.. _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. #. Log in to VOSS Automate as a Provider or Reseller administrator, or higher. #. Choose the hierarchy for the new menu layout. #. Go to (default menus) **Role Management > Menu Layouts**. #. To create a new menu layout ... * Based on settings in an existing menu layout (recommended) (create a clone) Click on the menu layout you want to re-use. On the editing screen, click the toolbar **Clone** icon. A new record is created with pre-populated settings. * Without existing settings (a new record) Click the toolbar Plus icon (**+**) to open the **Menu Layouts/New Record** page. #. Fill out a name and description for the new menu layout. .. note:: If you're editing a clone of an existing menu layout, you may need to edit existing 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 Automate * 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 Automate Admin Portal GUI. * Sub-menus cannot be landing pages. * Landing pages do not have context-sensitive help. * 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. .. note:: When editing a menu layout, updates display only once you've logged out and logged in again. .. _menu_layout_field_reference: Menu Layout Page .................. .. _21.1|VOSS-770|EKB-8084: .. _21.1|VOSS-770|EKB-8083: This section describes the fields and configuration options on the Menu Layout page. .. note:: To open this page, go to (default menu) **Role Management > Menu Layouts**, then click on an existing menu layout to edit it (or to clone it to create a new record based on an existing menu layout), or click the Plus icon (+) on the toolbar to add a new menu layout. .. tabularcolumns:: |p{3cm}|p{3.5cm}|p{7.5cm}| +--------------------------+-------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Title | Field Name | Description | +==========================+=========================+===============================================================================================================================================================+ | Name | name | Mandatory. The name of the menu layout. | +--------------------------+-------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Description | description | A description of the menu layout. | +--------------------------+-------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+ | Menu Items | menu\_items | The list of menu items and -sub items that belong to the menu layout. | +--------------------------+-------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------+ Menu Items '''''''''''' The table describes configuration options for the menu items on the Menu Layouts page: .. tabularcolumns:: |p{3cm}|p{3.5cm}|p{7.5cm}| +------------------------+-------------------------+------------------------------------------------------------------------------------------+ | Title | Field Name | Description | +========================+=========================+==========================================================================================+ | Title | title | The menu item title as it will show on the menu. | +------------------------+-------------------------+------------------------------------------------------------------------------------------+ | Condition | | Allows you to display/hide a menu and its sub-menus based on a condition specified | | | | in the macro. If the macro evaluates to true the menus and sub-menus display, else, | | | | when false, the menu and its sub-menus are hidden. The default is True. See the | | | | Advanced Configuration Guide for more information about using macros. | +------------------------+-------------------------+------------------------------------------------------------------------------------------+ | Icon | | The icon to use for the menu item. | | | | | +------------------------+-------------------------+------------------------------------------------------------------------------------------+ | Type | type | The model type to associate with the menu item title. | +------------------------+-------------------------+------------------------------------------------------------------------------------------+ | Href | href | If a direct reference to a model type is used for the menu item, the specified path. | +------------------------+-------------------------+------------------------------------------------------------------------------------------+ | Field Display Policy | field\_display\_policy | The field display policy to associate with the menu item. | +------------------------+-------------------------+------------------------------------------------------------------------------------------+ | Configuration Template | configuration\_template | The configuration template to associate with the menu item. | +------------------------+-------------------------+------------------------------------------------------------------------------------------+ | Custom Components | | Admin Portal core custom components. Options in the drop-down depend on | | | | the model you choose in the **Type** field, For example, when choosing model type | | | | view/AddPhone, the custom component available for selection is **Add Phone**. The | | | | custom components allow you to display GUI content (such as landing pages, lists, | | | | and forms) in the same layout as they appear in the Business Admin Portal. | | | | | | | | Custom components are also available for multi vendor environments and for | | | | Microsoft-only environments. | | | | This feature is only available in the new VOSS Automate Admin Portal. | +------------------------+-------------------------+------------------------------------------------------------------------------------------+ | Landing Page | | The landing page to display, when the **Display As** option for the menu item is set | | | | to **Landing Page**. This option is only available in the new VOSS Automate Admin Portal | | | | GUI. Note that sub-menus cannot be selected as landing pages. | +------------------------+-------------------------+------------------------------------------------------------------------------------------+ | Display As | display | The display format of the model types of the menu item. Options are: | | | | | | | | * **Form** for a single instance | | | | * **List** or **Tree** for more than one instance | | | | * **Landing Page** for an existing landing page. (This option is available only | | | | the new VOSS Automate Admin Portal GUI. | | | | | | | | The default is **List**. | +------------------------+-------------------------+------------------------------------------------------------------------------------------+ Filters '''''''' The table describes configuration options for Configurable and Fixed Filters on the Menu Layouts page: .. note:: Fixed filters çannot be removed. .. tabularcolumns:: |p{3cm}|p{3.5cm}|p{7.5cm}| +----------------------+--------------------+-------------------------------------------------------------------+ | Title | Field Name | Description | +======================+====================+===================================================================+ | Configurable Filters | filter_options.[n] | For **List** option only. | +----------------------+--------------------+-------------------------------------------------------------------+ | Filter By | filter_by | Attributes of the **Type** can be chosen from the drop-down list. | +----------------------+--------------------+-------------------------------------------------------------------+ | Filter Type | filter_type | Choose the matching operator for the filter. | +----------------------+--------------------+-------------------------------------------------------------------+ | Filter String | filter_string | Choose the value that the matching operator should match by. | +----------------------+--------------------+-------------------------------------------------------------------+ .. rubric:: Related Topics * :ref:`business-admin-portal-interface-custom-icon-names-reference` * .. raw:: latex Advanced Configuration Guide .. raw:: html Advanced Configuration Guide * .. raw:: latex Menu Layouts in the Core Feature Guide .. raw:: html Menu Layouts * .. raw:: latex Configurable Filters in Menus and Landing Pages in the Core Feature Guide .. raw:: html Configurable Filters in Menus and Landing Pages * .. raw:: latex Macros in VOSS Automate in the Core Feature Guide .. raw:: html Macros in VOSS Automate * .. raw:: latex Custom Icon Names Reference in the Core Feature Guide .. raw:: html Custom Icon Names Reference * .. raw:: latex Landing Pages in the Core Feature Guide .. raw:: html Landing Pages * .. raw:: latex Create a Landing Page in the Core Feature Guide .. raw:: html Create a Landing Page