Icon assignment mechanism

In the lsFusion platform, developers can manually assign icons to UI elements corresponding to properties, actions, forms, containers, and navigator elements. You can specify either an image file path or icon font CSS classes.

In addition, the platform provides a mechanism that can automatically assign suitable icons for these elements. The mechanism analyzes their names and captions and selects the most appropriate icons from the available sets.

Manual assignment

An icon is set using a string literal, which can be specified in one of the following ways:

• File path: 'path/to/image.png' (relative to the images directory)
• Icon font CSS classes: 'fa fa-user' (Font Awesome), 'bi bi-person' (Bootstrap Icons)

info

Icon font CSS classes are CSS classes for displaying vector icons from special fonts. Such icons scale without loss of quality and take up less space than raster images.

The platform supports free icons from two popular sets: Font Awesome and Bootstrap Icons.

For an icon set by a file path, the platform additionally looks up a matching icon-font icon by the name of that file — with the same mechanism as automatic assignment, and equally requiring the Icon.lsf module to be connected. If a match is found, the CSS classes of the icon found are attached to the element alongside the path, and wherever icon fonts are used it is shown rather than the raster image. The minimum rank of such a match is set by the working parameter defaultImagePathRankingThreshold. It is 0.0 by default, which means any match found will do; to have the specified path used as it is, the threshold has to be raised.

Automatic assignment

info

Automatic icon assignment works only if the Icon.lsf module is added to the project.

General logic

1. Keywords are extracted from the element name or caption.
2. Candidates are selected by these keywords; the icon with the highest match rank is chosen.
3. If the rank is not lower than the threshold for this element type, the found icon is used.
4. Otherwise, the default icon for this element type is applied (if its use is enabled).

Determining search keywords

Keywords are formed from the caption and/or the element name according to the following rules:

1. The caption is used first. If it is localizable, its English variant is taken.
2. The text is split into keywords; short words can be removed if necessary.
3. If there is no caption, or its processing does not produce a keyword list, the element name is used and processed in the same way.

Settings and parameters

Automatic icon assignment is configured via a set of working parameters.

Parameters that change ranking thresholds:

Parameter	Scope	Default threshold
defaultImagePathRankingThreshold	Icons set by a file path	0.0
defaultAutoImageRankingThreshold	All auto-icons	0.0
defaultNavigatorImageRankingThreshold	Navigator elements and forms	0.1
defaultContainerImageRankingThreshold	Containers	0.6
defaultPropertyImageRankingThreshold	Properties and actions	0.8

Parameters to enable/disable default icons:

Parameter	Element type	Default value
defaultNavigatorImage	Navigator elements and forms	true
defaultContainerImage	Containers	false
defaultPropertyImage	Properties and actions	false

The default icon is substituted when no suitable match is found; with the standard settings it is enabled only for navigator elements and forms.