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. When enabled, iframe history skipping is also enabled by default (see checkIframeHistoryOnBack).
• Example:

  [showHistoryBack]="true"

checkIframeHistoryOnBack

• Type: boolean | undefined
• Default: undefined (falls back to showHistoryBack() value)
• Description: When enabled, the back button keeps calling history.back() until the URL actually changes. Use on pages with iframe embeds (e.g. Power BI paginated reports) that push extra browser history entries without changing the parent URL. Set to false to force a single history.back() even when showHistoryBack is true.
• Example:

  <ngx-st-card
    [title]="'Power BI Report'"
    [showHistoryBack]="true"
    [checkIframeHistoryOnBack]="true">
  </ngx-st-card>

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.