.. _create_a_menu_layout:

Create a Menu Layout
--------------------


.. _19.3.1|VOSS-546|EKB-3607:
.. _20.1.1|VOSS-670|EKB-5199:
.. _21.1|VOSS-770|EKB-8081:


This procedure adds a new menu layout.


.. note::

   When editing an existing menu layout, updates to the menu layout display only once the relevant users have 
   logged out and logged in again.



**Perform the following steps**:

#. Log in as provider or reseller administrator, or higher.
#. Choose the hierarchy for the new menu layout.
#. Go to (default menu) **Role Management > Menu Layouts**.
#. View existing menu layouts. 

   * To create a new menu layout based on settings in an existing menu layout (recommended), click 
     on the menu layout you want to re-use; then, in the editing screen, click the toolbar **Clone** icon 
     to create a new record with pre-populated settings. 
     
   * To create a new menu layout without existing settings, click the toolbar Plus icon (**+**) to open 
     the **Menu Layouts/New Record** page. 

#. On the **Menu Layouts** page, in the **Name** and **Description** fields, 
   fill out a name and a description for the new menu layout.

   .. note:: 

      If you're editing a clone of an existing menu layout, you may need to edit exisitng 
      settings and add new values for the new menu layout. 

#. Add menu items (or edit existing settings for a cloned menu layout):  
   
   * In the **Menu Items** section, click the Plus icon (+) to open the menu layout editing page.
   
   * Configure the new menu item:

     * Enter a display title and description for the new menu item.

     * Optionally, in the **Condition** field, specify a macro to use as a criteria that 
       determines whether the menu and its sub-menus display.  
       
       .. note:: 
          When the macro evaluates to true, the menu and its sub-menus display, else, when 
          the macro evaluates to false, the menu and its sub-menus are hidden. The default is 
          true. The default also applies when no condition criteria is specified. See the following 
          topics in the Core Feature Guide for details: Menu Layout Page, Macros in VOSS-4-UC 

     * From the **Icon** drop-down, choose an icon for the menu item. 

     * From the **Type** drop-down, select the model type to associate with the title
       you defined (above).

     * In the **Href** field, define a link to to be used for external or internal links.

       .. note::

          Hrefs are generally recommended for external links. For backwards compatibility, hrefs
          can be used for links within the application, to link directly to a form:

          For example, the Add Phone page would have the following href
          value: ``api/relation/SubscriberPhone/add``

          In this case, you will need to use JSON format menu import, or bulk load, to add
          any associated field display policies (FDPs) and configuration templates for the
          menu item.

          It is recommended that you do not use hrefs to reference ``view/`` type models.

     * Select the **Field Display Policy** and the **Configuration Template** for this menu item.
     * From the **Custom Component** drop-down, select the VOSS portal custom component.
       See: :ref:`voss-custom-components`.
     * From the **Landing Page** drop-down, select the landing page to associate with the
       menu item.

       .. note::

          * This option is only available in the new VOSS-4-UC Admin Portal GUI. 
          * Sub-menus cannot be landing pages. 

     * From the **Display As** drop-down, select the display format for this menu item. Options
       are as follows:

       * List:

         Default. If you choose List display, and you've selected a default field display policy and
         configuration template for the model type, users with a user role
         associated with the menu layout view the model type based on these options. It is also
         possible to filter the list view. See :ref:`menus_landing_configurable_filters`.

         If you choose List display referenced by type or href, note that a tool
         (``tool/[toolname]``) can also be presented as a list, for
         example: ``/api/tool/Transaction/?entity=data/Event&operation=execute``

       * Landing Page:

         If you choose Landing Page display, you can select an existing landing page,
         which will display when this menu item is chosen. See :ref:`landing_pages` and :ref:`create_a_landing_page`. 

         Note that this option is *only* is only available if you're using the new VOSS Admin Portal GUI.

       * Form:

         If you're using href and you choose the Form display, note that the href value points to a
         model instance with the pkid, for example ``data/Countries/5331a739d0278d7893e26d2e``,
         or ends with ``/add/``.

         The ``view/`` model types always open the *Add* form; thus, if used, the value should not
         have the ``/add/`` endpoint, for example, as in this JSON:

         ::

            {
              "type": "view/QuickSubscriber",
              "display": "form",
              "title": "Quick Add Subscriber"
            }

       * External Link:

         Choosing an External Link display is the recommended use with href, where a URL specified as the href
         value opens as a new browser tab. You will need to disable pop-up blocking on the users browsers to
         allow the external link to resolve.

       * Tree (if available)

         Choosing a Tree display shows a tree view of the resource. When using href with Tree display,
         the href provides the tree path.

   * Configure fixed and configurable filters for the new menu item.
   * Click **OK** to add the menu item. 
   * To add additional menu items, repeat step 6.
     
     The menu items you added display in the **Menu Items** section of the Menu Layouts/New Record page, 
     one per row in the table. 

#. To re-order menu items, hold down the hamburger icon in the first column for the relevant row; then 
   drag the menu item to the required position in the table. 

#. Click the **Save** icon on the toolbar to add the new menu layout. 

#. Assign the menu layout to the appropriate roles. 




.. rubric:: Related Topics

*  
  .. raw:: latex

     Menu Layouts in the Core Feature Guide

  .. raw:: html
  
     <a href="concepts-menu-layout.html">Menu Layouts</a> 

*  
  .. raw:: latex

     Custom Icon Names Reference in the Core Feature Guide

  .. raw:: html
  
     <a href="reference-bap-interface-custom-icons-1.html">Custom Icon Names Reference</a> 

*  
  .. raw:: latex

     Landing Pages in the Core Feature Guide

  .. raw:: html
  
     <a href="concepts-landing-page.html">Landing Pages</a> 

*  
  .. raw:: latex

     Create a Landing Page in the Core Feature Guide

  .. raw:: html
  
     <a href="tasks-landing-page.html">Create a Landing Page</a> 

*  
  .. raw:: latex

     Menu Layout Page in the Core Feature Guide

  .. raw:: html
  
     <a href="reference-data_MenuLayout_field_descriptions.html">Menu Layout Page</a> 

*  
  .. raw:: latex

     Configurable Filters in Menus and Landing Pages in the Core Feature Guide

  .. raw:: html
  
     <a href="concepts-menus-landing-configurable-filters.html">Configurable Filters in Menus and Landing Pages</a>