Skip to content
PDF

SmartPages commands

Integrate SmartUI Commands in your workflow

Introduction

SmartUI commands provide a powerful way to interact with the SmartUI framework through the Radio channel messaging system. These commands enable seamless communication between different components in SmartUI applications, allowing developers to create dynamic, interactive user interfaces without tight coupling between components.

Module Suite plays a crucial role in seamlessly incorporating SmartUI commands into your enterprise content management ecosystem. By leveraging the Radio channel messaging system, Module Suite empowers you to:

  1. Decouple components: Enable loose coupling between UI components through event-driven communication, making applications more maintainable and extensible.

  2. Enhance user experience: Display toolbars, viewers, side panels, and other UI elements dynamically based on user interactions and application state.

  3. Simplify integration: Use a consistent command pattern across all SmartUI interactions, reducing complexity and learning curve.

  4. Enable dynamic content: Load Smart Pages, Intelligent Viewing, and other content on-demand without full page refreshes.

  5. Improve responsiveness: Show loading indicators and messages to provide feedback during asynchronous operations.

  6. Support flexible layouts: Open side panels, display viewers, and manage multiple UI components simultaneously with precise control.

By integrating SmartUI commands through Module Suite, organizations can create rich, interactive user interfaces that enhance productivity, improve user experience, and provide seamless integration with Extended ECM capabilities.

SmartUI Commands Integration Considerations

While SmartUI commands offer significant benefits, it's important to consider factors such as command naming conventions, parameter validation, and error handling when integrating commands into your applications. Module Suite provides the necessary tools and patterns to address these considerations effectively.

Architecture and Communication

SmartUI commands use the Radio channel messaging system as a message bus for inter-component communication. This architecture enables decoupled, event-driven interactions between different parts of SmartUI applications.

Here's an overview of how the communication works:

flowchart TD
    subgraph App["SmartUI Application"]
        Component1[Component 1]
        Component2[Component 2]
        Component3[Component 3]
        Radio[Radio Channel<br/>ampagenotify]
    end

    Handler1[Toolbar Handler]
    Handler2[Viewer Handler]
    Handler3[Panel Handler]
    Handler4[Message Handler]

    Component1 -->|trigger command| Radio
    Component2 -->|trigger command| Radio
    Component3 -->|trigger command| Radio

    Radio -->|route command| Handler1
    Radio -->|route command| Handler2
    Radio -->|route command| Handler3
    Radio -->|route command| Handler4

    Handler1 -->|update UI| Component1
    Handler2 -->|update UI| Component2
    Handler3 -->|update UI| Component3

    style App fill:#f9f,stroke:#333,stroke-width:2px
    style Radio fill:#bbf,stroke:#333,stroke-width:2px
    style Handler1 fill:#bfb,stroke:#333,stroke-width:2px
    style Handler2 fill:#bfb,stroke:#333,stroke-width:2px
    style Handler3 fill:#bfb,stroke:#333,stroke-width:2px
    style Handler4 fill:#bfb,stroke:#333,stroke-width:2px

Radio Channel Communication

All SmartUI commands are triggered through the ampagenotify Radio channel, which acts as a centralized message bus. This approach provides:

  • Decoupled communication: Components don't need direct references to each other
  • Event-driven architecture: Commands are triggered as events, enabling reactive programming patterns
  • Consistent interface: All commands follow the same pattern, making them easy to learn and use
  • Extensibility: New commands can be added without modifying existing components

Command Pattern

All SmartUI commands follow this consistent pattern:

amChannel.trigger("smartui:command:name", parameters);

Where: - smartui:command:name is the command identifier - parameters is an object containing the command-specific configuration

Typical Communication Sequence

Below is a diagram illustrating a typical communication sequence when using SmartUI commands:

sequenceDiagram
    participant User
    participant Component
    participant Radio as Radio Channel
    participant Handler
    participant UI

    User->>Component: User interaction
    Component->>Radio: trigger("smartui:command:name", params)
    Radio->>Handler: Route command to handler
    Handler->>Handler: Process command
    Handler->>UI: Update UI elements
    UI->>User: Display result

This pattern allows for clean separation of concerns, where components trigger commands without needing to know the implementation details of how those commands are handled.

Radio Channel Initialization

Before using any SmartUI commands, you need to initialize the Radio channel:

csui.onReady2(["csui/lib/radio"], function(Radio){
    var amChannel = Radio.channel('ampagenotify');
    // Now you can use amChannel.trigger() to send commands
});

Components of the SmartUI Commands Integration

Module Suite provides a comprehensive set of command handlers to enable seamless integration with SmartUI components. These handlers work together to offer a robust and flexible command-driven experience within the Extended ECM environment.

Command Handlers

SmartUI commands are processed by dedicated handlers that manage different aspects of the UI:

  • Toolbar Handler: Manages action toolbars for nodes
  • Viewer Handler: Handles Intelligent Viewing (IV) display
  • Smart Page Handler: Manages Smart Page rendering
  • Panel Handler: Controls side panel display and navigation
  • Loader Handler: Manages loading indicators
  • Message Handler: Displays global notifications
  • Search Handler: Handles search interface navigation
graph TD
    A[SmartUI Commands] --> B[Command Handlers]
    B --> C[Toolbar Handler]
    B --> D[Viewer Handler]
    B --> E[Smart Page Handler]
    B --> F[Panel Handler]
    B --> G[Loader Handler]
    B --> H[Message Handler]
    B --> I[Search Handler]

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#bbf,stroke:#333,stroke-width:2px

Integration Use Cases

Module Suite offers various capabilities for integrating SmartUI commands into your Extended ECM environment. Let's explore common use cases and how to implement them.

Displaying Action Toolbars

Action toolbars allow users to interact with content nodes through a contextual menu of available actions. This functionality is valuable for implementing:

  • Quick access to common actions (open, download, delete, etc.)
  • Contextual action menus based on node type and permissions
  • Customizable command sets for different use cases
  • Inline action bars for table rows or list items

Example: Basic Toolbar Display

Here's a simple example of how to display an action toolbar:

csui.onReady2(["csui/lib/radio"], function(Radio){
    var amChannel = Radio.channel('ampagenotify');

    // Show toolbar for node 2000 with default container
    amChannel.trigger("smartui:show:toolbar", {
        id: 2000
        // el is optional, defaults to ".actions_2000"
    });
});

csui.onReady2(["csui/lib/radio"], function(Radio){
    var amChannel = Radio.channel('ampagenotify');

    // Show toolbar with custom container and specific commands
    amChannel.trigger("smartui:show:toolbar", {
        id: 2000,
        el: ".am-content-container",
        separateCommands: true,
        commands: ["open", "download", "delete"],
        blacklistedCommands: ["share"],
        delayRestCommands: false,
        text: {
            dropDownText: "More actions"
        },
        dropDownIconName: "csui_action_more32",
        addGroupSeparators: false,
        inlineBarStyle: "csui-table-actionbar-bubble",
        forceInlineBarOnClick: false,
        showInlineBarOnHover: true,
        error: {
            type: "error",
            text: "Unable to load toolbar",
            details: ""
        }
    });
});

The first example demonstrates the simplest usage, where only the id parameter is required. The toolbar will be displayed in the default container .actions_{id}.

The second example shows a more advanced configuration with: - Custom container selector - Specific commands to display - Blacklisted commands to exclude - Custom styling and behavior options - Error handling configuration

Command Filtering

Use commands to specify exactly which actions to show, or use blacklistedCommands to exclude specific actions from the default command set.

Displaying Document Viewers

Intelligent Viewing (IV) allows users to view documents directly within the application without leaving the current context. This functionality is valuable for implementing:

  • Inline document preview
  • Document comparison (multiple versions)
  • Seamless document viewing experience
  • Integration with Smart Pages for empty states

Example: Document Viewer Display

csui.onReady2(["csui/lib/radio"], function(Radio){
    var amChannel = Radio.channel('ampagenotify');

    // Show Intelligent Viewing for a single node
    amChannel.trigger("smartui:show:iv", {
        id: "docpreview_1",
        target: ".am-content-container",
        node: 2000,
        css: {
            height: "100%",
            position: "relative"
        },
        html: "",
        error: {
            type: "error",
            text: "Unable to load viewer",
            details: ""
        }
    });
});

csui.onReady2(["csui/lib/radio"], function(Radio){
    var amChannel = Radio.channel('ampagenotify');

    // Show comparison view for multiple versions
    amChannel.trigger("smartui:show:iv", {
        id: "docpreview_compare",
        target: ".am-content-container",
        node: [
            {id: 2000, version_number: 1},
            {id: 2000, version_number: 2}
        ],
        mode: "compare",
        css: {
            height: "100%",
            position: "relative"
        },
        error: {
            type: "error",
            text: "Unable to load viewer",
            details: ""
        }
    });
});

csui.onReady2(["csui/lib/radio"], function(Radio){
    var amChannel = Radio.channel('ampagenotify');

    // Show viewer with Smart Page as empty view
    amChannel.trigger("smartui:show:iv", {
        id: "docpreview_1",
        target: ".am-content-container",
        node: 2000,
        source: {
            source: 123,
            parameters: []
        },
        css: {
            height: "100%",
            position: "relative"
        },
        error: {
            type: "error",
            text: "Unable to load viewer",
            details: ""
        }
    });
});

The first example shows the basic usage for displaying a single document. The viewer will show the document and when closed, will display the empty HTML template.

The second example demonstrates the comparison view mode, which is useful for comparing different versions of the same document. When multiple nodes with the same ID are provided, the system automatically uses version_number as the identifier.

The third example shows how to use a Smart Page as the empty view. When the viewer is closed, instead of showing HTML, it will load and display the Smart Page specified in the source parameter.

Empty View Options

You can use either html (for static HTML templates) or source (for dynamic Smart Page content) as the empty view. If neither is provided, the container will be empty when the viewer is closed.

Node Parameter Flexibility

The node parameter accepts: - A single number: node: 2000 - An array of numbers: node: [2000, 2001, 2002] - An array of objects: node: [{id: 2000, version_number: 1}, {id: 2000, version_number: 2}]

Displaying Smart Pages

Smart Pages can be loaded dynamically into containers, enabling dynamic content rendering based on server-side processing. This functionality is valuable for implementing:

  • Dynamic content loading without page refresh
  • Context-aware content display
  • Reusable Smart Page components
  • Flexible content rendering

Example: Loading Smart Pages

csui.onReady2(["csui/lib/radio"], function(Radio){
    var amChannel = Radio.channel('ampagenotify');

    // Show Smart Page with ID 2467915
    amChannel.trigger("smartui:show:smartpage", {
        id: "smartpage_1",
        target: ".am-content-container",
        css: {
            height: "100%"
        },
        dataSource: {
            source: 2467915,
            parameters: [
                {name: "target_folder", value: "2000"}
            ]
        },
        error: {
            type: "error",
            text: "Unable to load smart page",
            details: ""
        }
    });
});

csui.onReady2(["csui/lib/radio"], function(Radio){
    var amChannel = Radio.channel('ampagenotify');

    // Show custom HTML content
    amChannel.trigger("smartui:show:smartpage", {
        id: "custom_html_1",
        target: ".am-content-container",
        css: {
            height: "100%"
        },
        html: "<div><h1>Custom Content</h1><p>This is custom HTML content.</p></div>"
    });
});

The first example demonstrates loading a Smart Page script dynamically. The dataSource parameter specifies which Smart Page script to execute and what parameters to pass to it. This is useful when you want to display dynamic content that depends on server-side processing.

The second example shows how to display static HTML content directly. This is useful for simple content that doesn't require server-side processing or when you want to display custom HTML templates.

Mutually Exclusive Parameters

The dataSource and html parameters are mutually exclusive. You must provide either one or the other, but not both.

Displaying Side Panels

Side panels provide a slide-in interface for displaying additional content without navigating away from the main view. This functionality is valuable for implementing:

  • Contextual information panels
  • Search and filter interfaces
  • Multi-step workflows
  • Document viewing in side panels

Example: Side Panel Display

csui.onReady2(["csui/lib/radio"], function(Radio){
    var amChannel = Radio.channel('ampagenotify');

    // Show side panel with Smart Page
    amChannel.trigger("smartui:show:sidepanel", {
        id: "myCustomPanelRight",  // Remember this ID to close the panel later
        panel: {
            width: 40,
            cssClass: "am_panel_class",
            layout: {
                header: true,
                footer: true,
                mask: false,
                resize: true
            },
            slides: [{
                title: "Search",
                subTitle: "",
                dataSource: {
                    source: 123,
                    parameters: [
                        {name: "am_ActionParams", value: "search"}
                    ]
                }
            }]
        }
    });
});

csui.onReady2(["csui/lib/radio"], function(Radio){
    var amChannel = Radio.channel('ampagenotify');

    // Show side panel with multiple slides
    amChannel.trigger("smartui:show:sidepanel", {
        id: "multiSlidePanel",
        panel: {
            width: 50,
            layout: {
                header: true,
                footer: true,
                resize: true
            },
            slides: [
                {
                    title: "Search",
                    subTitle: "Find documents",
                    dataSource: {
                        source: 123,
                        parameters: [{name: "am_ActionParams", value: "search"}]
                    }
                },
                {
                    title: "Filters",
                    subTitle: "Apply filters",
                    dataSource: {
                        source: 456,
                        parameters: [{name: "am_ActionParams", value: "filters"}]
                    }
                }
            ]
        }
    });
});

The first example shows a basic side panel with a single slide. The panel will slide in from the right side of the screen, occupying 40% of the viewport width.

The second example demonstrates a panel with multiple slides. Users can navigate between slides using the panel's navigation controls. Each slide can have its own Smart Page content.

Panel Width

The width parameter is specified as a percentage of the viewport width (vw). Common values are 30, 40, 50, or 100 for full-width panels.

Command Key

The id parameter is crucial as it serves as the command_key for closing the panel later. Make sure to use a unique identifier.

Displaying Loading Indicators

Loading indicators provide visual feedback during asynchronous operations, improving user experience by indicating that the system is processing a request.

Example: Loading Indicators

csui.onReady2(["csui/lib/radio"], function(Radio){
    var amChannel = Radio.channel('ampagenotify');

    // Show loader with custom label (must be manually hidden)
    amChannel.trigger("smartui:loader", {
        xhr: null,
        options: {
            label: "Loading documents..."
        }
    });

    // Hide loader manually after operation completes
    setTimeout(function() {
        // Use smartui:hide:loader if implemented
        // Or remove the loader element from DOM
    }, 5000);
});

csui.onReady2(["csui/lib/radio"], function(Radio){
    var amChannel = Radio.channel('ampagenotify');

    // Show loader tied to an AJAX request (auto-hides on completion)
    var xhr = $.ajax({
        url: "/api/data",
        method: "GET"
    });

    amChannel.trigger("smartui:loader", {
        xhr: xhr,
        options: {
            label: "Fetching data..."
        }
    });

    // Loader will automatically hide when AJAX request completes
    // (either success or error)
});

The first example shows a manual loader that must be explicitly hidden. This is useful when you need to control exactly when the loader disappears, such as after multiple asynchronous operations complete.

The second example demonstrates an auto-hiding loader. By providing a jQuery XHR object, the loader will automatically hide when the AJAX request completes, whether it succeeds or fails. This is the recommended approach for single AJAX operations.

Auto-hide Behavior

When you provide an xhr object, the loader uses the jQuery promise system to automatically hide when the request completes. This eliminates the need for manual cleanup code.

Displaying Messages

Global messages provide user feedback for operations, displaying success, error, warning, or informational notifications.

Example: Global Messages

csui.onReady2(["csui/lib/radio"], function(Radio){
    var amChannel = Radio.channel('ampagenotify');

    // Show success message
    amChannel.trigger("smartui:message", {
        type: "success",
        text: "Document saved successfully",
        details: "The document has been saved to the repository",
        options: null
    });

    // Show error message
    amChannel.trigger("smartui:message", {
        type: "error",
        text: "Operation failed",
        details: "Unable to save the document. Please try again.",
        options: null
    });
});

csui.onReady2(["csui/lib/radio"], function(Radio){
    var amChannel = Radio.channel('ampagenotify');

    // Show warning message
    amChannel.trigger("smartui:message", {
        type: "warning",
        text: "Warning",
        details: "This action cannot be undone",
        options: null
    });

    // Show info message
    amChannel.trigger("smartui:message", {
        type: "info",
        text: "Information",
        details: "Your session will expire in 5 minutes",
        options: null
    });
});

Messages are displayed globally and automatically dismiss after a timeout period. The type parameter determines the visual style and icon of the message:

  • success: Green message with checkmark icon
  • error: Red message with error icon
  • warning: Yellow/orange message with warning icon
  • info: Blue message with information icon

The details parameter provides additional context that can be expanded by the user.

Message Visibility

Messages are displayed in a non-intrusive manner and automatically disappear after a few seconds. Users can manually dismiss them if needed.

Closing Panels

Panels can be closed programmatically using specific close commands that match the panel's command key.

Example: Closing Panels

csui.onReady2(["csui/lib/radio"], function(Radio){
    var amChannel = Radio.channel('ampagenotify');

    // Open a panel
    amChannel.trigger("smartui:show:sidepanel", {
        id: "myCustomPanelRight",  // This is the command_key
        panel: {
            width: 40,
            layout: { header: true, footer: true },
            slides: [{
                title: "Search",
                dataSource: {
                    source: 123,
                    parameters: []
                }
            }]
        }
    });

    // Close the panel using the command_key
    amChannel.trigger("smartui:dialog:myCustomPanelRight:hide");
});

csui.onReady2(["csui/lib/radio"], function(Radio){
    var amChannel = Radio.channel('ampagenotify');

    // Open IV side panel
    amChannel.trigger("smartui:show:iv:sidepanel", {
        id: "docpreview_panel",  // This is the command_key
        node: 2000,
        panel: {
            width: 100,
            layout: {
                header: false,
                footer: false,
                resize: true
            }
        }
    });

    // Close the IV side panel using the command_key
    amChannel.trigger("smartui:hide:docpreview_panel:iv:sidepanel");
});

The first example shows how to close a side panel opened with smartui:show:sidepanel. The command pattern is smartui:dialog:{command_key}:hide, where {command_key} matches the id used when opening the panel.

The second example demonstrates closing an IV side panel opened with smartui:show:iv:sidepanel. The command pattern is smartui:hide:{command_key}:iv:sidepanel.

Command Key Matching

The command_key in the hide command must exactly match the id used when opening the panel. If they don't match, the panel won't close.

Using Commands from Tiles Widgets

SmartUI commands can also be triggered from Tiles Widgets in Smart Pages, enabling command-driven interactions directly from tile components.

Example: Tile Widget Command

[
    size: 6,
    styleclass: "",
    command: "smartui:show:toolbar",      // Custom command name
    action: "notify",                       // Action type
    params: JsonOutput.toJson([            // Parameters as JSON
        id: 2000,
        el: ".am-content-container",
        separateCommands: true,
        commands: ["open", "download", "delete"],
        blacklistedCommands: ["share"],
        delayRestCommands: false,
        text: [
            dropDownText: "More actions"
        ],
        dropDownIconName: "csui_action_more32",
        addGroupSeparators: false,
        inlineBarStyle: "csui-table-actionbar-bubble",
        forceInlineBarOnClick: false,
        showInlineBarOnHover: true,
        error: [
            type: "error",
            text: "Unable to load toolbar",
            details: ""
        ]
    ]),
    newtab: false,
    type: 'blue',
    front: [
        body: "Show Toolbar",
        title: "Show Toolbar"
    ]
]

This example shows how to configure a tile widget to trigger a SmartUI command when clicked. The command parameter specifies the command name, action is set to "notify" to use the Radio channel, and params contains the command parameters as a JSON string.

Best Practices

When working with SmartUI commands, consider the following best practices:

Do: - Always use unique id values for each viewer/panel instance - Provide error handlers in your command parameters - Use the xhr parameter in smartui:loader for automatic loader dismissal - Use descriptive command_key values (e.g., "searchPanel" instead of "panel1") - Initialize the Radio channel before using commands - Handle errors gracefully with appropriate error configurations

Don't: - Don't use the same id for multiple instances - Don't hardcode node IDs - use variables or parameters - Don't use generic command_key values that might conflict - Don't forget to close panels when they're no longer needed - Don't ignore error handling - always provide error configurations

Command Organization

Organize your commands logically and use consistent naming conventions. This will make your code more maintainable and easier to debug.

Memory Management

Be mindful of opening multiple panels or viewers simultaneously. Consider closing unused instances to prevent memory leaks and performance issues.

Summary

This guide covered all the common SmartUI commands:

  • smartui:show:toolbar - Display action toolbar
  • smartui:show:iv - Display Intelligent Viewing in container
  • smartui:show:smartpage - Display Smart Page in container
  • smartui:show:sidepanel - Open side panel with Smart Page
  • smartui:show:iv:sidepanel - Open side panel with Intelligent Viewing
  • smartui:loader - Show loading indicator
  • smartui:message - Show global message
  • smartui:search - Open search interface
  • smartui:dialog:{command_key}:hide - Close side panel
  • smartui:hide:{command_key}:iv:sidepanel - Close IV side panel

All commands use the ampagenotify Radio channel for communication and follow consistent parameter patterns for easy integration into your SmartUI applications.