Skip to content

Core Concepts

Jump to bottom
Michael19842 edited this page Nov 9, 2025 · 2 revisions

Core Concepts

Understanding the core concepts of MvRAdaptiveCards will help you build powerful and maintainable cards. The module is designed with several key concepts in mind:

1: Open source - MvRAdaptiveCards is fully open source, allowing you to inspect, modify, and contribute to the codebase. Collaborate on GitHub is encouraged to help improve the module for everyone and is therefore transparent in its development.

2: Strictly limited to Adaptive Cards - The module focuses exclusively on Adaptive Cards, ensuring that all features and functions align with the Adaptive Cards framework. This specialization allows for deep integration and support for the latest Adaptive Card features. This focus ensures that users can rely on the module for all their Adaptive Card needs without unnecessary bloat or unrelated features.

3: Built in/for PowerShell - The module is designed specifically for PowerShell users, leveraging PowerShell's strengths and idioms. This makes it easy for PowerShell users to adopt and use the module effectively. Users familiar with PowerShell will find the syntax and patterns intuitive and aligned with their existing knowledge.

4: Ready to go - The module is designed to be ready for immediate use, with sensible defaults and easy setup. Users can quickly create and display Adaptive Cards without extensive configuration, making it accessible for both beginners and experienced users. The module will use default settings to streamline the card creation process.

5: Strict dependency management - The module minimizes external dependencies, leveraging only well-known open source solutions and Microsoft-defined libraries/CDN-sources where necessary. This approach reduces potential risks associated with third-party dependencies, such as security vulnerabilities or compatibility issues. By relying on well-established and trusted sources, the module ensures stability and reliability for users.

Note: While the module minimizes dependencies, it may still utilize certain Microsoft-defined libraries or CDN sources to ensure compatibility with the Adaptive Cards framework.

6: No sketchy stuff - The module adheres to best practices in PowerShell module development, ensuring that it is secure, reliable, and maintainable. Users can trust that the module follows established guidelines and standards, providing a solid foundation for building Adaptive Cards. There is no telemetry, data collection, or any form of tracking implemented in the module. User privacy and security are prioritized, ensuring that no personal or usage data is collected or transmitted. (Microsoft libraries used are subject to their own privacy policies and terms of use.) This commitment to quality ensures that users can confidently use the module in their projects without concerns about security or reliability.

Card Structure

An Adaptive Card has a hierarchical structure:

AdaptiveCard
├── Elements (Text, Images, Inputs, etc.)
├── Containers (Group elements)
│   └── Elements
└── Actions (Buttons, Submit, etc.)

Basic Structure Example

New-AdaptiveCard {
    # Header
    New-CardTextBlock -Text "Card Title" -Size Large -Weight Bolder
    
    # Content
    New-CardContainer -Items {
        New-CardTextBlock -Text "Content goes here"
    }
    
    # Actions
    New-CardActionSet -Actions {
        New-CardActionSubmit -Title "Submit"
    }
}

Design Patterns

The module is designed around several key patterns to facilitate card creation and card usage.

  1. Declarative Syntax: The module uses a declarative syntax that allows you to define your card structure in a clear and concise manner. This makes it easy to understand and modify your card layouts.

  2. Hierarchical Structure: The use of nested containers and elements reflects the hierarchical nature of Adaptive Cards. This allows for complex layouts to be built up from simple components.

  3. Reusable Components: The module encourages the creation of reusable card components. This means you can define a card layout once and reuse it across different cards, promoting consistency and reducing duplication. Through the use of templates, you can easily create dynamic cards that adapt to different data inputs.

  4. Integration with PowerShell: The module is designed to work seamlessly with PowerShell, leveraging its features and idioms. This makes it easy for PowerShell users to adopt and use the module effectively.

  5. Extensibility: The module is built to be extensible, allowing users to create custom elements and actions as needed. This ensures that the module can evolve with the needs of its users. These extensions can be easily integrated into the existing card structure.

Elements vs Containers vs Actions

Elements

Elements are the building blocks of a card. They display content but don't contain other elements.

Common Elements:

  • New-CardTextBlock - Display text
  • New-CardImage - Display images
  • New-CardIcon - Display Fluent UI icons
  • New-CardRichTextBlock - Rich formatted text
  • New-CardProgressBar - Progress indicators
  • New-CardBadge - Status badges
  • Charts: New-CardChartDonut, New-CardChartGauge, New-CardChartHorizontalBar

Input Elements:

  • New-CardInputText - Text input
  • New-CardInputNumber - Number input
  • New-CardInputDate - Date picker
  • New-CardInputTime - Time picker
  • New-CardInputToggle - Checkbox/toggle
  • New-CardInputChoiceSet - Radio buttons/dropdowns

Containers

Containers hold and organize other elements. They provide layout and grouping. Some containers can also be used like elements trough the intergrated features of the module. (e.g., FactSet, Table)

Common Containers:

  • New-CardContainer - General container with -Items { }
  • New-CardColumnSet - Multi-column layout with -Columns { }
  • New-CardColumn - Single column (inside ColumnSet)
  • New-CardFactSet - Key-value pairs
  • New-CardTable - Tabular data
  • New-CardImageSet - Image gallery
  • New-CardActionSet - Group of actions

Actions

Actions provide interactivity. They can only be added within an ActionSet, or in the actions area of the card. They can respond to click or tap events, triggering behaviors like submitting data or opening URLs.

Common Actions:

  • New-CardActionSubmit - Submit form data
  • New-CardActionOpenUrl - Open URL in browser
  • New-CardActionOpenUrlDialog - Open URL in modal dialog
  • New-CardActionToggleVisibility - Show/hide elements
  • New-CardActionShowCard - Expand to show another card

Scriptblock Pattern

The module uses scriptblocks for hierarchical structure:

# Parent element
New-CardContainer -Items {
    # Child elements inside scriptblock
    New-CardTextBlock -Text "Child 1"
    New-CardTextBlock -Text "Child 2"
    
    # Nested container
    New-CardColumnSet -Columns {
        New-CardColumn -Items {
            New-CardTextBlock -Text "In column"
        }
    }
}

Why Scriptblocks?

  • Natural hierarchy - Nesting reflects structure
  • Readable - Easy to understand card layout
  • Maintainable - Changes are localized
  • PowerShell native - Familiar syntax

Template System

Templates allow dynamic content using {{placeholder}} syntax:

Basic Templates

$data = @{
    name = "John Doe"
    email = "john@example.com"
}

New-AdaptiveCard {
    New-CardTextBlock -Text "Welcome {{name}}!" -Size Large
    New-CardTextBlock -Text "Email: {{email}}"
} | Build-CardFromTemplate -Data $data | Get-CardResponse -ViewMethod EdgeApp

Conditional Templates

New-AdaptiveCard {
    New-CardTextBlock -Text "Status: !{{if status=='active'}}Active!{{else}}Inactive!{{/if}}"
}

Template Tags

  • {{variable}} - Simple substitution
  • !{{if condition}}...!{{/if}} - Conditional content
  • !{{if condition}}...!{{else}}...!{{/if}} - If-else
  • !{{each items}}...!{{/each}} - Loops

Styling and Themes

Text Styling

New-CardTextBlock -Text "Styled Text" `
    -Size Large `
    -Weight Bolder `
    -Color Good `
    -HorizontalAlignment Center `
    -Wrap

Sizes: Small, Default, Medium, Large, ExtraLarge

Weights: Lighter, Default, Bolder

Colors: Default, Dark, Light, Accent, Good, Warning, Attention

Container Styling

New-CardContainer -Items {
    New-CardTextBlock -Text "Content"
} -Style Emphasis -Separator -Spacing Medium

Styles: Default, Emphasis, Good, Warning, Attention, Accent

Spacing: None, Small, Default, Medium, Large, ExtraLarge, Padding

Rich Text Formatting

New-CardRichTextBlock -Text @"
This is {{bold}}bold text{{/bold}} and this is {{color:Good}}green text{{/color}}.
You can {{italic}}combine{{/italic}} {{bold}}{{color:Accent}}multiple{{/color}}{{/bold}} styles.
"@

Supported tags:

  • Style: {{bold}}, {{italic}}, {{strikethrough}}, {{underline}}
  • Color: {{color:Good}}, {{color:Warning}}, etc.
  • Size: {{large}}, {{small}}, {{size:ExtraLarge}}
  • Font: {{monospace}}

Layout Patterns

Single Column (Default)

New-AdaptiveCard {
    New-CardTextBlock -Text "Item 1"
    New-CardTextBlock -Text "Item 2"
    New-CardTextBlock -Text "Item 3"
}

Multi-Column Layout

New-AdaptiveCard {
    New-CardColumnSet -Columns {
        New-CardColumn -Width "Auto" -Items {
            New-CardImage -Url "icon.png" -Size Small
        }
        New-CardColumn -Width "Stretch" -Items {
            New-CardTextBlock -Text "Title" -Weight Bolder
            New-CardTextBlock -Text "Description" -Wrap
        }
    }
}

Key-Value Display

New-AdaptiveCard {
    New-CardFactSet -Facts @{
        "Name" = "John Doe"
        "Email" = "john@example.com"
        "Status" = "Active"
    }
}

Element Visibility

Control element visibility dynamically:

Initial Visibility

New-AdaptiveCard {
    New-CardContainer -Id "Details" -Hidden -Items {
        New-CardTextBlock -Text "Hidden by default"
    }
    
    New-CardActionSet -Actions {
        New-CardActionToggleVisibility -Title "Show Details" -TargetElements "Details"
    }
}

Toggle Visibility

New-AdaptiveCard {
    New-CardContainer -Id "Page1" -Items {
        New-CardTextBlock -Text "Page 1"
        New-CardActionSet -Actions {
            New-CardActionToggleVisibility -Title "Next" -TargetElements "Page1", "Page2"
        }
    }
    
    New-CardContainer -Id "Page2" -Hidden -Items {
        New-CardTextBlock -Text "Page 2"
        New-CardActionSet -Actions {
            New-CardActionToggleVisibility -Title "Back" -TargetElements "Page1", "Page2"
        }
    }
}

Data Flow

Understanding how data flows through the module:

# 1. Build card structure
$card = New-AdaptiveCard {
    New-CardInputText -Id "input1"
}

# 2. Display and capture response
$response = $card | Get-CardResponse -ViewMethod EdgeApp

# 3. Process response
if ($response) {
    Write-Host "User entered: $($response.input1)"
}

Response Object

When a card is submitted, Get-CardResponse returns a hashtable with:

  • Input IDs as keys
  • User-entered values as values
  • Action data (if provided with -Data parameter)

Best Practices

  1. Use IDs consistently - Especially for inputs and toggle targets
  2. Provide labels - Always label input fields for accessibility
  3. Validate inputs - Use -IsRequired, -Regex, -MinLength, -MaxLength
  4. Organize with containers - Group related elements
  5. Use appropriate spacing - Control visual separation
  6. Test responsively - Cards should work at different widths
  7. Handle responses - Always check if response is not null
  8. Use templates for dynamic content - Separate data from structure

Next Steps

← Back to Getting Started | Next: Examples Gallery →

Clone this wiki locally