Skip to content
Snippets Groups Projects
Commit d7a8a988 authored by Sean Madsen's avatar Sean Madsen Committed by GitHub
Browse files

Merge pull request #227 from totten/master-ids 

CRM-20926 - hook_civicrm_{alter,xml}Menu - Fill in docs. Add PHPIDS docs.
parents c97326bb 51431846
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/hooks/hook_civicrm_alterMenu.md
+ 7
− 2
View file @ d7a8a988
......@@ -6,8 +6,6 @@ This hook is called when building CiviCRM's list of HTTP routes and should be us
## Notes
You will need to visit `/civicrm/menu/rebuild?reset=1` to pick up your additions.
!!! note "Comparison of Related Hooks"
This is one of three related hooks. The hooks:
......@@ -15,6 +13,9 @@ You will need to visit `/civicrm/menu/rebuild?reset=1` to pick up your additions
- [hook_civicrm_alterMenu](/hooks/hook_civicrm_alterMenu.md) manipulates the list of HTTP routes (using PHP arrays)
- [hook_civicrm_xmlMenu](/hooks/hook_civicrm_xmlMenu.md) manipulates the list of HTTP routes (using XML files)
!!! tip "Applying changes"
Menu data is cached. After making a change to the menu data, [clear the system cache](/tools/debugging.md#clearing-the-cache).
## Availability
......@@ -35,6 +36,10 @@ Added in CiviCRM 4.7.11.
- "*access_callback*": (usually omitted)
- "*access_arguments*": Description of required permissions. Ex:
*array(array('access CiviCRM'), 'and')*
- "*ids_arguments*": This array defines any [page-specific PHPIDS exceptions](/hooks/hook_civicrm_xmlMenu.md#xml-ids). It includes any of these three child elements:
- "*json*": Array of input fields which may contain JSON data.
- "*html*": Array of input fields which may contain HTML data.
- "*exceptions*": Array of input fields which are completely exempted from PHPIDS.
## Returns
......
docs/hooks/hook_civicrm_xmlMenu.md
+ 95
− 36
View file @ d7a8a988
......@@ -7,10 +7,6 @@ used to render urls in CiviCRM.
## Notes
This hook should be used when you want
to register your custom module url's in CiviCRM. You will need to visit
`/civicrm/menu/rebuild?reset=1` to pick up your additions.
!!! note "Comparison of Related Hooks"
This is one of three related hooks. The hooks:
......@@ -18,7 +14,9 @@ to register your custom module url's in CiviCRM. You will need to visit
- [hook_civicrm_alterMenu](/hooks/hook_civicrm_alterMenu.md) manipulates the list of HTTP routes (using PHP arrays)
- [hook_civicrm_xmlMenu](/hooks/hook_civicrm_xmlMenu.md) manipulates the list of HTTP routes (using XML files)
!!! tip "Applying changes"
Menu data is cached. After making a change to the menu data, [clear the system cache](/tools/debugging.md#clearing-the-cache).
## Definition
......@@ -26,43 +24,104 @@ to register your custom module url's in CiviCRM. You will need to visit
## Parameters
- $files the array for files used to build the menu. You can append
- `$files` the array for files used to build the menu. You can append
or delete entries from this file. You can also override menu items
defined by CiviCRM Core.
## Returns
- null
- `null`
## Example
Here's how you can override an existing menu item. First create an XML
file like this, and place it in the same folder as your hook
implementation:
<?xml version="1.0" encoding="iso-8859-1" ?>
<menu>
<item>
<path>civicrm/ajax/contactlist</path>
<page_callback>CRM_Contact_Page_AJAX::getContactList</page_callback>
<access_arguments>my custom permission</access_arguments>
</item>
</menu>
<?xml version="1.0" encoding="iso-8859-1" ?>
<menu>
<item>
<path>civicrm/ajax/contactlist</path>
<page_callback>CRM_Contact_Page_AJAX::getContactList</page_callback>
<access_arguments>access CiviCRM AJAX contactlist</access_arguments>
</item>
</menu>
\
Drupal developers can define 'my custom permission' using
[hook_perm](http://api.drupal.org/api/function/hook_perm) . Then create
a hook implementation like this:
function EXAMPLE_civicrm_xmlMenu( &$files ) {
$files[] = dirname(__FILE__)."/my_file_name_above.xml";
}
\ No newline at end of file
To define a new route, create an XML file (`my_route.xml`) in your extension or module:
```xml
<?xml version="1.0" encoding="iso-8859-1" ?>
<menu>
<item>
<path>civicrm/ajax/my-page</path>
<page_callback>CRM_Example_Page_AJAX::runMyPage</page_callback>
<access_arguments>administer CiviCRM</access_arguments>
</item>
</menu>
```
and register this using `hook_civicrm_xmlMenu`:
```php
function EXAMPLE_civicrm_xmlMenu(&$files) {
$files[] = dirname(__FILE__) . '/my_route.xml';
}
```
## 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: IDS
[PHPIDS](https://github.com/PHPIDS/PHPIDS) provides an extra layer of
security to mitigate the risk of cross-site scripting vulnerabilities, SQL
injection vulnerabilities, and so on. In CiviCRM, PHPIDS scans all inputs
for suspicious data (such as complex Javascriptor SQL code) before allowing
the page-controller to execute.
However, in some rare occasions, it is expected that the page-controller
will accept otherwise suspicious data -- for example, a REST endpoint may
accept JSON which superfically resembles complex XSS Javascript code; or an
administrative form may allow admins to customize the HTML of a screen.
When processing these page-requests, PHPIDS may generate false alarms.
In the following example, we provide hints to PHPIDS indicating that the
page `civicrm/my-form` accepts some inputs (`field_1`, `field_2`, `field_3`,
and `field_4`) which may ordinarily look suspicious.
```xml
<?xml version="1.0" encoding="iso-8859-1" ?>
<menu>
<item>
<path>civicrm/my-form</path>
...
<ids_arguments>
<!-- Fields #1 and #2 accept JSON input. These are partially exempt from PHPIDS -- they use less aggressive heuristics. -->
<json>field_1</json>
<json>field_2</json>
<!-- Field #3 accepts HTML input. It is partially exempt from PHPIDS -- they use less aggressive heuristics. -->
<html>field_3</html>
<!-- Field #4 accepts anything; it is not protected by PHPIDS heuristics. -->
<exception>field_4</exception>
</ids_arguments>
</item>
</menu>
```
!!! tip "Tip: Narrow exceptions are better than blanket exceptions"
The `<ids_arguments>` element allows you to define a narrow exception for a specific field on a specific page.
[hook_civicrm_idsException](/hooks/hook_civicrm_idsException.md) supports a blanket exemption for the entire page.
When possible, it is better to use a narrow exception.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment