menus-generator

Menus Generator

Menus generation designed in the same way as Forms Generator

Description

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.

Identifiers or IDs

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 definitions

• 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.

HTML and attributes insertion

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.

Example

Express 4 example application with pure-menu CSS style is in an example directory.

API

Menu(ID, options, attributes, ...items)

Constructor

Throws:

• Error with a string description on malformed items definitions.

Arguments:

• ID - string matching /^~?[a-zA-Z_][a-zA-Z0-9_]*$/ regular expression, or result of nTP function.
• options - object with menu options or null. 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.

Menu.getContent(i18n, skipCache)

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.

Menu.render(jade, options, i18n, insertions, ...includeJadeFiles)

Method

Renders HTML menu.

Arguments:

• jade - jade library.
• options - jade and render options or null. 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 or null.
• ...includeJadeFiles optional - The rest arguments are treated as jade files pathnames to include.

Returns:

• string HTML menu.

__(str)

Function

Wrapper for strings translation via __ function.

Arguments:

• str - string to translate.

Returns:

object that will be translated with menu.

__n(str, n)

Function

Wrapper for strings translation via __n function.

Arguments:

• str - string to translate.
• n - integer.

Returns:

object that will be translated with menu.

nTP(id)

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.

includeJade

Constant

Path to Jade mixins file. This file contains Menu mixin which performs HTML rendering.

Jade API

Menu(data, insertions, attrsExtender, prefixID)

Mixin

Renders menu.

Arguments:

• data - menu data (a result of js Menu.getContent method).
• insertions optional - object with HTML insertions data or null.
• attrsExtender optional - function that extends HTML tags attributes. or null.
• prefixID optional - string with prefix that is added to all IDs or null.