Menus generation designed in the same way as Forms Generator
The main interface is Menu
class, which creates menu
definitions. These definitions could be directly rendered to HTML via
render
method. Or getContent
method could be used to get an object
suitable as an argument for Jade Menu
mixin. In this case HTML will
be rendered as a part of Jade template.
Note: Neither i18n
nor jade
are included in the production
dependencies, but rather they are expected by some methods as
arguments. Jade
should be compatible with version 1.9.0
and i18n
with version ~0.5.0
or ~0.8.0
.
Each item should have an ID that is used for several purposes. All IDs
should match /^~?[a-zA-Z_][a-zA-Z0-9_]*$/
regular expression. ~
prefix is stripped from actual IDs.
The first one is generating HTML ID attributes. All item IDs are
prefixed with a menu ID. So generated HTML ID attributes will look
like MenuID-ItemID
. Single -
is used as a nesting separator,
--
is used to separate ID suffixes for additional elements like
links.
The second one is generating translation labels for fields. By default
translation IDs generation algorithm is the same as the HTML one, but
using non-prefixed IDs is allowed. nTP
function disables prefixing
for a single ID. Prefixing ID with ~
is similar to using nTP
function. Also menu class constructor options allow customisation of
menu translation IDs generation. HTML ID attributes are not affected
by any of these options.
- items = item-array | items
- item-array = [ ID , [ url , attributes , items ] ]
- ID =
/^~?[a-zA-Z_][a-zA-Z0-9_]*$/
- url =
string
|null
- attributes =
attributes-object
|null
| attributes-array - attributes-array =
[
attributes-object
, [attributes-object
,attributes-object
,attributes-object
] ]
attributes-object
with attribute : value
pairs is used to set
input HTML elements attributes. attributes-array
is used to set
attributes to the following elements: attributes-array[0]
- <li>
tag attributes, attributes-array[1]
- <a>
tag attributes,
attributes-array[2]
- <span>
tag attributes (text labels inside
<a>
), attributes-array[3]
- <ul>
tag attributes in nested menus.
This operations doesn't alter a menu definition, separating view style operations. As a result a menu can have several custom view renders.
It is possible to insert attributes and HTML elements into generated menus with an object. Object key are the following selectors prefixed by an element HTML ID:
::before
insertion before an element::after
insertion after an element::attributes
insertion of element attributes
For ::before
and ::after
selectors values can be either HTML
strings or arrays with mixin name and arguments (up to 9 mixin
arguments are supported). Or attribute objects for ::attributes
selector. Class attributes are concatenated, preserving classes
defined in a menu constructor.
Another way to insert attributes, based on tag/nesting combinations,
is a user supplied attrsExtender
function. It should return an
attributes-object
and it recieves the following arguments:
tag
-string
HTML tag name.level
-int
menu nesting level, the first level is 0.hasSubmenu
-bool
true if current item has submenu.
IDs can be abbreviated with the help of @
syntax, so selectors will
look like @-ItemID::Selector
.
Express 4 example application with pure-menu CSS style is in an
example
directory.
Constructor
Throws:
Error
with astring
description on malformed items definitions.
Arguments:
ID
-string
matching/^~?[a-zA-Z_][a-zA-Z0-9_]*$/
regular expression, or result ofnTP
function.options
-object
with menu options ornull
. Fields:i18nNoPrefix
-boolean
option to turn off prefixes for translation IDs,false
by default.i18nMenuID
-string
with a menu ID, overrides a default menu ID in translations.
attributes
-object
null
....items
- Rest arguments are interpreted as items definitions.
Method [caches results]
Expands menu for i18n
locale and caches results.
Arguments:
i18n
-i18n
translation library.skipCache
optional - Ignore the current cache and re-expand content.
Returns:
object
for Jade menu render.
Method
Renders HTML menu.
Arguments:
jade
-jade
library.options
-jade
and render options ornull
. Render options:attrsExtender
-function
that extends HTML tags attributes.prefixID
-string
with prefix that is added to all IDs.skipCache
- Ignore the current cache and re-expand content.
i18n
-i18n
translation library.insertions
optional -object
with HTML insertions ornull
....includeJadeFiles
optional - The rest arguments are treated as jade files pathnames to include.
Returns:
string
HTML menu.
Function
Wrapper for strings translation via __
function.
Arguments:
str
-string
to translate.
Returns:
object
that will be translated with menu.
Function
Wrapper for strings translation via __n
function.
Arguments:
str
-string
to translate.n
-integer
.
Returns:
object
that will be translated with menu.
Function
Forces usage of unprefixed IDs for translation.
Arguments:
id
-string
matching/^~?[a-zA-Z_][a-zA-Z0-9_]*$/
regular expression.
Returns:
object
that could be used as ID in menu definitions.
Constant
Path to Jade mixins file. This file contains Menu
mixin which
performs HTML rendering.
Mixin
Renders menu.
Arguments:
data
- menu data (a result of js Menu.getContent method).insertions
optional -object
with HTML insertions data ornull
.attrsExtender
optional -function
that extends HTML tags attributes. ornull
.prefixID
optional -string
with prefix that is added to all IDs ornull
.