Navigation & Menus

standard/htmlNav.ftlNavigational elements that can be used to generate complexe menus, pagination controls or other navigation elements (magelan, step elements, breadcrumbs or alike). The usage should be largely simplified by the elements provided.

Included by htmlTemplate.ftl.

NOTES:

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

Definitions:#

cmsmenu , isMenuMarkupItemsInline , makeMagTargetAttribMap , menu , menuitem , mli , mtarget , nav , paginate , step , treeitem , treemenu

Nav List#

macro nav#

Creates a navigation list, for example based on magellan-destination or breadcrumbs.

Breadcrumb navigation documentation

Since this is very foundation specific, this function may be dropped in future installations

Usage Examples#

<@nav type="">
        <li>Text or <a href="#">Anchor</a></li>
    </@nav>

    OR

    <@nav type="magellan">
        <@mli arrival="MyTargetAnchor">Text or <a href="#">Anchor</a></@mli>
    </@nav>

    <@heading attribs=makeMagTargetAttribMap("MyTargetAnchor") id="MyTargetAnchor">Grid</@heading>

Parameters#

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

mli#

macro mli#

Creates a magellan-destination link.

Parameters#

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

mtarget#

function mtarget#

Creates an magellan-destination attribute string.

Parameters#

makeMagTargetAttribMap#

function makeMagTargetAttribMap#

Makes an attrib map container a magellan-destination attribute.

Parameters#

step#

macro step#

Creates a single step – to be used with <@nav type="steps" />.

Parameters#

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

Menu#

macro menu#

Menu macro, mainly intended for small inline menu definitions in templates, but able to substitute for widget menu definitions if needed.

Menu macro documentation showing menu button states

It may be used in two forms:

<#assign items = [{"type":"link", ...}, {"type":"link", ...}, ...]>
<@menu ... items=items />
OR
<@menu ...>
  <@menuitem type="link" ... />
  <@menuitem type="link" ... />
  ...
</@menu>

In the first, each hash of the items list represents a menu item with the exact same arguments as the @menuitem macro. The first method gives the @menu macro more control over the items, and to delegate the definitions, while second is cleaner to express.

Note that both macros support arguments passed in a hash (or map) using the “args” argument, so the entire menu definition can be delegated in infinite ways (even to data prep). The inline args have priority over the hash args, as would be expected.

The generated menu ID following a call can be read using: getRequestVar("scipioLastMenuInfo").id. At current time (2016-09-16), other members of that map should not be relied upon.

Nested Menus#

Nested menus (sub-menus) will inherit the type of the parent if no type is specified. The macro will automatically try to determine if the menu is nested and the type of the parent, but these may be overridden so a nested menu may behave as a top-level menu. Note the macro makes a distinction between sub-menus that are the same type as the parent and sub-menus that are a different type as the parent, which may require different handling.

The submenu’s main class may be set as altnested in global styles.

Parameters#

styles["menu_" + type?replace("-","_")], or if missing from hash, falls back to
styles["menu_default"]

through items list of hashes, currently does not apply to
nested items. by default, sorts by text, or sortBy can specify a menu item arg to sort by.
normally case-insensitive.

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

History#

Enhanced for 1.14.3.

Enhanced for 1.14.2.

Menu Item#

macro menuitem#

Menu item macro. Must ALWAYS be enclosed in a @menu macro (see @menu options if need to generate items only).

WARN: Currently the enclosing @menu and sub-menus should never cross widget boundaries, and at most will survive direct FTL file includes.

Parameters#

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

Menu Markup Inline Check#

function isMenuMarkupItemsInline#

Function that examines a string containing menu HTML markup and returns true if and only if the menu items are inlined, i.e. without container.

Occasionally macros need to check this, notably for compatibility with Ofbiz screens. By default, this checks if the first item is a

element. Themes that use a different menu item element must override this and provide a proper check.

Parameters#

menuContent

string of HTML markup

---

Pagination#

macro paginate#

Creates a pagination menu, for example around a data table, using Ofbiz view pagination functionality.

Usage Examples#

text

<@paginate mode="single" ... />
    <@paginate mode="content">
      <@table type="data-list">
        ...
      </@table>
    </@paginate>

Parameters#

mode	(content|single, default: single) content: decorates the nested content with one or more pagination menus (depending on layout, and layout can be centralized) NOTE: in overwhelmingly most cases, this mode should be preferred, as it offers more control to the theme. single: produces a single pagination menu (layout argument has no effect)
type	(default, default: default) Type of the pagination menu itself default: default scipio pagination menu
layout	(default|top|bottom|both, default: default) Type of layout, only meaningful for "content" mode default: "pagination_layout" from styles hash, otherwise both top: no more than one menu, always at top bottom: no more than one menu, always at bottom both: always two menus, top and bottom
position	(top|bottom|, default: -empty-) Optional position indicator, only makes sense in single mode. If specified, it may lead to the pagination not rendering depending on resolved value of layout. In content mode (preferred), this is handled automatically.
noResultsMode	(default|hide|disable, default: default) default: "pagination_noresultsmode" from styles hash, otherwise hide. may depend on mode argument. hide: hide menu when no results disable: disable but show controls when no results (TODO?: not implemented)
enabled	((boolean), default: true) Manual control to disable the entire macro Sometimes needed to work around FTL language. For "content" mode, with false, will still render nested content (that is the purpose), but will never decorate.
url	Base Url to be used for pagination 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).
class	((css-class)) CSS classes 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)
listSize	Size of the list in total
viewIndex	((int)) Page currently displayed
viewSize	((int)) Maximum number of items displayed NOTE: this should be decided earlier in rendering (data prep) and a valid value MUST be passed.
forcePost	((boolean), default: false) Always use POST for non-ajax browsing NOTE: even if false, large requests may be coerced to POST.
paramStr	Extra URL parameters in string format, escaped e.g. param1=val1&param2=val2 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).
viewIndexFirst	((int)) First viewIndex value number (0 or 1, only affects param values, not display)
showCount	((boolean)) If true show "Displaying…" count or string provided in countMsg; if false don't; empty string is let markup/theme decide
alwaysShowCount	((boolean)) If true, show count even if other pagination controls are supposed to be omitted
countMsg	Custom message for count, optional; markup provides its own default or in styles hash
lowCountMsg	Alternate custom message for low counts, optional; markup provides its own or in styles hash
paginateToggle	((boolean)) If true, include a control to toggle pagination on/off (specify current state with paginateOn and tweak using paginateToggle* arguments)
paginateOn	((boolean)) Indicates whether pagination is currently on or off Can be used with paginateToggle to indicate current state, or set to false to prevent pagination controls while still allowing some decorations (depending on styling). NOTE: this is not the same as enabled control. paginateOn does not prevent macro from rendering.
previousViewSize	((int)) Used if paginate state is off. if not specified, it will use a default from general.properties.
paginateOffViewSize	((int), default: -in general.properties-) A viewSize value send when turning off pagination via toggle
viewSizeSelection	((boolean), default: false) Currently officially unsupported.
altParam	Use viewIndex/viewSize as parameter names, instead of VIEW_INDEX / VIEW_SIZE
viewIndexString	(default: VIEW_INDEX) Specific param name to use
viewSizeString	(default: VIEW_SIZE) Specific param name to use Set to the value "_" to omit from URLs.
paginateToggleString	(default: PAGING) Specific param name to use
paramPrefix	(default: -empty-) Prefix added to param names. Some screens need "~". NOTE: Does not affect paramStr – caller must handle.
paramDelim	(default: "&") Param delimiter. Some screens need "/". NOTE: Does not affect paramStr – caller must handle.
pagLabels	((map)) Map of label names to labels These can be set in themes also in a styles.pagination_labels hash, where they support #getTextLabelFromExpr syntax (NOTE: the macro pagLabels arg does not support that syntax, not needed there). Supported keys: first, previous, page, next, last, viewSize, on, off
infoWidget	Definition for widget to use in place of the "count" left-hand dialog This is a map with the entries: {"content":[directive to render], "args":[hash of args to pass to directive], "always":[boolean; if true, show even if results not paged], "size":[grid size, default markup default: 2], "layout":[both|top|bottom, default: both]}
ctrlWidget	Definition for dialog to use in place of the "toggle" right-hand dialog
prioViewSize
paginateToggleOnValue
paginateToggleOffValue
passArgs

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

History#

Enhanced for 1.14.4 (added pagLabels).

---

Tree Menu#

macro treemenu#

Renders a menu in a tree fashion.

The tree can be defined in nested or flat format to describe the hierarchy, and using either macro calls or by passing item lists of maps.

For settings and plugins map arguments, child map elements which should not be interpreted as string but rather as script (such as javascript functions) can be wrapped using #wrapRawScript .

WARN: The parameters which contain full javascript code (not just string values/within-literals) are not and cannot be escaped by the macro; caller is responsible for escaping them! Use #escapeVal (preferred) or ?js_string.

Usage Examples#

text

<@treemenu type="lib-basic">
        <@treeitem text="Some item" />
        <@treeitem text="Some item">
            <@treeitem text="Some item" />
            <@treeitem text="Some item" />
        </@treeitem>
        <@treeitem text="Some item" />
    </@treemenu>

    OR

    <@treemenu type="lib-basic" items=[
        {"text":"Some item"},
        {"text":"Some item", "items":[
            {"text":"Some item"},
            {"text":"Some item"}
        ]},
        {"text":"Some item"}
    ]/>

    OR

    <@treemenu type="lib-basic">
        <@treeitem text="Some item" parent="#" id="treeitem_3_root1"/>
        <@treeitem text="Some item" parent="#" id="treeitem_3_root2"/>
        <@treeitem text="Some item" parent="treeitem_3_root2" id="treeitem_3_child1"/>
        <@treeitem text="Some item" parent="treeitem_3_root2" id="treeitem_3_child2"/>
        <@treeitem text="Some item" parent="#" id="treeitem_3_root3"/>
    </@treemenu>

    OR

    <@treemenu type="lib-basic" items=[
        {"text":"Some item", "isRoot":true, "id":"treeitem_4_root1"},
        {"text":"Some item", "isRoot":true, "id":"treeitem_4_root2"},
        {"text":"Some item", "parent":"treeitem_4_root2", "id":"treeitem_4_child1"},
        {"text":"Some item", "parent":"treeitem_4_root2", "id":"treeitem_4_child2"},
        {"text":"Some item", "isRoot":true, "id":"treeitem_4_root3"}
    ]/>

Parameters#

type	(lib-basic|lib-model, default: lib-basic) Type of tree and generation method lib-basic: uses @treeitem or items list to generate the tree items, while plugins and settings are extra settings, as simple maps lib-model: uses a (java) model from data, plugins, settings arguments to generate the tree NOTE: 2016-08-04: The default is now lib-basic.
library	(jstree, default: jstree) Library NOTE: is case insensitive
inlineItems	((boolean)) If true, generate only items, not menu container NOTE: currently unused.
id	Menu ID If omitted, will be auto-generated.
attribs	((map)) Map of other tree menu attribs NOTE: currently unused.
items	((list)) List of maps, where each hash contains arguments representing a menu item, Same as @treeitem macro parameters. Alternatively, the items can be specified as nested content.
nestedFirst	((boolean), default: false) If true, use nested items before items list, otherwise items list always first Usually should use only one of alternatives, but is versatile.
data	((object)) Data model Depends on type and library: lib-model, jstree: list of JsTreeHelper$JsTreeDataItem objects, where each object contains fields representing a tree menu item lib-basic, jstree: unused. use items instead.
settings	((object)) Tree library settings Depends on type and library: lib-model, jstree: settings model class lib-basic, jstree: map of settings, added alongside the core data
plugins	((object)) Tree plugin settings Depends on type and library: lib-model, jstree: plugins model class lib-basic, jstree: list of maps where each map follows the format: {"name":(plugin name), "settings":(map of jstree plugin settings)}
preItems	((list)) Special-case list of maps of items, added before items and nested content Excluded from sorting. Templates should generally avoid use unless specific need, but may be used by other macros.
postItems	((list)) Special-case list of maps of items, added after items and nested content Excluded from sorting. Avoid use unless specific need; may be needed by scipio menu handling. Templates should generally avoid use unless specific need, but may be used by other macros.
sort, sortBy, sortDesc	Items sorting behavior; will only work if items are specified through items list of hashes, currently does not apply to nested items. by default, sorts by text, or sortBy can specify a menu item arg to sort by. normally case-insensitive.
events	((map)) Map of javascript events to code The code is inlined into a callback function having arguments (e, data). NOTE: Must not specify "on" prefix.
defaultNodeIcon	((string), default: -depends on library-) Default (leaf) node icon Defaults: jstree: jstree-file (in standard theme)
defaultDirIcon	((string), default: -depends on library-) Default non-leaf node icon Defaults: jstree: jstree-folder (in standard theme) NOTE: Currently, this will only be used for nested jstree format. It does not apply to the flat data format (with parent: attributes).
passArgs

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

Related#

@treeitem

History#

Enhanced for 1.14.2.

---

Tree Item#

macro treeitem#

Renders a tree menu item.

Supports nested or flat format for hierarchy.

Parameters#

id	Item ID NOTE: Automatically added to attribs.
attribs	((map)|(inline)) Attributes for the item, either passed in this map, or inlined to this macro. For jstree, these are: icon, id, text, state (map container: opened, selected), type, li_attr (map), a_attr (map), etc. (see https://www.jstree.com/docs/json/ for full reference) At least "text" must be specified. "children" should be omitted and items arg used instead. "parent" should be used along with "id" when using flat format for hierarchy, where root nodes are marked using parent="#" attribute here (or using isRoot=true macro argument). NOTE: The attribs map macro argument itself is not that useful, and is mainly for bypassing the macro arguments, if needed, for example when an attribute shares the name of a macro argument with a different function. But in most cases it is more appropriate to specify inline arguments to the macro or even use the args map argument, rather than the attribs map argument. Using the attribs map argument may provide less abstraction.
isRoot	((boolean)|"", default: "") Helper flag to indicate root nodes This is mainly needed when using flat hierarchies. For jstree, passing true is the same as specifying parent="#". Default is "" which means unspecified. NOTE: 2016-08-04: At current time, unspecified means no action is taken. Subject to change internally.
items	((list)) Children items: list of maps, where each hash contains arguments representing a menu item, Same as @treeitem macro parameters. Alternatively, the items can be specified as nested content.
preItems	((list)) For children items: Special-case list of maps of items, added before items and nested content Excluded from sorting. Templates should generally avoid use unless specific need, but may be used by other macros.
postItems	((list)) For children items: Special-case list of maps of items, added after items and nested content Excluded from sorting. Avoid use unless specific need; may be needed by scipio menu handling. Templates should generally avoid use unless specific need, but may be used by other macros.
sort, sortBy, sortDesc	For children items: items sorting behavior; will only work if items are specified through items list of hashes, currently does not apply to nested items. by default, sorts by text, or sortBy can specify a menu item arg to sort by. normally case-insensitive.
nestedFirst	((boolean), default: false) For children items: if true, use nested items before items list, otherwise items list always first Usually should use only one of alternatives, but is versatile.
type
passArgs

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

Related#

@treemenu

History#

Added for 1.14.2.

---

CmsMenu#

macro cmsmenu#

CmsMenu macro, used to draw menus created with the cms menu interface. Uses menu macro to mimick original html. If menu has not been created with the CMS component, use menu macro instead.

Menu macro documentation showing menu button states

It may be used in combination with cms menus:

text

<@cmsmenu type="sidebar" menuId="9000" .../>

Parameters#

menuId	MenuId (as displayed inside of cms menu screen)
type	(generic|section|section-inline|main|sidebar|tab|subtab|button|..., default: generic) The menu type For nested menus, this will inherit the type of the parent. Passed along inside of cmsmenu macro General: generic: any content, but specific type should be preferred.
class	((css-class), default: -based on menu type-) CSS classes for menu 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) defaults are based on: styles["menu_" + type?replace("-","_")], or if missing from hash, falls back to styles["menu_default"] NOTE: for this macro, the inline "class" args is now logically combined with the "class" arg from the "args" map using the logic in combineClassArgs function, with inline having priority.
id	ID
style	Legacy menu HTML style attribute (for <ul> element)
attribs	((maps)) Other menu attributes (for <ul> element)
items	((list)) List of maps, where each hash contains arguments representing a menu item. Uses Objects generated by CMS Menu generator.
title	Menu title (abstract) This has a generic/abstract meaning and semantics meaning use will depend on the specific menu type and implementation. Currently mostly needed for button-dropdown.
passArgs

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

History#

Added for 1.14.4.