Customize the Admin console menu

Updated on 20-October-2016 at 10:16 AM

Once you create your app, it will automatically add a new menu entry at the bottom of the menu, on the site where you're building the app. You can further customize the menu entries, by changing the menu.json file from the config folder of your app:

/_System/apps/[app key]/_config/

Syntax and formatting

Here is how the formatting and syntax should look like:

Do note that if you choose to define alternate titles or links for your app "EN" being the default language setting is required. See the rest of the article for samples.

Defining the "href" for your menu entry

For security reasons that are a very strict ways the "href" parameter can be defined. Here are a few guidelines on how it should look like.

A very important thing to note is that all the "href" links need to be either external links (see the example below regarding creating Google App links ) or contained in your app's folder. They cannot point to your site's root or any other folder on your site other than the app's folder. For example if your site URL is http://mysite.com and you have a page "/folder/page1.html" you cannot link it like below:

If you choose to point the href to an external link things are pretty straight forward. If you need to point it to your app's folder there are quite a few ways of doing that:

  • "href"="/Admin/AppLoader.aspx?client_id=[your-app-hey-kere]" - will open up the index.html or index.htm file located in "/_System/apps/[your-app-key-here]/
  • "href"="somepage.html" - will open up the "/_System/apps/[your-app-key-here]/somepage.html" page
  • "href"="/somepage.html" - (notice the extra slash) this will open up the "/_System/apps/[your-app-key-here]/somepage.html" page
  • "href"="/_System/apps/[your-app-key-here]/somepage.html" - will work just as the previous example, will open up the "/_System/apps/[your-app-key-here]/somepage.html" page
  • "href" : "/Admin/AppLoader.aspx?client_id=[your-app-hey-kere]&redirect_uri=edit.html" - will open up the edit.html page in your app's folder
  • "href"="http://google.com" - will open up the Google homepage

Customizing menu items

There are a number of customization options available, these options include:

To target a menu item element, use the id of the entry. You can get the id by inspecting the menu items DOM (e.g. Right click > Inspect element in Chrome). The ids are in the below format:

menu-item-name

When adding or targeting a menu item, ensure that the ids start with the following:

  • "menu-" (for navigation menu on left)
  • "ribbon-" (for navigation ribbon at top)
  • "quickaction-" (for the quick actions that appear when you hover the menu item's gear icon)

For a full list of menu item names, ids and default weights, see the Admin Console items list .

Note: If you are working with Web Apps, you can not have 2 or more Web Apps with the same name. This is currently not supported, however there are plans of having vendor prefixes per webapp to solve duplicate menu IDs and other issues.

Renaming or adding menu items

To rename a menu item, you first need to target the item, and then use the title attribute as shown below:

  • Replace the Existing menu item name section, with one of the current menu items.
  • Replace the New item name with your own customized name

If the entry id already exists in the menu, your changes will apply to the existing entry. Otherwise, a new entry will be added.

Example

This example renames the "CRM" menu item to "Members".

Adding a menu item to the top navigation ribbon

Adding an item to the top navigation ribbon is similar to the above method. You need to use "ribbon-item-name" in place of "menu-item-name. See below example:

Example

Since there is no "target: _blank" attribute, the content will be opened inside admin console.

Adding a menu item to an external page

To create sub menu item that opens an external page, first target the menu items name you want to create, then use the parent attribute to set this as a sub menu item.

Note: For any items you add, it is recommended you give this a unique name, such as adding a prefix of your company name. This will avoid any conflicts if you implement files from other partners/users. Example: "acmedesign_google" in place of "google".

Example

This example adds a "Google Apps" menu entry at the bottom of the menu list with links to Webmail & Drive.

Each menu item has a weight property, and menu items are sorted by weight. To reposition an item in the menu tree, first target the item, and then use the weight attribute as shown below:

For a full list of default weights, see the Admin Console items list .

If you want to add a new entry between Dashboard (10000) and Site Manager (20000), use a weight between 10001 and 19999. When there are two items with the same weight added, they'll be sorted alphabetically by title.

Example

This example overwrites the default weight for Reports (80000) to 11000 which moves the "Reports" tab in the menu to be the 2nd menu item.

Adding sub menu item that opens a webpage on which you can run API calls

This scenario is very similar to the one above, the only difference is in this case you need to go through the authorization process .

Simply put the basic steps are:

  • register an app and create its folder structure
  • create the menu.json folder
  • make sure the app's index.html page is in place - this is the page the user will get to after clicking the menu entry we are about to add

Let's take a look at an example, we havee two different apps, one named "Customer database", one named "Customer Orders". We will create a menu entry named "My customers" and place links for my two apps under it.

For this scenario here is how the content of the menu.json file should look like:

Here is how the menu entry looks like once everything is in place:

 

After you click any of the app links you will be taken to the app's landing page and because we used the App Loader to ge there we also have an access token generated we can then use to authorize API calls.

Removing an item

To hide a menu item from the tree, first target the item and then set the visible: attribute to false as below:

Example

This example removes the Settings > Sitemap entry for all users.

Adding localized names and links

Depending on the admin users language setting for the Admin Console, you can display different link titles and URLs.

Business Catalyst will use the values corresponding to the current users' language, as selected in User > My Details. See below accepted language codes:

  • en
  • de
  • es
  • fr
  • se
  • nl
  • jp

If the current users' language doesn't match any of the values you provided, the default "en" entry will be used. Therefore, it is required to always define "en".

The 'title' and 'attr' parameters also accept a key-value object as well as string. See below example.

Example

The below example displays a localized version of the "Authors" sub menu items.

Displaying a menu item based on the existence of another item

You can hide/show menu items, based on whether another item is present using the applyIf: attribute. See below example.

Example

The below example displays an entry based on a blog created using two webapps, posts and authors. The top-level menu entry is called "Blog", with child entry items of "Posts" and "Authors". In this example, the Web App entries are also hidden.

The ID of the menu item corresponding to webapp "Posts" will be:

menu-webapp-posts (a slug version of your Web app name)

Displaying a menu item based on the admin user Roles

You can hide/show menu items, based on the Role the logged in user is assigned to. Ensure that the role exists in the admin conosle and then target this role using the userHasRoles attribute. See below example.

Example

The below example will update the blog example above, so that the default Web App menus are hidden from business owners, and only visible to the partner.

Example using all the above methods

In this example we will add several localized menu items that have user roles based conditions as well as dependencies.

The code below will achieve the following:

  • Add a "Useful links" section with child items that point to various panels in the Admin Console.
  • Add a Blog section that appears only if the "Useful links" section is present.
  • The Blog section has child items that point to 2 external pages.
  • If the user has the Admin Console language set to "Francais", the Blog section sub menus will be in French.
  • The "Reports" tab is hidden for anyone that is not in the Administrators2 role.

Index of Admin Console items

The below table is a reference used with the Open Admin method. The table outlines all the default menu item names, and the associated ids and weights.

Menu Item Names ID Default Weight
Dashboard menu-dashboard 10000
Site Manager menu-site-manager 20000
Pages menu-webpages 10000
Page Templates menu-site-templates 20000
Module Templates menu-module-templates 30000
Content Holders menu-content-holders 40000
Menus menu-dynamic-menus 50000
Web Forms menu-webforms 60000
File Manager menu-file-manager 70000
Secure Zones menu-secure-pages 80000
URL Redirects menu-url-redirects 90000
Site Search menu-site-search 100000
System Pages menu-system-messages 110000
System E-Mails menu-system-emails 120000
Web Apps menu-webapps 30000
Modules menu-modules 40000
Blogs menu-blogs 10000
Events menu-events 20000
Photo Galleries menu-galleries 30000
News menu-news 40000
Media Downloads menu-downloads 50000
Comments menu-comments 60000
FAQs menu-faq 70000
Ad Rotators menu-banners 80000
Forums menu-forums 90000
CRM menu-customers 50000
Search menu-customers-search 30000
Customers menu-customers-manage 40000
Orders menu-orders 50000
Cases menu-cases 60000
Event Bookings menu-bookings 70000
Opportunities menu-opportunities 80000
Sales Forecasts menu-forecasts 90000
Extend CRM Database menu-customers-database 100000
E-Commerce menu-ecommerce 60000
Products menu-products 10000
Catalogs menu-catalogs 20000
Discount Codes menu-discount-codes 30000
Gift Vouchers menu-giftvouchers 40000
Affiliate Programs menu-affiliate-programs 50000
Payment Gateways menu-payment-gateways 60000
Tax Codes menu-taxcodes 70000
Shipping Options menu-shipping-options 80000
Shop Settings menu-settings-shop 90000
E-Mail Marketing menu-email-marketing 70000
E-Mail Campaigns menu-email-campaigns 10000
Mailing Lists menu-mailing-lists 20000
Reports menu-reports 80000
Visitors menu-reports-visitors 10000
Traffic Sources menu-reports-traffic 20000
Website Content menu-reports-content 30000
Web Forms Usage menu-reports-webforms 40000
E-Commerce menu-reports-ecommerce 50000
E-Mail Campaigns menu-reports-email-campaigns 60000
Custom Reports menu-reports-custom 70000
Admin Reports menu-reports-admin-usage 90000
Site Settings menu-site-settings 90000
Site Domains menu-settings-domains 10000
E-Mail Accounts menu-settings-emailaccounts 20000
Admin Users menu-settings-adminusers 30000
User Roles menu-settings-userroles 40000
Categories menu-settings-categories 50000
Manage Workflows menu-settings-workflows 60000
Social Integration menu-settings-facebook 70000
Mobile Support menu-settings-mobilesupport 80000
Captcha menu-settings-captcha 90000
Site Map menu-settings-site-map 100000
RSS Channels menu-settings-rss-channels 110000
Site Billing menu-billing-settings 120000
Customer Service Ticketing menu-settings-service-ticketing 130000
QuickBooks menu-settings-quickbooks 140000
API Integration menu-settings-api-integration 150000
Site Management menu-generalsettings 170000
Secure Domain Redirection menu-settings-secure-redirect 180000
Beta Features menu-settings-beta-features 190000