routing.md

# 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](/hooks/hook_civicrm_navigationMenu.md).
    
## Example

```xml
<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>`](#menu) element must be the root element of the document.
    
### `<access_callback>` {:#access_callback}

* Containing element: [`<item>`](#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.

### `<access_arguments>` {:#access_arguments}

* Containing element: [`<item>`](#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

### `<adminGroup>` {:#adminGroup}

* Containing element: [`<item>`](#item)
* Description: Is this menu part of a Administration group and if so which one
* Example: `Manage`
* Contains: Text

### `<comment>` {:#comment}

* Containing element: [`<item>`](#item)
* Description: ???
* Contains: Text

### `<component>` {:#component}

* Containing element: [`<item>`](#item)
* Description: ???
* Example: `CiviContribute`
* Contains: Text

### `<desc>` {:#desc}

* Containing element: [`<item>`](#item)
* Description: What is the description of this route
* Example: `This sets up specific eway settings`
* Contains: Text

### `<icon>` {:#icon}

* Containing element: [`<item>`](#item)
* Description: What icon should display next to the title in the menu
* Example: `admin/small/duplicate_matching.png`
* Contains: Text

### `<item>` {:#item}

* Containing element: [`<menu>`](#menu)
* Contains: Elements

Elements acceptable within `<item>`

| Element | Acceptable instances | 
| -- | -- |
| [`<access_callback>`](#access_callback) | 0 or 1 |
| [`<access_arguments>`](#access_arguments) | 0 or 1 |
| [`<adminGroup>`](#adminGroup) | 0 or 1 |
| [`<desc>`](#desc) | 0 or 1 |
| [`<icon>`](#icon) | 0 or 1 |
| [`<is_public>`](#is_public) | 0 or 1 |
| [`<is_ssl>`](#is_ssl) | 0 or 1 |
| [`<comment>`](#comment) | 0 or 1 |
| [`<component>`](#component) | 0 or 1 |
| [`<path>`](#path) | 1 |
| [`<page_arguments>`](#page_arguments) | 0 or 1 |
| [`<page_callback>`](#page_callback) | 0 or 1 |
| [`<page_type>`](#page_type) | 0 or 1 |
| [`<path_arguments>`](#path_arguments) | 0 or 1 |
| [`<return_url>`](#return_url) | 0 or 1 |
| [`<skipBreadCrumb>`](#skipBreadCrumb) | 0 or 1 |
| [`<title>`](#title) | 1 |
| [`<weight>`](#weight) | 0 or 1 |

### `<is_public>` {:#is_public}

* Containing element: [`<item>`](#item)
* Description: ???
* Contains: `true` or `false`

### `<is_ssl>` {:#is_ssl}

* Containing element: [`<item>`](#item)
* Description: ???
* Contains: `true` or `false`

### `<menu>` {:#menu}

* Containing element: none (this is the root element)
* Contains: Elements

Elements acceptable within `<menu>`

| Element | Acceptable instances | 
| -- | -- |
| [`<item>`](#item) | 1+ |

### `<path>` {:#path}

* Containing element: [`<item>`](#item)
* Description: The path is the url route that this menu item is for
* Example: `civicrm/admin/eway/settings`
* Contains: Text

!!! Caution "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.


### `<page_arguments>` {:#page_arguments}

* Containing element: [`<item>`](#item)
* Description: Arguments passed to the function generating the content of the route
* Example: `addSequence=1`
* Contains: Text

### `<page_callback>` {:#page_callback}

* Containing element: [`<item>`](#item)
* Description: Function called to generate the content of the route
* Example: `CRM_Contact_Page_Dashboard`
* Contains: Text

### `<page_type>` {:#page_type}

* Containing element: [`<item>`](#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_arguments>` {:#path_arguments}

* Containing element: [`<item>`](#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>` {:#return_url}

* Containing element: [`<item>`](#item)
* Description: ???
* Contains: Text

### `<skipBreadCrumb>` {:#skipBreadCrumb}

* Containing element: [`<item>`](#item)
* Description: Should this route not generate any breadcrumbs
* Contains: `true` or `false`

### `<title>` {:#title}

* Containing element: [`<item>`](#item)
* Description: Title of the route
* Example: `Eway Settings`
* Contains: Text

### `<weight>` {:#weight}

* Containing element: [`<item>`](#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