Widget HTML and CSS reference
The section is only applicable to widgets, and describes standard HTML and CSS configuration in a widget's web page. It does not apply to scripts and UDIXes, which have no web page.
Standard behaviour is for a widget to include both the framework's Javascript and its CSS (in the page's <head>). Doing this means that the widget will automatically participate in the user's selected graphical theme for the software. The widget will inherit standard background and text colours, including live changes if the user selects a different theme.
However, this is not compulsory. A widget is free to ignore or override the framework's CSS, and use its own design.
6.1 CSS reference
The best and simplest reference to the framework's CSS is the Developer Console of your web browser. This will show you the CSS variables which the framework declares (at :root level), such as --clr-text and --font-size-base.
The following sections contain some explanatory notes about the standard CSS, not a full itemisation of its variables and classes.
6.1.1 Body classes
The framework sets some standard classes on the widget's <body> which may be useful as selectors in your own CSS (for example, changing some colours of your own based on BODY.Theme_light):
CSS class | Description |
Theme_x | Identifier for the current graphical theme, such as Theme_standard or Theme_light |
LTR or RTL | Identifies whether the user's selected language for the platform is written left-to-right or right-to-left. Sets CSS direction on the <body> (either direction:ltr or direction:rtl). The framework has some helper CSS classes to handle reading order. |
BrowserPhoneScreen | Set by the framework if the device qualifies as a "phone-sized" screen. The framework's definition is if either the device width or the device height is less than 500px. Note that this is calculated using the size of the monitor (window.screen in Javascript), not the size of any individual browser frame in the software. |
6.1.2 Right-to-left reading order
The framework provides some helper CSS classes for handling reading order. The following classes invert, between left and right, if the user's selected language is right-to-left. For example, the definition of TEXTL becomes {text-align: right}.
CSS class | Description |
TEXTL | text-align:left by default, inverting to right for right-to-left languages |
TEXTR | text-align:right by default, inverting to left for right-to-left languages |
FLOATL | float:left by default, inverting to right for right-to-left languages |
FLOATR | float:right by default, inverting to left for right-to-left languages |
TextDirection | direction:ltr by default, inverting to rtl for right-to-left languages |
6.1.3 Button CSS classes
There are some standard CSS classes for buttons. Note: in some future graphical themes of the software, the colour might maintain the general connotations of the class/type but not match the actual colour name.
CSS button class | Common purpose |
btn-green | A button for accepting, saving, granting permission etc |
btn-red | A button with a dangerous or destructive result: deleting something, carry out a dangerous action etc |
btn-blue | A button for carrying out an action with no strong positive or negative connotation |
btn-standard | A button with no associated action (other than e.g. closing a dialog) |
btn-amber | Normally associated with a mild warning, without the full connotations of btn-red |
btn-pink | (no common association) |
6.1.4 FontAwesome icons
The framework automatically includes the Font Awesome icons (v6), but does not include the standard Font Awesome CSS. The icons are imported into the framework's CSS as font-family:FontAwesome, and the framework's CSS includes a .FA class whose definition is {font-family:FontAwesome}. For example:
<!-- Display FontAwesome icon, inline, using the hex code in the form ꪪ -->
<span class="FA"></span>
Or, using CSS to declare a class which displays an icon using :after:
.tickicon {
font-family: FontAwesome;
}
.tickicon:after {
content: "\f058";
}
6.2 Standard HTML structure
Sway Charts Pro's built-in widgets have little standard HTML structure because they display such a wide variety of information and functionality.
6.2.1 Standard dialog structure
There is a standard HTML structure for dialogs, potentially relevant if your widget is displaying itself as its own dialog.
<div class="DialogStructure">
<div class="DialogTitle"></div>
<div class="DialogContent DialogContentIndent"></div>
<div class="DialogFooter"></div>
</div>
The DialogContent automatically expands and shrinks to fill the available space, and with overflow:auto. It is not compulsory for a dialog to have a title and/or footer. These elements can be omitted.
You may want to re-use the DialogStructure for things which are not dialogs. If a widget is not being displayed as a dialog, then the framework's standard CSS automatically hides the DialogTitle. You can force it to be visible by adding DialogTitleAlways: class="DialogTitle DialogTitleAlways".
Adding the class DialogTitleMini to the title reduces the font size and height of the title.
6.3 Pop-up menus
The framework provides a standard mechanism for displaying pop-up menus. This has three advantages over a widget implementing its own menu HTML:
· Standard look and feel with Sway Charts Pro's built-in widgets
· On small screens such as mobile phones, the framework automatically converts menus into a full-screen dialog (the MenuListDialog).
· The framework's menus can extend outside the boundary of a widget's frame. If your widget is in a small frame, such as a small segment of a multi-widget layout in the Sway Charts Pro page container, any menu which the widget displays itself will be confined to its small frame.
A widget can display a pop-up menu using Framework.CreatePopupMenu(). This takes three parameters:
Parameter | Description |
menu | Definition of the menu (which can contain items with sub-menus) |
eventOrNode | Either a node in the DOM, or a Javascript event object from which the framework uses the event.target. The menu is positioned relative to this node. |
callback | Asynchronous callback function which receives the user's selection from the menu |
For example:
// Add a click handler on someButton which displays a menu next to it
someButton.addEventListener("click", function(event) {
var menuDef = { … some menu definition … };
Framework.CreatePopupMenu(menuDef, event, function(Msg) {
// Receives the asynchronous result of the menu
});
});
The definition of a menu is the same as for Framework.MenuListDialog(), and described in detail in that section. The menu should have a title (only used on small screens when converted into a MenuListDialog), and an array of items[]. Each item can have an icon, custom colours, an array of sub-items etc.
The asynchronous callback function receives the user's selection from the menu, or cancellation. If there was a selection, then the Msg will contain an itemData which is simply the selected entry from the items[] array. For example:
Framework.CreatePopupMenu(menuDef, event, function(Msg) {
if (Msg.itemData) {
// User made a selection, and the original object from items[]
// is in Msg.itemData
} else {
// User dismissed the menu without making a selection
}
});
Last updated