Menu System Documentation
Concept
Instead of being a monolithic component, there are three types of directives that work together to create menus and similar displays:
*Menu Root
*Renderer
*Behavior
The cef-menu-root is always required and the core directive. It sets up
a controller that renderers and behaviors will use. Renderers are
responsible for generating the HTML under the menu-root, and also
activating/deactivating the view of that content. Behaviors control when
and how a piece of the menu is activated/deactivated.
In the course of assembling a menu the pre-built renderers and behaviors
may not cover all use cases. This is expected, and customization can be
handled via template edits or entirely new directives.
Finally, the directives and templates can be written in such a way to
assemble themselves from JSON data. This will allow administration tools
to be written in the future.
Assembling a Menu
The cef-menu-root directive should generally be placed on the element
that receives user input for displaying a sub-menu. For every sub-menu,
you will need a cef-menu-root directive. For example, a typical UL top
menu will have a cef-menu-root on each LI that displays a menu.
The directive has these attributes:
*cef-menu-root -- expression -- Accepts a configuration object (referred to later as menuConfig). This object checks the render, behavior, and group properties and will use the values as an alternative to attributes. Attributes take precedence over this configuration. Any data that may be needed by other directives should be passed here.
*menu-data -- two-way data-bound -- Source of data that will be available to rendering templates.
*render -- expression -- The name of a rendering directive.
*behavior -- expression -- The name of a behavior directive.
*group -- expression -- An optional group id that is used to manage certain behaviors when scope hierarchy is not available.
**Note: Since the attributes are processed as expressions, don't forget that straight string values must be quoted. <attribute="'string'" />
The cef-menu-root directive will usually insert a div just before closing the element. This new element is where the rendered content is inserted via the renderer directive. It is also where the behavior directive is placed. It's good to know where these parts go so statically-rendered menus can be set up.
Pre-Built Rendering Directives
cef-menu-render-dropdown -- This is likely to be used a lot since it renders a basic UL. For compatabilty with a common CSS menu pattern, it replaces the render containing div rather than nesting inside. It's a good general example of how to write rendering directives.
cef-menu-render-yamm -- YetAnotherMegaMenu (https://github.com/geedmo/yamm3) is a Bootstrap3 extension that adds CSS that enhances the normal dropdown markup to be a full-width mega menu base.
cef-menu-render-include -- This renders the contents of a template pulled via URL. In the menuConfig, it expects a templateUrl to be passed in.
cef-menu-render-pane -- A directive that renders its content outside of the usual rendering hierarchy. It must be paired with a cef-menu-pane directive. It takes these properties via menuConfig:
*paneId -- The id of a menu-pane directive.
*paneTemplate -- An optional template URL string.
**The directive can also transclude the contents nested inside of it.
When writing content for this directive it's important to know that scope of the cef-menu-root is the scope the content will inherit, no matter where the cef-menu-pane may be. This maintains access to the menu-data and controller.
cef-menu-render-static -- There are many reasons why you may need to integrate pre-rendered HTML into the menu. A common scenario is using DNN's DDR menu for HTML generation. You would still need to modify the DDR template to output the directives, but Angular won't be creating any markup. To use static content, you start by adding a cef-menu-root directive as normal, but do not designate a render or behavior directive. Next, you need to place the cef-menu-render-static and a behavior directive on an element nested under the cef-menu-root. A single parameter is passed as the attribute value of cef-menu-render-static, the name of a rendering directive that you want the static content to mimic. This must be a string (no extra quotes needed). What happens is that the link function of the passed-in render directive is attached to the static content.
Pre-Built Behavior Directives
cef-menu-fast-hover -- Uses mouseenter and mouseleave events to activate/deactivate.
cef-menu-hover-intent -- The HoverIntent jQuery plugin is used to prevent unintentional menu changes.
cef-menu-click -- Clicking the item activates the menu. There is no deactivate.
cef-menu-click-toggle -- Click on. Click off.
cef-menu-hover-toggle -- The name conceals the logic inside, since this does more than just toggle activation on hover (HoverIntent). It works with an established group to handle the more complex mouse behavior of mega menus. It is a good example of how to use groups in other directives.
Pre-Built Other Parts
cef-menu-set-active -- A directive that will activate the menu item it
is attached to.
cef-menu-pane -- The counterpart to cef-render-pane. This needs an id
set as the attribute value of the directive. Content from the render
directive will be rendered here.