This Tutorial explains how to define and use a Ribbon in the SWAT UX, like in this Screen:
First, you need to add a Ribbon control to your screen, using the SWAT Screendesigner. As the Ribbon is quite generic, you can just use the Object-Master “SimpleSwatRibbon”, which is shipped with the Framework, instead of creating your own Ribbon-Masters.
Just add the SimpleSwatRibbon object to your Screen like any other Object, by opening the “Add” dialog, and drag&drop from the Grid onto a panel in your screen:
This will add the Ribbon control to your screen, but at runtime it will be empty. To actually see a Ribbon at runtime, you need to provide a Ribbon definition. This is done by the “ToolbarKey” Attribute of the Ribbon control. At runtime, this will tell the Ribbon which Menu-Structure it should use to build the actual Ribbon on the screen. You can specify a JSON file here, which must be available on the Backend, e.g. “uicache/myRibbonDefinition.json”. This can be useful for testing, or for quick prototyping.
Most of the time, however, you will use a SmartComponentLibrary Menustructure to define your Ribbon. This can be done using a “#” as the prefix in your ToolbarKey Attribute, which will tell the Ribbon that the part after the “#” is the Code of a SCL Menustructure, e.g. “#MyRibbonDefinition”:
In order to use a Menustructure for a Ribbon, it needs to have the correct structure.
A Ribbon consists of:
- The “Root” Menu, whose “Structure Code” is what you specify in the ToolbarKey Attribute (prefixed with “#”)
- Below the root Menu, there are Menus of type “Ribbon Block”
- Below the Ribbon Blocks, there are Menu-functions, which make up the actual Ribbon-items (e.g. Buttons).
- Menu functions are maintained in SmartMenu Menu Function Maintenance. You can drag these menu functions onto the ribbon block by selecting the rowselector of the desired function.
Optionally, below the “Root” node and above the Block nodes, there can be an additional level of menu-nodes. These Menu-nodes will be rendered as Ribbon-Tabs, and therefore must have the Menu-Style set to “Ribbon Tab”
Attributes for Ribbon Blocks
You can define Attributes for whole Ribbon blocks, e.g. to conditionally define their visibility. For this, you must set the Parameter Type to “SWAT Ribbon”:
The “visibility Rules” Attribute allows to dynamically control the visibility of whole Ribbon blocks. E.g.: {"currentPage": "1,!*"}
This value for the visibility Rules Attribute makes the corresponding Ribbon-Block only on page 1 visible, and hides it for all other pages.
Note
The “Menu Style” and Parameter type are not that important, because the actual UI representation is mostly dependent on the definition of the screen and the Menustructure. E.g., if you add a “SimpleSwatRibbon” to your screen, the menustructure referenced in the “ToolbarKey” attribute will be rendered as a Ribbon. If instead you use a “SimpleSwatToolbar” object (which also has a “Toolbarkey” Attribute), the same structure will be rendered as a Toolbar.
Similar, the structure defines e.g. if a Ribbon has as RibbonTab, Ribbon-Blocks,, and in which block an item resides. There is only one special case: A Menu below the Ribbon-Root-Node could be a Tab or a Block. Therefore, in this case, the SWAT UX assumes you want this to be a Block. If you want to use a Ribbon-Tab, you must explicitly set the Menu-Style of the menu-node to “Ribbon Tab”.
The lowest level in a Ribbon Menu-Structure are items (which reference Menu-Functions). Those are usually represented in the UX as Buttons, which trigger certain actions when clicked at runtime, depending on their Action-Type (launch, publish, run…).
Those work the same as Menu-Functions in other parts of the UX (like FAB, Context-Menu, Panel-Menu…)
Sample Action Types
Next comes the menu function for the first button you want to put into the ribbon. In my case it is a create record button.
Important here are the parameters “action type” and “action parameter”. As I want to launch a create window in my case I put “launch” as the action type and the window name “CreateRecordWindow” as action parameter. This is more or less the “folderWindowToLaunch” as you might know already.
Linking
If the Ribbon is used for Updating records, it must be connected as a TableIO-Source to a SwatForm. If there are multiple SwatForms related to the same BusinessEntity / DataSource, then only the 1st one must be linked.
If the Ribbon is used for Navigating a Query (Next/Prev/First/Last), it must be connected as a Navigation-Source to a BusinessEntity/Datasource.
