Card Component - Complete Documentation

Table of Contents

• Overview
• Installation
• Basic Usage
• Inputs
• Content Projection
• Usage Examples
• Best Practices

Overview

The ngx-st-card component is a styled card wrapper with header, actions, and content areas. Features include:

• Title with optional back navigation
• Create button with custom link
• Action menu and action button support
• History back button
• Configurable body padding
• Material Design styling

Installation

npm install ngx-st-card

Import the module:

import { StCardModule } from 'ngx-st-card';

@NgModule({
  imports: [StCardModule]
})
export class AppModule { }

Basic Usage

<ngx-st-card title="User Details">
  <p>Card content goes here</p>
</ngx-st-card>

Inputs

title

• Type: string
• Default: undefined
• Description: Title text displayed in the card header.
• Example:

  title="User Profile"
  title="Product Details"
  [title]="dynamicTitle"

createLink

• Type: string[]
• Default: undefined
• Description: Router link array for the create button. When provided, shows a create button in the header.
• Example:

  [createLink]="['/users', 'create']"
  [createLink]="['/products', 'new']"

backLink

• Type: string[]
• Default: undefined
• Description: Router link array for the back button. When provided, shows a back button in the header.
• Example:

  [backLink]="['/users']"
  [backLink]="['/dashboard']"

showHistoryBack

• Type: boolean
• Default: false
• Description: Shows a back button that uses browser history (Location.back()). Alternative to backLink.
• Example:

  [showHistoryBack]="true"

actionMenu

• Type: MenuElementModel[]
• Default: undefined
• Description: Array of menu items to display in the actions dropdown menu. Requires ngx-st-dynamic-menu types.
• Example:

  actionMenu: MenuElementModel[] = [
    { label: 'Edit', icon: 'edit', action: () => this.edit() },
    { label: 'Delete', icon: 'delete', action: () => this.delete() }
  ];

  [actionMenu]="actionMenu"

actionButton

• Type: MenuElementModel
• Default: undefined
• Description: Single action button to display in the header (not in dropdown).
• Example:

  actionButton: MenuElementModel = {
    label: 'Save',
    icon: 'save',
    action: () => this.save()
  };

  [actionButton]="actionButton"

noBodyTopPadding

• Type: boolean
• Default: false
• Description: Removes top padding from the card body. Useful for tables or other content that needs to start at the top.
• Example:

  [noBodyTopPadding]="true"

createLinkLabel

• Type: string
• Default: 'Create'
• Description: Custom label for the create button.
• Example:

  createLinkLabel="Add New"
  createLinkLabel="New Product"

Content Projection

The component uses content projection for the card body:

<ngx-st-card title="My Card">
  <!-- All content here goes into the card body -->
  <p>Any HTML content</p>
  <div>Components, forms, tables, etc.</div>
</ngx-st-card>

Usage Examples

Example 1: Simple Card

// Component
@Component({
  selector: 'app-user-profile',
  template: `
    <ngx-st-card title="User Profile">
      <div class="profile-content">
        <p><strong>Name:</strong> {{ user.name }}</p>
        <p><strong>Email:</strong> {{ user.email }}</p>
        <p><strong>Role:</strong> {{ user.role }}</p>
      </div>
    </ngx-st-card>
  `
})
export class UserProfileComponent {
  user = {
    name: 'John Doe',
    email: '[email protected]',
    role: 'Administrator'
  };
}

Example 2: Card with Back Button

// Component
@Component({
  selector: 'app-user-details',
  template: `
    <ngx-st-card 
      title="User Details"
      [backLink]="['/users']">
      <p>User information here...</p>
    </ngx-st-card>
  `
})
export class UserDetailsComponent { }

Example 3: Card with History Back

// Component
@Component({
  selector: 'app-product-view',
  template: `
    <ngx-st-card 
      title="Product Details"
      [showHistoryBack]="true">
      <div>Product content...</div>
    </ngx-st-card>
  `
})
export class ProductViewComponent { }

Example 4: Card with Create Button

// Component
@Component({
  selector: 'app-users-list',
  template: `
    <ngx-st-card 
      title="Users"
      [createLink]="['/users', 'create']"
      createLinkLabel="Add User">
      <table>
        <!-- Users table -->
      </table>
    </ngx-st-card>
  `
})
export class UsersListComponent { }

Example 5: Card with Action Menu

// Component
@Component({
  selector: 'app-document-view',
  template: `
    <ngx-st-card 
      title="Document"
      [showHistoryBack]="true"
      [actionMenu]="documentActions">
      <div>Document content...</div>
    </ngx-st-card>
  `
})
export class DocumentViewComponent {
  documentActions: MenuElementModel[] = [
    {
      label: 'Edit',
      icon: 'edit',
      action: () => this.editDocument()
    },
    {
      label: 'Download',
      icon: 'download',
      action: () => this.downloadDocument()
    },
    {
      label: 'Share',
      icon: 'share',
      action: () => this.shareDocument()
    },
    {
      label: 'Delete',
      icon: 'delete',
      action: () => this.deleteDocument()
    }
  ];
  
  editDocument(): void {
    console.log('Edit document');
  }
  
  downloadDocument(): void {
    console.log('Download document');
  }
  
  shareDocument(): void {
    console.log('Share document');
  }
  
  deleteDocument(): void {
    console.log('Delete document');
  }
}

Example 6: Card with Action Button

// Component
@Component({
  selector: 'app-form-card',
  template: `
    <ngx-st-card 
      title="Edit Profile"
      [showHistoryBack]="true"
      [actionButton]="saveButton">
      <form [formGroup]="profileForm">
        <!-- Form fields -->
      </form>
    </ngx-st-card>
  `
})
export class FormCardComponent {
  profileForm = this.fb.group({
    name: [''],
    email: ['']
  });
  
  saveButton: MenuElementModel = {
    label: 'Save Changes',
    icon: 'save',
    action: () => this.save()
  };
  
  constructor(private fb: FormBuilder) {}
  
  save(): void {
    if (this.profileForm.valid) {
      console.log('Saving:', this.profileForm.value);
    }
  }
}

Example 7: Card with Table (No Top Padding)

// Component
@Component({
  selector: 'app-data-table-card',
  template: `
    <ngx-st-card 
      title="Products"
      [createLink]="['/products', 'create']"
      createLinkLabel="New Product"
      [noBodyTopPadding]="true">
      <ngx-st-material-table
        [data]="products"
        [initColumns]="columns">
      </ngx-st-material-table>
    </ngx-st-card>
  `
})
export class DataTableCardComponent {
  products = [...];
  columns = [...];
}

Example 8: Card with Multiple Actions

// Component
@Component({
  selector: 'app-project-details',
  template: `
    <ngx-st-card 
      [title]="project.name"
      [backLink]="['/projects']"
      [createLink]="['/projects', project.id, 'tasks', 'create']"
      createLinkLabel="Add Task"
      [actionMenu]="projectActions"
      [actionButton]="primaryAction">
      
      <div class="project-info">
        <p>{{ project.description }}</p>
        <p>Status: {{ project.status }}</p>
        <p>Progress: {{ project.progress }}%</p>
      </div>
      
      <h3>Tasks</h3>
      <div *ngFor="let task of project.tasks">
        {{ task.name }}
      </div>
    </ngx-st-card>
  `
})
export class ProjectDetailsComponent {
  project = {
    id: 1,
    name: 'Project Alpha',
    description: 'Important project',
    status: 'In Progress',
    progress: 65,
    tasks: [...]
  };
  
  primaryAction: MenuElementModel = {
    label: 'Complete Project',
    icon: 'check_circle',
    action: () => this.completeProject()
  };
  
  projectActions: MenuElementModel[] = [
    {
      label: 'Edit Project',
      icon: 'edit',
      action: () => this.editProject()
    },
    {
      label: 'Export',
      icon: 'file_download',
      action: () => this.exportProject()
    },
    {
      label: 'Archive',
      icon: 'archive',
      action: () => this.archiveProject()
    },
    {
      label: 'Delete',
      icon: 'delete',
      action: () => this.deleteProject()
    }
  ];
  
  completeProject(): void {
    console.log('Complete project');
  }
  
  editProject(): void {
    console.log('Edit project');
  }
  
  exportProject(): void {
    console.log('Export project');
  }
  
  archiveProject(): void {
    console.log('Archive project');
  }
  
  deleteProject(): void {
    console.log('Delete project');
  }
}

Example 9: Dynamic Title Card

// Component
@Component({
  selector: 'app-dynamic-card',
  template: `
    <ngx-st-card 
      [title]="cardTitle"
      [showHistoryBack]="true"
      [actionMenu]="getActions()">
      <div>Content based on {{ entityType }}</div>
    </ngx-st-card>
  `
})
export class DynamicCardComponent implements OnInit {
  entityType = 'user';
  entityId = 123;
  
  get cardTitle(): string {
    return `${this.entityType} #${this.entityId}`;
  }
  
  ngOnInit(): void {
    // Load entity data
  }
  
  getActions(): MenuElementModel[] {
    return [
      {
        label: 'Edit',
        icon: 'edit',
        action: () => this.edit()
      },
      {
        label: 'Delete',
        icon: 'delete',
        action: () => this.delete()
      }
    ];
  }
  
  edit(): void {
    console.log('Edit', this.entityType);
  }
  
  delete(): void {
    console.log('Delete', this.entityType);
  }
}

Best Practices

1. Use descriptive titles:

   title="User Profile"  <!-- Good -->
   title="Details"       <!-- Less descriptive -->

2. Choose appropriate navigation:

   <!-- Use backLink for specific routes -->
   [backLink]="['/users']"
      
   <!-- Use showHistoryBack for general back -->
   [showHistoryBack]="true"

3. Group related actions in menu:

   actionMenu = [
     { label: 'Edit', ... },
     { label: 'Duplicate', ... },
     { label: 'Delete', ... }
   ];

4. Use actionButton for primary action:

   actionButton = { label: 'Save', icon: 'save', ... };

5. Remove top padding for tables:

   [noBodyTopPadding]="true"  <!-- For tables -->

6. Provide clear create button labels:

   createLinkLabel="Add User"
   createLinkLabel="New Product"

MenuElementModel Interface

When using actionMenu or actionButton:

interface MenuElementModel {
  label: string;              // Button/menu item label
  icon?: string;              // Material icon name
  action?: () => void;        // Click handler function
  url?: string[];             // Router link (alternative to action)
  disabled?: boolean;         // Disable the action
  color?: 'primary' | 'accent' | 'warn';  // Button color
}

Common Patterns

Pattern 1: List Card

Card with create button and table content, no top padding.

Pattern 2: Details Card

Card with back button and action menu for entity operations.

Pattern 3: Form Card

Card with back button and save action button.

Pattern 4: Dashboard Card

Simple card with title and content, no actions.

Component Structure

<ngx-st-card>
  <!-- Header (automatic) -->
  ├── Back Button (optional)
  ├── Title
  ├── Create Button (optional)
  ├── Action Button (optional)
  └── Action Menu (optional)
  
  <!-- Body (content projection) -->
  └── Your content here
</ngx-st-card>

Styling

The component includes base Material Design card styling. You can override styles:

ngx-st-card {
  /* Customize card appearance */
}

ngx-st-card ::ng-deep .card-header {
  /* Customize header */
}

ngx-st-card ::ng-deep .card-body {
  /* Customize body */
}

This documentation covers all inputs and usage patterns for the Card component.