edit

Routing

CiviCRM's routing system is built based on XML files. These XML files define what class gets loaded when a specific path is arrived at, what permissions are required to access that route.

The standard menu XML files can be found in CRM/Core/xml/Menu/. Each route is defined as an "Item" Within the menu. In extensions you should add your menu to <extension folder>/xml/Menu/<extensionName>.xml

Note

For historical reasons, the routing files live in a Menu folder, but the contents of these files do not affect the navigation menu at the top of the screen.

Extension authors can add new menu entires by using hook_civicrm_navigationMenu.

Example

<menu>
  <item>
    <path>civicrm/payment/form</path>
    <access_callback>1</access_callback>
    <page_callback>CRM_Financial_Form_Payment</page_callback>
    <is_public>true</is_public>
    <weight>0</weight>
  </item>
  <item>
    <path>civicrm/payment/edit</path>
    <page_callback>CRM_Financial_Form_PaymentEdit</page_callback>
    <access_arguments>access CiviContribute</access_arguments>
    <component>CiviContribute</component>
  </item>
</menu>

Elements

The XML will contain a structure made up of the following elements.

Tip

The <menu> element must be the root element of the document.

<access_arguments>

  • Containing element: <item>
  • Description: Arguments to be passed to the permission checking function
  • Example: access CiviCRM;administer CiviCRM
  • Contains: Text
  • Notes:
    • If you want the permissions to be an "or" situation i.e. User needs either access CiviCRM or administer CiviCRM put a ; between the permissions. If you want it so that users need multiple permissions put a , between

<access_callback>

  • Containing element: <item>
  • Description: Function to be used to check access to the route
  • Example: CRM_Core_Permission::checkMenu
  • Contains: Text
  • Notes:
    • If you wish for this route to be public you can set it to be 1.

<adminGroup>

  • Containing element: <item>
  • Description: Is this menu part of a Administration group and if so which one
  • Example: Manage
  • Contains: Text

<comment>

  • Containing element: <item>
  • Description: ???
  • Contains: Text

<component>

  • Containing element: <item>
  • Description: ???
  • Example: CiviContribute
  • Contains: Text

<desc>

  • Containing element: <item>
  • Description: What is the description of this route
  • Example: This sets up specific eway settings
  • Contains: Text

<icon>

  • Containing element: <item>
  • Description: What icon should display next to the title in the menu
  • Example: admin/small/duplicate_matching.png
  • Contains: Text

<is_public>

  • Containing element: <item>
  • Description: This determines whether the path is considered to be "frontend" (true) or "backend" (false, the default) in CMSes that make such a distinction (Joomla! and WordPress). Attempting to visit the path via the wrong end of the site may result in denied permission or the site acting like the path doesn't exist.
  • Contains: true or false

Tip

The word "public" is a bit of a misnomer. The <is_public> element determines whether the path works on the public side of the website, but it does not grant permission for it to be seen by the public. Permissions are handled by <access_callback> and <access_arguments>.

<is_ssl>

  • Containing element: <item>
  • Description: If true, HTTP visitors will be redirected to HTTPS when they visit this path if the site has "Force Secure URLs (SSL)" set to "Yes". The visitors will not be redirected if this element is set to false or omitted.
  • Contains: true or false

<item>

  • Containing element: <menu>
  • Contains: Elements

Elements acceptable within <item>

Element Acceptable instances
<access_arguments> 0 or 1
<access_callback> 0 or 1
<adminGroup> 0 or 1
<comment> 0 or 1
<component> 0 or 1
<desc> 0 or 1
<icon> 0 or 1
<is_public> 0 or 1
<is_ssl> 0 or 1
<page_arguments> 0 or 1
<page_callback> 0 or 1
<page_type> 0 or 1
<path> 1
<path_arguments> 0 or 1
<return_url> 0 or 1
<skipBreadCrumb> 0 or 1
<title> 1
<weight> 0 or 1
  • Containing element: none (this is the root element)
  • Contains: Elements

Elements acceptable within <menu>

Element Acceptable instances
<item> 1+

<page_arguments>

  • Containing element: <item>
  • Description: Arguments passed to the function generating the content of the route
  • Example: addSequence=1
  • Contains: Text

<page_callback>

  • Containing element: <item>
  • Description: Function called to generate the content of the route
  • Example: CRM_Contact_Page_Dashboard
  • Contains: Text

<page_type>

  • Containing element: <item>
  • Description: What type of a page is this
  • Example: 1 or contribute
  • Contains: Text
  • Notes:
    • If this is not set the default is 0

<path>

  • Containing element: <item>
  • Description: The path is the url route that this menu item is for
  • Example: civicrm/admin/eway/settings
  • Contains: Text

Caution: Wild card sub-paths

One path can match all sub-paths. For example, <path>civicrm/admin</path> can match http://example.org/civicrm/admin/f/o/o/b/a/r. However, one should avoid designs which rely on this because it's imprecise and it can be difficult to integrate with some frontends.

<path_arguments>

  • Containing element: <item>
  • Description: These are arguments to be added to the url when it is loaded. These are generally useful when redirecting people after filling in the page or form
  • Example ct=Household
  • Contains: Text

<return_url>

  • Containing element: <item>
  • Description: ???
  • Contains: Text

<skipBreadCrumb>

  • Containing element: <item>
  • Description: Should this route not generate any breadcrumbs
  • Contains: true or false

<title>

  • Containing element: <item>
  • Description: Title of the route
  • Example: Eway Settings
  • Contains: Text

<weight>

  • Containing element: <item>
  • Description: Set a weight on the route to change the order of it in the menu
  • Example: 105
  • Contains: Integer
  • Notes:
    • Items with heavier weights will appear lower in the menu