Merge pull request #394 from seamuslee001/menu_xml_doucmentation

Add in documentation on menu XML definition

docs/framework/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

docs/hooks/hook_civicrm_xmlMenu.md

@@ -55,34 +55,9 @@ function EXAMPLE_civicrm_xmlMenu(&$files) {
 }
 ```
 
-## XML: Common
-
-Several elements are supported in any route:
-
- * `<path>` (ex:`civicrm/ajax/my-page`): This specifies the URL of the page. On a system like Drupal (which supports "clean URLs"), the full page URL would look like `http://example.org/civicrm/ajax/my-page`.
- * `<page_callback>` (ex: `CRM_Example_Page_AJAX::runMyPage` or `CRM_Example_Page_MyStuff`): This specifies the page-controller, which may be any of the following:
-    * Static function (ex: `CRM_Example_Page_AJAX::runMyPage`)
-    * A subclass of `CRM_Core_Page` named `CRM_*_Page_*` (ex: `CRM_Example_Page_MyStuff`)
-    * A subclass of `CRM_Core_Form` named `CRM_*_Form_*` (ex: `CRM_Example_Form_MyStuff`)
-    * A subclass of `CRM_Core_Controller` named `CRM_*_Controller_*` (ex: `CRM_Example_Controller_MyStuff` )
- * `<access_arguments>` (ex: `administer CiviCRM`): A list of permissions required for this page.
-    * If you'd like to reference *new* permissions, be sure to declare them with [hook_civicrm_permission](/hooks/hook_civicrm_permission.md).
-    * To require *any one* permission from a list, use a semicolon (`;`). (ex: `edit foo;administer bar` requires `edit foo` **or** `administer bar`)
-    * To require *multiple* permissions, use a comma (`,`). (ex: `edit foo,administer bar` requires `edit foo` **and** `administer bar`)
-    * At time of writing, mixing `,`s and `;`s has not been tested.
- * `<title>` (ex: `Hello world`): Specifies the default value for the HTML `<TITLE>`. (This default be programmatically override on per-request basis.)
-
-!!! caution "Caution: Wildcard sub-paths"
-    One path can match all subpaths.  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.
-
-## XML: Administration
-
-The administration screen (`civicrm/admin`) includes a generated list of fields. This content is determined by some additional elements:
-
- * `<desc>`
- * `<icon>`
- * `<adminGroup>`
- * `<weight>`
+## XML Structure
+
+See the [routing](/framework/routing.md) page for details on the XML schema.
 
 ## XML: IDS
 

mkdocs.yml

@@ -224,6 +224,7 @@ pages:
      - QuickForm: framework/quickform/index.md
      - Entity Reference Field: framework/quickform/entityref.md
   - Region Reference: framework/region.md
+  - Routing: framework/routing.md
   - Resources Reference: framework/resources.md
   - Setting Reference: framework/setting.md
   - Template Reference: