References to image or icon resources are used in many contexts within Lobster Data Platform / Orchestration, to determine the graphical information to display.

Typically, dedicated input elements are provided to enable the definition of image resources, which may include a preview (as shown in the following screenshot for Dynamic Enumeration Common business object type) ...

images/download/attachments/62850922/image2019-5-27_11-56-21-version-1-modificationdate-1603695302510-api-v2.png

... or use a more compact format without a preview (e.g. an Image/Icon element in Form designer):

images/download/attachments/62850922/image2019-5-27_12-0-25-version-1-modificationdate-1603695302503-api-v2.png

In both cases clicking the Button opens an image browser, where a reference can be picked instead of entering a link directly.

URL formats for image resources

Image resources are referenced in Lobster Data Platform / Orchestration via a proprietary URL format:

[<type>://]<type-specific address>

The optional Type prefix defines the scheme according to which the character string designated as a Type-specific address will be interpreted (see following table).

Blank characters in file and folder names

If an image URL does not begin with the abbreviation for one of the types listed below, the character string specified as the Type-specific address is interpreted as a reference of img type.

In this special case, blank spaces within the Type-specific address are not regarded as separators between several image URLs (see section 'Sub-images', below), but as part of an all-encompassing URL.

Examples:

The Type-specific address images/custom icons/container terminal.png efers only without the prefix img:// to an image with the name 'container terminal.png' in the subdirectory 'images/custom icons' of the web folder.
With the prefix img:// the same Type-specific address is interpreted as an ensemble of three images because the spaces are used as separators:
- img://images/custom icons/container terminal.png
- It is rather unlikely that these text fragments refer to existing files in the server file system, but access to the file 'container terminal.png' is certainly not possible in this way.
In order for a Type-specific address with blank spaces in file or folder names to be interpreted correctly in conjunction with the prefix img:// the blank spaces must be 'URL-encoded', i.e. replaced by the %20 character string:
- In the example, img://images/custom%20icons/container%20terminal.png would be the appropriate Type-specific address.

Types

Type	Description	Example
img (or no prefix)	reference to an image file in a generic image format (JPEG, PNG, GIF, etc.) defining a resource path relative to the web-folder of the Lobster Data Platform / Orchestration system	assets/loginLogo.png or (equivalent) img://assets/loginLogo.png
fa	reference to a FontAwesome icon, addressed by its name as URL path Currently FontAwesome icons of Version 4 are supported. A list of available icons can be viewed online: https://fontawesome.com/icons?d=gallery	fa://fa-plus Displayed:
rs	resolves an image reference string from Localization or Company specific localization with the following syntax for the URL path: `rs://<bundle>/<resource>` Main advantage: Icons are maintained at a central location, which enables systematic re-assignments, without having to identify and adapt all relevant references individually.	rs://icons/addSymbol with a localization entry for resource 'addSymbol' in bundle 'icons' reading '`fa://fa-plus'` Displayed:
svg	resolves the XML code of an SVG image from Localization or Company specific localization by the following syntax for the URL path: `svg://<bundle>/<resource>`	svg://icons/germany
cfg	concatenates a set of icons defined by a list of references to individual resources with the following syntax for the URL path: `cfg://["image1url","image2url", ...]`	cfg://["fa://fa-file-text", "fa://fa-chevron-right", "fa://fa-truck", "fa://fa-chevron-right", "fa://fa-home"] Diplayed: ►NOTE◄ "fa://fa-spacer" can be used to insert some space between icons: cfg://["fa://fa-truck", "fa://fa-spacer","fa://fa-spacer" ,"fa://fas-truck","fa://fal-truck","fa://fa-truck","fa://far-truck"] Output:

Sub-images (subscript)

Image references concatenated via blank characters define a subordination relation between the resources. The 'sub-image' referenced after the blank character is displayed in reduced size and at a 'subscript' position relative to the first image. If several resources are concatenated with blank spaces (see last example in the list), the images appear in a cascaded manner with descending size.

Examples

Reference (URL)	Result
fa://fa-file
fa://fa-plus
fa://fa-file-text-o fa://fa-plus
fa://fa-home fa://fa-truck fa://fa-home

Advanced configuration options (experts only)

In addition to the simple application options shown above, advanced style settings can also be defined. However, this requires basic a knowledge of CSS (Cascading Style Sheets).

►NOTE◄ The style properties applied must of course be applicable to the resource type addressed. So it makes no sense to set the color property (‘color’) for a standard image type, such as a photograph.

An extended configuration is defined by JSON format in the URL path and might look as follows:

{	"url": "imageURL",
	"style": {
		"css-property1": "css value",
		"css-property2": "css value",
		...
	},
	"cssClass": "css-class-name1 css-class-name2 ..."
}

The properties 'style' and 'cssClass' are both optional an may also be used separately.

Configuration options

Properties	Description
url	the resource URL of an image/icon (see section 'URL formats for image resources above)
style	defines CSS style properties (also in JSON format) CSS property names appear as field names of the JSON object CSS property values appear as field values in the JSON object
cssClass	defines a reference to one or multiple (blank-separated) names of CSS classes to apply to an icon ►NOTE◄ A compact syntax for applying CSS classes is to suffix their name to the image resource separated by a 'dot' (.): a single CSS class: `fa://fa-check-circle.cssClassName` multiple CSS classes: `fa://fa-check-circle.cssClass1.cssClass2.cssClass3` The Lobster Data Platform / Orchestration system provides a set of popular CSS classes for certain layout settings:
	CSS class names	Details
	Default colors of the active 'Style' (see Styles)
	lb-primary / lb-primary-contrast	Style designer color: primaryColor / primaryContrastColor
	lb-secondary / lb-secondary-contrast	Style designer color: secondaryColor / secondaryContrastColor
	lb-inactive / lb-inactive-contrast	Style designer color: inactiveColor / inactiveContrastColor
	lb-warn / lb-warn-contrast	Style designer color: warnColor / warnContrastColor
	lb-error / lb-error-contrast	Style designer color: errorColor / errorContrastColor
	lb-success / lb-success-contrast	Style designer color: successColor / successContrastColor
	Beyond colors, the following CSS classes can be set:
	lb-no-image-shadow	deactivates the contrast shadow for sub-images Examples (with/without shadow): fa://fa-home fa://fa-truck.lb-success fa://fa-home fa://fa-truck.lb-success.lb-no-image-shadow
	lb-stacked	places the following sub-image as full-size overlay on-top of the image the class is applied to, instead of the usual subscript position: Example: `fa://fas-square.lb-stacked fa://fas-check.fa-inverse` Result:
	`lb-pad`	adds padding to the left and right of an image
	The following CSS classes are applicable exclusively to FontAwesome-Icons (fa)
	fa-flip-horizontal / fa-flip-vertical / fa-flip-both	flips the icon horizontally, vertically or in both directions
	fa-rotate-90 / fa-rotate-180 / fa-rotate-270	rotates the icon 90, 180 or 270 degrees (clockwise)
	fa-inverse	inverts the icon (foreground color becomes white)
	Additionally, custom CSS classes can be defined in expert settings for Styles.

Examples

URL

Output

fa://{
 "url": "fa-check-circle",
 "cssClass": "lb-success"
}

images/download/attachments/62850922/image2019-4-3_11-6-9-version-1-modificationdate-1603695302577-api-v2.png

fa://{

 "url": "fa-check-circle",

 "style": {

  "color": "#980f45"

images/download/attachments/62850922/image2019-4-3_11-14-36-version-1-modificationdate-1603695302581-api-v2.png

Advanced application example

A classical use case for a concatenation of icons is the visualization of Tracking state.

A symbol for a hypothetical tracking state 'Shipped' could be composed of icons representing a sequence of process stages with the choice of color indicating progress along the chain, as in the following example:

images/download/attachments/62850922/image2020-4-28_16-23-43-version-1-modificationdate-1603695302443-api-v2.png

To enable a transparent and easy to maintain solution for this, all individual icons required for visualizing the chain should be defined by entries in Localization.

For this example, a dedicated bundle 'tsIcons' was introduced, in which self-explanatory resource names are mapped to individual symbol definitions.

The following table lists all 'localization entries' and their values defining the icons:

Bundle	Resource	Value (e.g. for locale English)	Preview
tsIcons	shipment	fa://fa-file-text
	shipment-active	rs://{ "url": "tsIcons/shipment", "cssClass": "lb-secondary" }
	shipment-inactive	rs://{ "url": "tsIcons/shipment", "cssClass": "lb-inactive" }
	transition	fa://fa-chevron-right.lb-pad
	transition-active	rs://{ "url": "tsIcons/transition", "cssClass": "lb-primary" }
	transition-inactive	rs://{ "url": "tsIcons/transition", "cssClass": "lb-inactive" }
	enroute	fa://fa-truck
	enroute-active	rs://{ "url": "tsIcons/enroute", "cssClass": "lb-secondary" }
	enroute-inactive	rs://{ "url": "tsIcons/enroute", "cssClass": "lb-inactive" }
	delivered	fa://fa-home
	delivered-active	rs://{ "url": "tsIcons/delivered", "cssClass": "lb-secondary" }
	delivered-inactive	rs://{ "url": "tsIcons/delivered", "cssClass": "lb-inactive" }

Once such a set of icons has been created, concatenated tracking state icons can be configured or even generated extremely easily .

The hypothetical tracking state 'Shipped' (as shown above) would be defined by the following URL:

cfg://["rs://tsIcons/shipment-active", "rs://tsIcons/transition-active", "rs://tsIcons/enroute-active", "rs://tsIcons/transition-inactive", "rs://tsIcons/delivered-inactive"]

Similarly, a concatenated icon for another tracking state 'Delivered' can be composed as follows:

cfg://["rs://tsIcons/shipment-active", "rs://tsIcons/transition-active", "rs://tsIcons/enroute-active", "rs://tsIcons/transition-active", "rs://tsIcons/delivered-active"]

Result:

images/download/attachments/62850922/image2020-4-28_16-58-11-version-1-modificationdate-1603695302403-api-v2.png

This systematic approach also has another advantage: If required, the basic icon for a component used by multiple tracking states can be replaced globally.

In the following example, the localization entry for 'tsIcons/shipment' was changed from 'fa://fa-file-text' to 'fa://fa-cubes' to replace the document-symbol with a group of boxes.

Result:

images/download/attachments/62850922/image2020-4-28_17-0-50-version-1-modificationdate-1603695302390-api-v2.png

The change immediately affects all tracking state icons (here: 'Delivered' and 'Shipped'), which reference the localization entry for the 'base icon' directly or indirectly.

Further examples for icon combinations

As explained above, CSS classes can be applied to images using notation like ‘imageURL.cssClassName1.cssClassName2’. In section 'Advanced configuration' (above) the classes provided by the system are listed.

Stacked icons

With the CSS class 'lb-stacked' images can be stacked on top of each other.

Examples:

URL	Result
`fa://fas-square`
`fa://fas-check.lb-primary`
`fa://fas-square.lb-stacked fa://fas-check.lb-primary`
`fa://fas-square.lb-stacked fa://fa-home fa://fas-check.lb-primary`

Inversion ("fa://" FontAwesome-Icons only)

CSS class 'lb-inverse' inverts the FontAwesome icon to white (foreground color).

URL	Result
`fa://fas-square.lb-stacked fa://fas-check`
`fa://fas-square.lb-stacked fa://fas-check.lb-inverse`