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:
-
Decouple components: Enable loose coupling between UI components through event-driven communication, making applications more maintainable and extensible.
-
Enhance user experience: Display toolbars, viewers, side panels, and other UI elements dynamically based on user interactions and application state.
-
Simplify integration: Use a consistent command pattern across all SmartUI interactions, reducing complexity and learning curve.
-
Enable dynamic content: Load Smart Pages, Intelligent Viewing, and other content on-demand without full page refreshes.
-
Improve responsiveness: Show loading indicators and messages to provide feedback during asynchronous operations.
-
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:
separateCommandsandshowInlineBarOnHoverare alwaystrue. Passingfalsehas no effect.text.dropDownTextandaddGroupSeparatorsare 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 adropDownIconNameparameter.
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.
Footer Buttons¶
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:ivcloses it and opens the same nodes withsmartui:show:iv:sidepanel,id<id>_panel, at full width. Close that panel withsmartui: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.