When customizing CiviCRM to display new user-interface elements, one needs to add or replace content in the page output. Prior to CiviCRM 4.2, site administrators could do this by overloading CiviCRM's Smarty templates – or by [creating "extra" templates](http://civicrm.org/blogs/dave-greenberg/now-its-easier-add-custom-behaviors-templates) -- but these solutions do not allow third-party developers (module authors or extension authors) to modify the output. CiviCRM 4.2 introduces the "Region" system which allows downstream developers to add code directly to a page.
The markup in CiviCRM has been broken up into various regions, and each region is assigned a name. Module authors can append their own snippets of code to each region. For example, to add markup at the top of the CiviCRM content area, one would put content in the "page-header" region. A more complete listing of regions is included below.
## Working with regions
A region is defined by placing a `{crmRegion}` tag within a Smarty template. For Example:
The crmRegion tag allows developers to sepcify which section of the page they wish to add their code to. A simple additon would be similar to the following
<div style="background: red; color: blue; font-size: 5em">
<marquee>
<blink>
Congratulations! You won the lottery!
</blink>
</marquee>
</div>
```
The `Add()` method will accecpt a few different paramaters for injecting content into a region:
| Parameter | Type | Description |
| --- | --- | --- |
| markup | String (HTML) | Add literal HTML code to a region |
| template | String (File path) | Load a Smarty template and add the contents to a region |
| callback | Mixed (PHP Callable) | filter the content of a region using a callback function. Function signagure would be `function myCallback(&$snippetSpecification, &$html)` |
| script | String (Javascript) | Add a `<script>` tag with Javascript code |
| jquery | String (Javascript) | Add a `<script>` tag which has been guarded using jQuery conventions `jQuery(function($) { });`
| style | String (CSS) | Add a `<style>` tag with CSS Code |
Any of the above paramaters can be combined with the following additional options to organise the content in regions
| Parameter | Type | Description |
| --- | --- | --- |
| name | String | A unique name for the snippet of content being added to the region |
| weight | Int | Relative postion of this snippet compare to other snippetts (negative - before the default conent; positive - after the default content) |
| disabled | bool | Should this snippet be displayed or hidden |
## Replace Content in a Region
If the defualt content of the region is innaproriate, then you can disable the default content and supply your own:
When adding a new region in the core templates, use a model similar to the file hierarchy of the template file itself.
For example, if adding a section in templates/CRM/PCP/Page/PCPInfo.tpl, the crmRegion name should be:
```
{crmRegion name="pcp-page-pcpinfo"}
< existing html >
{/crmRegion}
```
In some cases, we may want to have multiple regions in a template file. Ideally, model the name on the closest relevant CSS "id". For example, in templates/CRM/PCP/Form/PCP.tpl:
```
<div id="pcpFields">
{crmRegion name="pcp-form-pcp-fields"}
< existing html >
{/crmRegion}
</div>
```
As there are not many such regions in the templates at the moment, please help improve this documentation!
!!!note
Please keep in mind that changing an existing region name will break existing extensions.
## List of Regions
### Core
| Region Name | Type | Details | CiviCRM Version |
| --- | --- | --- | --- |
| ajax-snippet | (FIXME) | All AJAX pages based on AHAH/crmSnippet | 4.5.3+ |
| billing-block | The set of fields required for credit-card information, bank information, etc| Contribution pages; Event registration pages| 4.2.1+ |
| default-report-header | The HTML `<HEAD>` in the default value for report headers.| This will not affect report instances where a (presumably customized) header has been saved. (N.B. use hook_civicrm_preProcess() as hook_civicrm_buildForm will come too late to affect the default value.)| 4.6.11+ |
| export-document-header | The HTML `<HEAD>` in a PDF export.| `CRM_Utils_PDF_Utils::html2pdf` strips out all `<head>` information (including anything in the html-header region) going into a PDF.| 4.6.11+ |
| html-header | The HTML `<HEAD>` which contains metadata, scripts, styles, etc| All pages. (Note: WP support is inconsistent pending refactor.) | 4.2.0+ |
| page-header | The top of the CiviCRM content area. (Note: This may be different from the CMS's header section.) | All pages | 4.2.0+ |
| page-body | The main CiviCRM content | All pages | 4.2.0+ |
| page-footer | The bottom of the CiviCRM content area. (Note: This may be different from the CMS's footer section.) | All pages | 4.2.0+ |
| profile-form-(NAME) | Custom contact create/edit-screen based on a profile form | (NAME) corresponds to the internal name (`civicrm_uf_group.name`) | 4.4.0+ |
| profile-search-(NAME) | Custom contact search/listing-screen based on a profile form | (NAME) corresponds to the internal name (`civicrm_uf_group.name`) | 4.4.0+ |
| profile-view-(NAME) | Custom contact view-screen based on a profile form | (NAME) corresponds to the internal name (`civicrm_uf_group.name`) | 4.4.0+ |
### Price Set
| Region Name | Type | Details | CiviCRM Version |
| --- | --- | --- | --- |
| price-set-1| The block with the priceset (currently only 1 per page but 1 in name for potential for more)| CRM/Price/Form/PriceSet.tpl | 4.6.4 |
### Contributon Page
| Region Name | Type | Details | CiviCRM Version |
| Region Name | Type | Details | CiviCRM Version |
| --- | --- | --- | --- |
| contribute-form-contributionpage-addprouct-main| Wrapper region around the main fields on add product settings tab| CRM/Contribute/Form/ContributionPage/AddProduct.tpl | 4.7.13+ |
| contribute-form-contributionpage-addproduct-post| Wrapper region after the main fields on add product settings tab| CRM/Contribute/Form/ContributionPage/AddProduct.tpl | 4.7.13+ |
| contribute-form-contributionpage-amount-main| Wrapper region around the main fields on amount settings tab| CRM/Contribute/Form/ContributionPage/Amount.tpl | 4.7.13+ |
| contribute-form-contributionpage-amount-post| Wrapper region after the main fields on amount settings tab| CRM/Contribute/Form/ContributionPage/Amount.tpl | 4.7.13+ |
| contribute-form-contributionpage-custom-main| Wrapper region around the main fields on the profile settings tab| CRM/Contribute/Form/ContributionPage/Custom.tpl | 4.7.13+ |
| contribute-form-contributionpage-custom-post| Wrapper region after the main fields on the profile settings tab| CRM/Contribute/Form/ContributionPage/Custom.tpl | 4.7.13+ |
| contribute-form-contributionpage-premium-main | Wrapper region around the main fields on the preimum settings tab| CRM/Contribute/Form/ContributionPage/Premium.tpl | 4.7.13+ |
| contribute-form-contributionpage-premium-post| Wrapper region after the main fields on the preimum settings tab| CRM/Contribute/Form/ContributionPage/Premium.tpl | 4.7.13+ |
| contribute-form-contributionpage-settings-main| Wrapper region around the main fields on the main settings tab| CRM/Contribute/Form/ContributionPage/Settings.tpl | 4.7.13+ |
| contribute-form-contributionpage-settings-post| Wrapper region after the main fields on the main settings tab| CRM/Contribute/Form/ContributionPage/Settings.tpl | 4.7.13+ |
| contribute-form-contributionpage-thankyou-main"| Wrapper region around the main fields on the thank you settings tab| CRM/Contribute/Form/ContributionPage/ThankYou.tpl | 4.7.13+ |
| contribute-form-contributionpage-thankyou-post| Wrapper region after the main fields on the thank you settings tab| CRM/Contribute/Form/ContributionPage/ThankYou.tpl | 4.7.13+ |
| contribute-form-contributionpage-widget-main| Wrapper region around the main fields on the widget settings tab| CRM/Contribute/Form/ContributionPage/Widget.tpl | 4.7.13+ |
| contribute-form-contributionpage-widget-post| Wrapper region after the main fields on the widget settings tab| CRM/Contribute/Form/ContributionPage/Widget.tpl | 4.7.13+ |
### Event Pages
| Region Name | Type | Details | CiviCRM Version |
| pcp-page-pcpinfo| PCP page displayed to a visitor.| CRM/PCP/Page/PCPInfo.tpl | 4.3.0+ |
### Manage Premimums
| Region Name | Type | Details | CiviCRM Version |
| --- | --- | --- | --- |
| contribute-form-managepremiums-standard-fields| The non-collapsible fields at the top of the form.| CRM/Contribute/Form/ManagePremiums.tpl | 4.7.2+ |
| contribute-form-managepremiums-other-fields| The collapsible fields at the bottom of the form. | CRM/Contribute/Form/ManagePremiums.tpl | 4.7.2+ |
