Information & Notifications

standard/htmlInfo.ftl

The information and notification elements can be used to define content that should catch the users attention,
such as modals, panels and alerts.

Included by htmlTemplate.ftl.

NOTES:

  • May have implicit dependencies on other parts of Scipio API.

Definitions:

alert,
commonMsg,
modal,
panel

Modal

macro modal

Creates a modal UI element.

Usage Examples

    <@modal id="dsadsa" attr="" >
        Modal Content
    </@modal>

Parameters

id (required)
Model general ID

This receives the prefix "modal_" for the modal itself, and
"modal_link_" for the modal link.
label (required)
Anchor text
icon Generates icon inside the link

NOTE:
Has to be the full set of classes, e.g. "fa fa-fw fa-info"

class ((css-class))
CSS classes or additional classes for inner modal wrap

Supports prefixes (see #compileClassArg for more info):

  • +: causes the classes to append only, never replace defaults (same logic as empty string "")
  • =: causes the classes to replace non-essential defaults (same as specifying a class name directly)

linkClass ((css-class))
CSS classes or additional classes for anchor

Supports prefixes (see #compileClassArg for more info):

  • +: causes the classes to append only, never replace defaults (same logic as empty string "")
  • =: causes the classes to replace non-essential defaults (same as specifying a class name directly)

href Link

NOTE:
This parameter is automatically (re-)escaped for HTML and javascript (using #escapeFullUrl or equivalent)
to help prevent injection, as it is high-risk. It accepts pre-escaped query string delimiters for compatibility,
but other characters should not be manually escaped (apart from URL parameter encoding).

passArgs

NOTE: This macro implements an advanced arguments interface supplementing
regular macro invocations. See standard/htmlTemplate for details.

Alert box

macro alert

Alert box for messages that must grab user attention.

NOTE:
Should avoid using this for regular, common inlined message results such as "No records found." unless
it's an unexpected result, error or one that requires user action.
For most cases, it is preferrable to use @commonMsg macro because it is higher-level.

Usage Examples

    <@alert type="info">
        This is an alert!
    </@alert>

Parameters

type (info|success|warning|secondary|alert|error)
, default info
class ((css-class))
CSS classes or additional classes for nested container

Supports prefixes (see #compileClassArg for more info):

  • +: causes the classes to append only, never replace defaults (same logic as empty string "")
  • =: causes the classes to replace non-essential defaults (same as specifying a class name directly)

id ID on innermost container
style Legacy HTML style attribute on innermost container
closable ((boolean), default: -from global styles-, fallback default: true)
Whether the alert should be hidable/closable
containerClass
containerId
containerStyle
passArgs

NOTE: This macro implements an advanced arguments interface supplementing
regular macro invocations. See standard/htmlTemplate for details.

Panel box

macro panel

Creates a panel box.

Usage Examples

    <@panel type="">
        This is a panel.
    </@panel>

Parameters

type (callout|, default: -empty-)
title Title
id ID for outermost container
class ((css-class))
CSS classes or additional classes for outermost container

Supports prefixes (see #compileClassArg for more info):

  • +: causes the classes to append only, never replace defaults (same logic as empty string "")
  • =: causes the classes to replace non-essential defaults (same as specifying a class name directly)

style Legacy HTML style attribute for outermost container (for compatibility)
topContent ((directive)|(string))
Additional content directly inside panel container at top (before title)

NOTE:
Not escaped by macro.

topContentArgs ((map))
Additional args for topContent
bottomContent ((directive)|(string))
Additional content directly inside panel container at bottom (after body)

NOTE:
Not escaped by macro.

bottomContentArgs ((map))
Additional args for bottomContent
passArgs

NOTE: This macro implements an advanced arguments interface supplementing
regular macro invocations. See standard/htmlTemplate for details.

Common messages (abstraction)

macro commonMsg

Abstracts and factors out the display format of common messages of specific meanings, such as
errors (e.g. permission errors) and query results (e.g. "No records found." messages).

This labels messages according to what they are and lets the theme decide on markup and styling based on content.

This is higher-level than @alert macro; @alert has a specific markup/display and its types are usually levels of severity,
whereas @commonMsg abstracts markup/display and its messages can be a combination of levels and specific meanings;
@alert's goal is to grab user attention, whereas @commonMsg's behavior depends on the type of message.

@commonMsg may use @alert to implement its markup.
A template should not assume too much about the message markup, but the markup should be kept simple.

Usage from screen widgets

<label…/> elements in screen widgets can be mapped to this macro using the special "common-msg-xxx" style name, where
xxx is the message type. e.g.: 

<label style="common-msg-error-perm" text="Permission Error" />

translates to: 

<@commonMsg type="error-perm">Permission Error</@commonMsg>

Extra classes are also possible using colon syntax (combined with the usual "+" macro additive class instruction): 

<label style="common-msg-error-perm:+myclass" text="Permission Error" />

translates to: 

<@commonMsg type="error-perm" class="+myclass">Permission Error</@commonMsg>

Usage Examples

    <@commonMsg type="result-norecord"/>

Parameters

type (default|generic|..., default: default)
The type of message contained

Basic types:

  • default: default. in standard Scipio markup, same as generic.
  • generic: no type specified (avoid using – prefer more specific)

Types recognizes by Scipio standard markup (theme-defined types are possible):

  • result: an informational result from any kind of query. e.g., "No records found.".

    is a normal event that shouldn't distract user attention.
  • result-norecord: specific "No records found." message.
  • info: general information (NOTE: this is not really useful, but supported for completeness)
  • info-important: general important information
  • warning: general warning
  • fail: general non-fatal error
  • error: general error message – typically an unexpected event or fatal error that should not happen in intended use.
  • error-perm: permission error
  • error-security: security error

id ID on innermost container
class ((css-class))
CSS classes or additional classes for message container (innermost containing element)

Supports prefixes (see #compileClassArg for more info):

  • +: causes the classes to append only, never replace defaults (same logic as empty string "")
  • =: causes the classes to replace non-essential defaults (same as specifying a class name directly)

text ((string))
Text

If a string is not specified, uses nested content instead.
closable ((boolean), default: -from global styles-)
Whether the message should be closable

NOTE:
This is not implemented for all types and defaults vary, but if unsure and need to prevent closing, best to specify explicit false.

passArgs

NOTE: This macro implements an advanced arguments interface supplementing
regular macro invocations. See standard/htmlTemplate for details.