====== Menu Builder ======

===== Description =====

Menu Builder is a plug-in that will let you create one or more menus (navigations) for your website. You can compose the navigation out of any existing element of the website, such as page, a category, an article, tag, or combination of VTE and xHTML tags resulting in intuitive menu elements like search or tag cloud. Each menu can be attached to a template separately, resulting in different (or modified) menus for different sections of the website, such as web version and mobile version. Also, you can have several menus on the same template (page), with main navigation menu showing top-level navigation and auxiliary navigation showing only current portion of the website.

===== How to Install =====

You need to access to the Plug-ins section. Click on the Plug-ins link which is located in the Main menu at the top of your administration panel.

{{:user_manual:plugin-manual:admin_menu.jpg|Admin menu}}

A list of all plug-ins currently registered to the system is displayed on the right hand side of the screen on Downloaded plug-ins tab.

To install Menu Builder you need to click on the install icon on the right side of the plug-in name.

{{:user_manual:plugin-manual:menu_builder_install.jpg|Menu Builder install}}

This will take you to the page with the installation link: Click here to Install the plug-in

{{:user_manual:plugin-manual:menu_builder_install_step_1.jpg|Menu Builder install step 1}}

After you run the installation, you will be informed that the plug-in was successfully installed.

You may easily go back to the Plug-ins page, by following the link: Click here to go to Plug-in

{{:user_manual:plugin-manual:menu_builder_install_step_2.jpg|Menu Builder install step 2}}

===== How to Uninstall =====

To uninstall Menu Builder you need to click on the uninstall icon on the right side of the plug-in name

{{:user_manual:plugin-manual:menu_builder_uninstall.jpg|Menu Builder uninstall}}

This will take you to the page with the link for uninstall: Click here to Uninstall the plug-in

{{:user_manual:plugin-manual:menu_builder_uninstall_step_1.jpg|Menu Builder uninstall step 1}}

You will be informed that the plug-in was successfully uninstalled and you may return to the Plug-ins page by clicking the link: Click here to return to Plug-in home page

{{:user_manual:plugin-manual:menu_builder_uninstall_step_2.jpg|Menu Builder uninstall step 2}}

===== Access =====

The path to the Menu Builder plug-in:

Click on the Plug-ins link (which is located in Main menu at the top of your administrator panel).

Choose Menu Builder from the list of all installed plug-ins (on the left side of the screen).

===== User level =====

This plug-in can be accessed only by users belonging to groups that are allowed to manage Menu Builder plug-in. 

===== Actions =====

**Menus** tab that is located on the left hand side of the screen holds **+Add new menu** link which takes you to new menu creation form and a list of all previously created menus. 

{{:user_manual:plugin-manual:menu_builder_menus.jpg|Menus tab}}

If you click on any item listed here, the menu settings will open on the right and you'll be able to see and change its preferences, nodes, title and template or just copy its VTE integration code. You can also **edit** a menu if you choose edit icon {{:user_manual:plugin-manual:icon_edit.jpg|Edit menu}} next to its name on the list. 

After you have applied changes to a menu click on **Save** button to apply and keep the changes. 

To **delete** a menu, just click on delete icon {{:user_manual:plugin-manual:icon_delete.jpg|Delete menu}} next to its title.

==== Add new menu ====

Click on **+Add new menu** link on the **Menus** tab and use editing area to set-up your new navigation. 

First, add its title and choose one of predefined templates for the menu from the drop-down list. 

{{:user_manual:plugin-manual:menu_builder_add_menu.jpg|Add new menu}}

<note tip>You may create your own menu templates and upload them to **VIVVO_TEMPLATE_DIR/box/menu_builder** folder. </note>

Menus consist of single items - **nodes**. On each menu you create you can have unlimited number of nodes of the same type or a mixture of categories/subcategories, pages, articles and VTE elements in a chosen order. 

After you set-up all nodes and menu preferences don't forget to click on **Add** button to save this menu. 

==== Add new node ====

Click on **+Add new node** to add new item to the menu you are creating. You can add infinite number of nodes to each menu. 

Now double click on the node to add/edit its preferences.

{{:user_manual:plugin-manual:menu_builder_node_preferences.jpg|Set node preferences}}

First choose the **type** - each node can be link, category, VTE, subcategories or all categories. 

{{:user_manual:plugin-manual:menu_builder_node_type.jpg|Add new node - choose type}}  

=== Link ===

{{:user_manual:plugin-manual:menu_builder_node_link.jpg|Add new node - link}}

**Link** menu item takes a visitor to a link specified in the Href field. It can be internal (page, category, article or a tag that is a part of your Vivvo website) or external (any external link). In case of using an external link just enter the full URL in the Href field, for example %%http://www.example.com%%. For internal links you may rely on **Search element** option - start typing a name of a page/category/article or a tag you want to link to and wait for the matching results to be found then just click on a chosen result and the Href field will be automatically populated. 

{{:user_manual:plugin-manual:menu_builder_node_search.jpg|Add new node - search element}}

Click **Apply** to save changes for the node.

**Example menu with links:**

{{:user_manual:plugin-manual:menu_builder_links.jpg|Links menu}}

=== Category ===

Choosing **Category** as a type offers a list of existing categories and subcategories so you can choose one from the Category drop-down. 

{{:user_manual:plugin-manual:menu_builder_node_category.jpg|Add new node - category}}

After you've chosen a category from the drop-down, **Node title** and **Href** fields will be automatically populated with category title and category page URL. You may edit those preferences and add different title/URL. 

{{:user_manual:plugin-manual:menu_builder_node_category_2.jpg|Add new node - category}}

Mark **Include subcategories** if you want to show subcategories of this subcategory on the menu as well. 

{{:user_manual:plugin-manual:menu_builder_node_category_3.jpg|Add new node - category}}

When you are done click **Apply** to save changes for the node.

**Example menu with categories:**

{{:user_manual:plugin-manual:menu_builder_categories.jpg|Category menu}}

=== VTE ===

Enrich menu by adding Vivvo elements like search box, links to author pages or article tags. These are only predefined elements but you can create your own templates and add, for example, newsletter subscription box or most popular articles to your menu. Just upload your custom templates to **VIVVO_TEMPLATE_DIR/box/menu_builder/widgets** folder.

For this type of node you just need to enter a title and choose a template from the drop-down menu. When you are done click **Apply** to save changes for the node.

**Example VTE menu:**

{{:user_manual:plugin-manual:menu_builder_vte.jpg|VTE menu}}

=== All Categories ===

Use one node to list all categories that exist in Vivvo system - just like default Vivvo menu. You can choose to display only top level categories or include their subcategories as well. 

{{:user_manual:plugin-manual:menu_builder_node_all_categories.jpg|Add new node - All categories}}

Click **Apply** to save changes for the node.

**Example menu with all categories:**

{{:user_manual:plugin-manual:menu_builder_all_categories.jpg|All Categories menu}}

=== Subcategories ===

Subcategories menu lists subcategories of an active category and optionally their subcategories. You'll include this navigation in your category template. 

**Example subcategories menu:**

{{:user_manual:plugin-manual:menu_builder_subcategories.jpg|Subcategories menu}}

==== Edit/delete node ====

To **edit** an item just double click on its name and change settings on the right hand side of the screen then click **Apply** button. 

When you double click an item's name you'll be able to **delete** it - just click on delete icon {{:user_manual:plugin-manual:menu_builder_delete_icon.jpg|Delete node}} next to its name.

<note warning>When you delete a parent node all the items it holds will be removed as well.</note>

Drag and drop nodes to **change their order** on the menu.

{{:user_manual:plugin-manual:menu_builder_node_reorder.jpg|Reorder nodes}}

===== Use generated code in templates =====

Menu Builder generates an integration code for each navigation you create. You may use this code and copy/paste it template file where you want the menu to appear on your website. 

{{:user_manual:plugin-manual:menu_builder_integration_code.jpg|Integration code}}

Templates are located in {ROOT}/templates/ folder, followed by the currently active theme (default is /xhtml). Commonly used templates for menus are so-called "frame" or main carrier templates holding entire pages in Vivvo site. Three most important are: 
  * homepage - homepage/default.tpl 
  * individual article page - article/default.tpl
  * category pages - category/default.tpl

  * to put menu in all pages, header or footer - box/header.tpl, box/footer.tpl

To get additional help on template files and explanation of template system, you may refer to [[../../devdoc/templates|Template manual]].

You can learn how to change template files referring to our [[../layout|User manual::Layout]] section.