This is a wiki topic, regular members as well as staff may edit it freely and are encouraged to do so! The content will eventually be migrated somewhere in the main documentation when it’s stabilized and enough feedback has been received. When replying to posts on this series, please try to stay on-topic - there will be several of them, each covering a particular feature or area, so please look for the appropriate topic and reply there, or create a new topic. Thanks!
As mentioned in the previous article, cards saved in your Card deck can be changed to look better, new ones can even be created from scratch.
From the Card deck screen, you can create a card from one of three templates by clicking on the “+” button and selected either a tabbed card, a list card or a simple card.
Note that choosing a template is only a way to have part of the card designed for you, it is not a decision you cannot go back on.
You can also edit an existing saved card using its context menu - from the Card deck or anywhere the card appears:
The Card Designer
The Card designer is where you can design your card visually.
The left side pane contains a tree view of Components and Slots (see below), the main area displays a live and fully functional rendering of the card, and the right side pane contains tools for the currently selected node in a tree. The header displays the name and type of the node (component or slot), and a context menu on the right list actions available for that component.
Components and Slots
Cards are a hierarchy of Components and Slots - similar to the terminology found in web frameworks like VueJS:
Components are pieces of UI designed to fullfill a specific purpose, they have a type (prefixed with “Hb”, for example HbCard, HbContainer, HbListItem, HbBtn etc.), some configuration settings, and might contain one of more slots;
Slots can be seen as placeholders within a Component where new Components may be added - thus forming the hierarchy of the whole card, which is a HbCard component at the root level. The available slots depend on their parent Component.
For example, the HbCard component defines multiple slots - in the Designer click on the HbCard component at the root of the tree view on the left side pane, then the Slots tab on the right side pane to see which slots are available. Those already added are grayed out - only one slot of each type may be added to a given component. When clicking on a slot, the tool pane will allow adding more components to that slot. If all components in a slot are removed, the slot disappears too. The red dot on the tab header simply means there are slots available to be added.
Each slot corresponds to a place on the HbCard component hosting other components. Certain components are only valid and therefore can only be added on a certain slot. For example, the “right” slot is the slot near the context menu and can only accept 3 types of components, the “main” slot in the main area for components which are not a HbList or HbTabs, and the “actions” slot is the area at the bottom which can only contain specific button-like components: HbAnalyzeActionButton or HbCommandActionButton.
Usually container components will only have one slot (typically called “main”) or specialized slots which may not have a “visual” meaning (for instance, the HbBtn component has a “modal” slot for opening a HbModal component upon clicking, the HbCarousel component has a “slides” slots, etc.).
How to render components in a slot depends on the implementation of the parent component.
The usual flow when designing cards is to configure components by selecting them in the tree view, eventually creating slots if available, and then creating new components in that slot.
Because the card is fully functional and accepts clicks like it would anywhere else in the UI, you can only select a component by finding it in the tree - you can’t simply click on it on the card itself.
Descriptions for all slots, components and configuration options are provided.
Don’t forget to save the card regularly when designing it by clicking on the Save button!
On a component’s tool pane, a toolbar allows you to quickly delete, reorder (within its parent slot) or clone the component.
Copying and pasting components
You can cut or copy a component (and its slots and subcomponents) with the context menu while it’s selected or with the standard keyboard shortcuts Ctrl+X / Ctrl+C (Cmd+X / Cmd+C on Macs). Then you need to select the slot which can accept it before pasting it, again with the slot’s context menu in the tool pane or with Ctrl+V (Cmd+V on Macs).
Editing a slot’s JSON directly
You can edit individual slots by selecting them, then using the “Edit JSON” option in the tool pane’s context menu. With this technique you can quickly remove parts you don’t need, copy paste components, and it’s also usefuly to reuse or share parts of cards by saving them in a file. You need to understand the structure of the tree in JSON format, which isn’t so hard
The buttons on the JSON editor’s toolbar allow you to reindent the JSON, perform some quick checks, and update the card to reflect the changes and close the editor.
The next article will present some components, how to configure certain options like icons and colors, and introduce expressions.