Skip to content

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"
        },
        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.

Options without effect

Some toolbar options are accepted but do not change the toolbar:

  • separateCommands and showInlineBarOnHover are always true. Passing false has no effect.
  • text.dropDownText and addGroupSeparators are overridden by the Smart View inline action bar defaults (the localized "More" label, no group separators).
  • The overflow icon is always csui_action_more32. The handler does not read a dropDownIconName parameter.

blacklistedCommands only filters the built-in command list, so it is ignored when you pass commands.

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. Always pass one of them: use html: "" to leave the container empty when the viewer is closed. If you pass neither, the viewer does not open and the error message is shown.

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). Supported values are 10 to 100 in steps of 10. Common values are 30, 40, 50, or 100 for full-width panels.

Always pass cssClass

The panel class is built from width and cssClass. If cssClass is missing, the panel gets a CSS class named undefined. Pass cssClass: "" when you do not need an extra class.

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..."
        }
    });

    // There is no command that hides this loader.
    // Pass a jqXHR (see the next example) when the loader must close by itself.
});
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 loader without a request. No Smart UI command hides it, so prefer the second form whenever the work is tied to a request.

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"
        ],
        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.

Using Commands from a Shell Component

A Shell Component does not use Radio. It publishes the command on the Shell event bus with the ampagenotify: prefix, and the Shell Tile triggers it on the classic channel:

const events = useEvents()   // capability "events"
events.publish('ampagenotify:smartui:dialog:myCustomPanelRight:hide')

Commands that render into an element selected with target or el (smartui:show:iv, smartui:show:smartpage, smartui:show:toolbar) cannot reach the component's own DOM. See Triggering Smart UI commands from a Shell Component for the commands that work, the side panel walkthroughs and the limits.

Command Reference

All commands and events in this section use the ampagenotify channel. <id> stands for the id you passed when you opened the panel, viewer or region.

Commands

Command Parameters Description
smartui:show:toolbar id, el, commands, blacklistedCommands, delayRestCommands, inlineBarStyle, forceInlineBarOnClick, error, callback Fetches node id with its actions and renders the Smart View inline action bar in the element matched by el (default .actions_<id>).
smartui:show:iv id, target, node, mode, html or source, css, error, callback Opens Intelligent Viewing inside the element matched by target.
smartui:show:iv:sidepanel id, node, panel, mode, error, callback Opens Intelligent Viewing in a side panel.
smartui:hide:<id>:iv:sidepanel none Closes the viewer side panel opened with that id.
smartui:destroy:iv none Closes every open viewer, inline or in a side panel.
smartui:show:smartpage id, target, dataSource or html, css, error, callback Renders Content Script output or an HTML template inside the element matched by target.
smartui:<id>:destroy:smartpage none Removes the content rendered by smartui:show:smartpage with that id.
smartui:show:sidepanel id, panel, error, callback Opens a side panel whose slides show Content Script output.
smartui:dialog:<id>:hide none Closes the side panel opened by smartui:show:sidepanel with that id.
smartui:search searchForm, searchQuery Starts a Smart View search.
smartui:message type, text, details, options Shows a global message. type is success, info, warning or error. Deprecated.
smartui:loader xhr, options Shows the global loader. With a jqXHR in xhr, the loader closes when the request completes.

Instance commands

The hide and destroy commands only exist after the panel, viewer or region with that id is open. A hide command for a smartui:show:sidepanel panel that is still loading its slides has no effect.

Common Parameters

Parameter Used by Description
id every show command A string that is unique on the page. It names the hide, destroy and event topics of that instance. You can reuse the same id to open the same panel again.
error every show command, smartui:show:toolbar { type, text, details, options }, shown as a global message when a node or a Content Script cannot be fetched or the viewer cannot load. Always pass it: without it, the failure itself causes a script error. smartui:show:smartpage needs it only with dataSource.
dataSource (source in smartui:show:iv) slides of smartui:show:sidepanel, smartui:show:smartpage, smartui:show:iv { source, parameters, uiParentID }. source is the node ID of the Content Script to run. parameters is a list of { name, value } (values are URL-encoded) or a query string. uiParentID is sent only when you set it. The script's output, or the whole response if there is no output, is inserted as HTML.
node smartui:show:iv, smartui:show:iv:sidepanel A node ID (number), a list of node IDs, or a list of { id, version_number } with numbers only. Any other value shows the message "Invalid node ID" or "Invalid node IDs". When all entries have the same id, the versions are kept apart by version_number, which is what mode: "compare" needs.
mode smartui:show:iv, smartui:show:iv:sidepanel "compare" opens the viewer in compare mode.
panel smartui:show:sidepanel, smartui:show:iv:sidepanel Side panel options, see Side Panel Options.
callback every show command, smartui:loader, smartui:message Function called with the created view or panel. Classic JavaScript only: a Shell Component or a Tiles Widget cannot pass a function.

Side Panel Options

The panel parameter of smartui:show:sidepanel and smartui:show:iv:sidepanel:

Parameter Description
width Width in percent of the window: 10 to 100 in steps of 10.
cssClass Extra CSS class for the panel. Always pass it, "" when you do not need one.
layout { header, footer, mask, resize }. Defaults: header: true, footer: true, mask: true, resize: false. With mask, a click outside the panel does not close it.
title Header title. The title and subTitle of the slide being shown replace it.
openFrom "right" (default) or "left".
footerButtonLabel Label of the Cancel button.
hideBackButton, hideNextButton true removes the Back or Next button that the panel adds between slides.
slides List of slides, at least one for smartui:show:sidepanel. A slide is { title, subTitle, dataSource, buttons, leftButtons, rightButtons }. Optional for smartui:show:iv:sidepanel: without slides, the panel forces header and footer on; with slides, the viewer becomes the content of the first slide.

smartui:show:sidepanel fetches the Content Script of every slide first. The panel opens only when all of them have answered. If one fails, the error message is shown and no panel opens.

The footer is shown when layout.footer is true. Add your own buttons to a slide with buttons (right side, after rightButtons) or leftButtons:

buttons: [
    { id: "approvePanel-submit", label: "Submit", type: "action", variant: "primary", close: true }
]
Attribute Description
id Identifies the button in smartui:sidepanel:button:clicked.
label Button text.
type "action" for your own buttons.
variant "primary" or "secondary".
close true closes the panel after the click.

The panel adds these buttons by itself, unless the slide already has a button of the same type:

Button type Shown on
Back back Every slide after the first one.
Next next Every slide except the last one.
Cancel (id csui-side-panel-cancel) cancel Every slide. Closes the panel.

Every click on a footer button, including Back, Next and Cancel, triggers smartui:sidepanel:button:clicked with the button attributes as the first argument.

Search Parameters

smartui:search saves the current page in the Smart View navigation history, so Back returns to it, and then clears the Smart View search query.

Parameter Description
searchForm Values for the search form, or null.
searchQuery Attributes set on the Smart View search query. Setting them starts the search and opens the results. The Navigation Pane snippet passes { query: "" }.

Events

The handlers trigger these events. Listen with amChannel.on(...).

Event Arguments Triggered when
smartui:sidepanel:button:clicked button attributes, event arguments A footer button is clicked in a smartui:show:sidepanel panel, in a Content Script command panel or in the Navigation Pane panel. The event is shared by all of them, so check the button id.
panel:button:click button attributes, event arguments A footer button is clicked in a Content Script command panel. Older name, triggered together with smartui:sidepanel:button:clicked.
smartui:<id>:iv:sidepanel:closed none The user closes the viewer in a viewer side panel. It is not triggered when the panel is closed with smartui:hide:<id>:iv:sidepanel, with smartui:destroy:iv or because another viewer opens.
smartui:<id>:iv:closed none The user closes an inline viewer opened with smartui:show:iv.
smartui:<id>:smartpage:shown none smartui:show:smartpage has rendered its content.

smartui:show:sidepanel has no closed event. Clicks on Cancel arrive as smartui:sidepanel:button:clicked with type: "cancel". Closing with Esc or the header close button is not reported.

Request Topics

Classic code can also request these values from the channel with amChannel.request(...):

Topic Returns
smartui:context The Smart View perspective context. Module Suite tiles, including the Shell Tile, register it. The command handlers need it.
smartui:<id>:iv:get The viewer view of the inline viewer opened with smartui:show:iv and that id.

Viewer Behavior

  • Opening a viewer first triggers smartui:destroy:iv, so only one viewer is open at a time.
  • The expand button of an inline viewer opened with smartui:show:iv closes it and opens the same nodes with smartui:show:iv:sidepanel, id <id>_panel, at full width. Close that panel with smartui:hide:<id>_panel:iv:sidepanel.
  • In a viewer side panel, expand and collapse switch the panel between its width and full width.

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
  • smartui:destroy:iv - Close every open viewer
  • smartui:{id}:destroy:smartpage - Remove the content shown by smartui:show:smartpage

The Command Reference lists every parameter and the events the handlers trigger.

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