Skip to content

Routing

CiviCRM's routing system defines what class gets loaded when a specific URL path is arrived at, and what permissions are required to access that route. This information is stored in XML files.

Note

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

Extension authors can add new navigation menu entries by using hook_civicrm_navigationMenu.

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

After adding or changing routing files, running cv flush should cause the changes to be picked up. If your CMS is Drupal, you may also need to clear Drupal's router cache: drush cache:clear router.

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
    • This value will be inherited from the parent path if not defined.

<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.
    • This value will be inherited from the parent path if not defined.

<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
  • Notes:
  • This value will be inherited from the parent path if not defined.

<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
  • Notes:
  • This value will be inherited from the parent path if not defined.

<page_callback>

  • Containing element: <item>
  • Description: Function called to generate the content of the route
  • Example: CRM_Contact_Page_Dashboard
  • Contains: Text
  • Notes:
  • This value will be inherited from the parent path if not defined.

<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