Images

Image assets

All Images should be placed in /assets/images/ or within a descendent directory of it. Images should be added to the markdown using the image shortcode. This ensures a consistent look for all images and allows control of the size of the image.

The short code can be added in the following ways.

Markdown:

{{< image "style-guide/stroom-oo.svg" "200x" >}}

{{< image "style-guide/stroom-oo.png" >}}

{{< image "style-guide/stroom-oo.svg" "200x" >}}Image caption{{< /image >}}

All paths used in the image shortcode are relative to /assets/images.

The following shows an example of the directory structure.

/assets
   /images
      /section-x
         /sub-section-y
            /page1
               /image.svg
/content
   /en
      /docs
         /section-x
            /sub-section-y
               page1.md - #image shortcode used in here

Where images are only used by one page then the directory structure in /assets ought to mirror that of the page the images are used in, as shown above. If images are used by multiple pages then some other sensible organisation of the images should be used, e.g. /assets/images/section-x if they are limited to pages in one section, or /aaets/images/common if they are used in multiple sections.

Captions

The image can be displayed with a caption:

Example:

---

Markdown:

{{< image "style-guide/svg-logo.svg" "200x" >}}
By W3C SVG Logo, CC BY-SA 4.0, https://commons.wikimedia.org/w/index.php?curid=105996438
{{< /image >}}

Size

The image can be defined with a maximum width (e.g. "300x") or a maximum height ("x200").

Example:

Markdown:

{{< image "style-guide/svg-logo.svg" "120x" />}}

.png files

.png files can be rendered in their original size by omitting the size argument.

Examples:

Or they can be rendered with a set size.

Markdown:

The markdown for the examples above is:

{{< image "style-guide/stroom-amber.png" />}}

Or they can be rendered with a set size.

{{< image "style-guide/stroom-amber.png" "50x"/>}}

Using global /assets/ resources

For images that are shared by multiple page bundles, e.g. stroom icons, place them in /assets/images/. The image path is relative to /assets/images/, e.g. file /assets/images/style-guide/svg-example.svg becomes style-guide/svg-example.svg.

Example:

---

Markdown:

{{< image "style-guide/svg-example.svg" "200x" >}}
This is some optional caption text for the image.
And this is another line.
{{< /image >}}

PlantUML

PlantUML is the favoured tool for producing diagrams such as UML diagrams, entity relationship diagrams and other more general architecture diagrams. The diagrams are written in plain text which makes them easy to version control. The plantUML syntax can then be converted into image files, e.g. .svg files.

A plantUML diagram looks like this in plain text form:

@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml

PlantUML diagrams should be saved in a dedicated .puml file in the same folder as the page that will display it. If it is needed by multiple pages then it should be saved in /assets/images/.

The build process will convert all .puml files to a corresponding .puml.svg file. These generated .puml.svg files are ignored by git so need to be regenerated at build time or when you change a .puml file. The images can be generated by doing:

./container_build/runInPumlDocker.sh SVG

You should embed a PlantUML image like this, using the .puml.svg file (that may not yet exist, but will have to exist before the site is built):

Example:

Markdown:

{{< image "style-guide/puml-example.puml.svg" "300x" />}}

Using page resources

Images can be located in a page bundle . This is where the page is defined as a named directory (rather than a .md file) with an associated index.md file for the markdown contnet. All other items in the directory are page resources that can be used by the page, i.e. image files.

Use the image short code to display an image file that is located in the same directory as the page. For the short code to work the page must be a leaf bundle (index.md) or a branch bundle (_index.md), i.e:

/docs
   /MyPage
      index.md - #image shortcode used in here
      example.svg

or

/docs
   /MySection
      /Page1
         index.md
      /Page2
         index.md
      _index.md - #image shortcode used in here
      example.svg

In the above example, the shortcode would look like:

{{< image "example.svg" "200x" >}}

Stroom user interface Components

Sometimes it is useful to display an image of certain user interface elements to explain something. Rather than use screenshots which are very difficult to keep up to date, you can instead use some simple shortcodes to display some UI elements, e.g. buttons, pipeline elements, etc. By using shortcodes, any change to the look of the Stroom UI means only the shortcode content and their styling need to change, without having to recreate tens or hundreds of screenshots.

Stroom icons

Stroom UI icons such as or can be added in line using the shortcode stroom-icon.

Arguments:

• name - The filename (and relative path) of the icon file. The path is relative to /assets/images/stroom-ui/, e.g. documents/Feed.svg.
• title (optional) - The hover tip title that will be given to the icon. If not supplied, the filename (minus extension) will be converted to sentence case and used as the title.
• enabled (optional) [enabled|disabled] - Whether the button is enabled or disabled. Defaults to enabled.
• colour (optional) - The colour variant to use for the icon. Not all icons support colour variants. If not supplied, and where the icon supports colour variants, then the default colour is blue. See below for the list of colour variants.

The full list of available icons can be found in the Icon Gallery.

Examples:

Simple use:

Custom hover tip name:

A document icon:

A pipeline icon:

Enabled vs disabled

An icon in its different colour states:

• Default (no colour specified)
• blue
• brey
• green
• red

Markdown:

The markdown for the examples above is:

Simple use: {{< stroom-icon "save.svg" >}}

Custom hover tip name: {{< stroom-icon "key.svg" "Not a key" >}}

A document icon: {{< stroom-icon "document/Feed.svg" >}}

A pipeline icon: {{< stroom-icon "pipeline/text.svg" >}}

Enabled {{< stroom-icon "delete.svg" >}} vs disabled {{< stroom-icon "delete.svg" "Delete" "disabled" >}}

An icon in its different colour states:
* Default (no colour specified) {{< stroom-icon name="settings.svg" >}}
* `blue` {{< stroom-icon name="settings.svg" colour="blue" >}}
* `brey` {{< stroom-icon name="settings.svg" colour="grey" >}}
* `green` {{< stroom-icon name="settings.svg" colour="green" >}}
* `red` {{< stroom-icon name="settings.svg" colour="red" >}}

Buttons

To display a user interface button you can use the shortcode stroom-btn with the button title as its only argument.

Arguments:

• title - The text to display on the button.

Examples:

Ok and Cancel

And not in line

Save

Markdown:

The markdown for the examples above is:

{{< stroom-btn "Ok" >}} and {{< stroom-btn "Cancel" >}}

And not in line

{{< stroom-btn "Save" >}}<br/>

Pipeline elements

To display a pipeline element (as seen on the Structure sub-tab on the Pipeline screen), like SplitFilter , you can use the shortcode pipe-elm.

Arguments:

• element_name - The name of the pipeline element (case sensitive), e.g. XSLTFilter.
• display_name (optional) - The display name for the pipeline element. If a display name is not provided then the element name will be used as the display name.

The list of available pipeline elements can be found in this gallery. An invalid element_name will result in an error when building the site.

The icon will be selected to match the element name provided. The element is a clickable link to the appropriate reference page for that element.

Examples:

This is an xsltFilter with its default name:

XSLTFilter

This is a splitFilter with a custom name:

My Split Filter

This is an IndexingFilter in line.

Markdown:

The markdown for the examples above is:

This is an xsltFilter with its default name:

{{< pipe-elm "XSLTFilter" >}}<br/>

This is a splitFilter with a custom name:

{{< pipe-elm "SplitFilter" "My Split Filter" >}}<br/>

This is an {{< pipe-elm "IndexingFilter" >}} in line.

Pipelines

To display a pipeline consisting of multiple pipeline elements (as seen on the Structure sub-tab on the Pipeline screen) you can use the short code pipe.

This shortcode takes no arguments. Instead, the inner content of the shortcode is populated with multiple pipe-elm shortcodes to describe each of the elements in the pipeline. This shortcode does not support any branching/forking in the pipeline.

Example:

Markdown:

The markdown for the two examples above is:

{{< pipe >}}
  {{< pipe-elm "Source" >}}
  {{< pipe-elm "XMLParser" >}}
  {{< pipe-elm "RecordCountFilter" "recordCount (read)" >}}
  {{< pipe-elm "SplitFilter" >}}
  {{< pipe-elm "IdEnrichmentFilter" >}}
  {{< pipe-elm "XSLTFilter" >}}
  {{< pipe-elm "SchemaFilter" >}}
  {{< pipe-elm "ElasticIndexingFilter" >}}
  {{< pipe-elm "RecordCountFilter" "recordCount (written)" >}}
{{< /pipe >}}

Each element is a clickable link to the appropriate reference page for that element. Pipelines cannot be used in-line in text.

For details on how to use pipe-elm see pipeline elements above. The list of available pipeline elements can be found in this gallery.

Stroom document tabs

To display a top level Stroom document tab, like Big Index , you can use the shortcode stroom-tab.

Arguments:

• icon_filename - The filename of the icon to use (relative to assets/images/stroom-ui/document/) (case sensitive), e.g. Pipeline.svg.
• title - The text to display in the tab, e.g. Indexing Pipeline.
• state (optional) - Whether the tab is active or not (active or inactive). Defaults to inactive.

For a full list of all available icons see the Icon Gallery

Examples:

Simple: MY_FEED

Custom name: My Translation

Active: My Translation

Unsaved: * My Translation

Markdown:

The markdown for these examples is:

Simple: {{< stroom-tab "Feed.svg" "MY_FEED" >}}
Custom name: {{< stroom-tab "XSLT.svg" "My Translation" >}}
Active: {{< stroom-tab "XSLT.svg" "My Translation" "active" >}}
Unsaved: {{< stroom-tab "XSLT.svg" "My Translation" "active" "unsaved" >}}

Stroom selected menu items

To display the selection of a menu item you can use the stroom-menu shortcode.

Arguments:

• menu_item_names... - One argument per menu item name in the order root to leaf.

Examples:

For example to demonstrate creating a folder using the context menu:

The shortcode takes one argument per menu item so you can have multiple levels of menu.

Markdown:

The markdown for these examples is:

For example to demonstrate creating a folder using the context menu:

{{< stroom-menu "New" "Folder" >}}

The shortcode takes one argument per menu item so you can have multiple levels of menu.

{{< stroom-menu "Add" "Folder" "Feed" >}}

It cannot be used in-line in text, it needs to be on its own line.

The list of available menu items with an icon can be found in this gallery. Menu item names are case-sensitive.

If the menu item name is not an exact match to one in the gallery then it will be displayed without an icon, e.g.:

Keyboard Shortcuts

To display a keyboard shortcut (AKA key binding) you can use the key-bind shortcode.

Arguments:

• key_bind... - One or more key bindings, whit keys in the key binding delimited by ,, - or +. The name and case of non-alphabet keys will be normalised, e.g. del => Delete. The modifier keys ctrl, shift, alt, meta will be placed first and displayed in a consistent order.

Each argument is one of more keys that are pressed at the same time, e.g. "ctrl,c" for Ctrl ^ + c . Chord key bindings where multiple key binds are pressed and released in sequence have one argument for each step in the chord, e.g. pressing g then p has arguments "g" and "p", producing g , p .

Examples:

This is a key binding with modifiers Ctrl ^ + Shift ⇧ + f and this is chord type key binding g , p .

If the key is a , then use + or - as the delimiter, e.g. Ctrl ^ + Alt + , , Ctrl ^ + + or Alt + - .

Markdown:

The markdown for these examples is:

This is a key binding with modifiers {{< key-bind "ctrl,shift,f" >}}  and this is chord type key binding {{< key-bind "g" "p" >}}.

If the key is a `,` then use `+` or `-` as the delimiter, e.g. {{< key-bind "ctrl+alt+," >}}, {{< key-bind "ctrl,+" >}} or {{< key-bind "alt+-" >}}.