Skip to content
Snippets Groups Projects
Commit 67f32f0a authored by Sean Madsen's avatar Sean Madsen
Browse files

Extensive markdown improvements

parent d4964538
No related branches found
No related tags found
1 merge request!271Migrate wiki pages on UI reference
Hide whitespace changes
Inline Side-by-side
Showing
with 412 additions and 995 deletions
docs/framework/ui.md
+ 412
− 995
View file @ 67f32f0a
# Accordions
# User Interface Reference
CiviCRM uses accordions throughout its UI to minimize the visual weight
of the page (hiding less used pieces of content).
## Accordions
There are two types of accordions in use in CiviCRM:
1\) the more commonly used accordion widget which hides content already
in the rendered page
2\) the more advanced widget that uses ajax to render content when the
accordion header has been clicked
The format for a common accordion widget (collapsed by default) is as
follows:
<div class="code panel" style="border-width: 1px;">
CiviCRM uses accordions throughout its UI to minimize the visual weight of the page (hiding less used pieces of content).
<div class="codeContent panelContent">
There are two types of accordions in use in CiviCRM:
<div class="crm-accordion-wrapper collapsed">
<div class="crm-accordion-header">
Accordian Title here
</div><!-- /.crm-accordion-header -->
<div class="crm-accordion-body">
<div class="crm-block crm-form-block crm-form-title-here-form-block">
Accordion Body here
</div><!-- / .crm-block -->
</div><!-- /.crm-accordion-body -->
</div><!-- /.crm-accordion-wrapper -->
1. The more commonly used accordion widget which hides content already in the rendered page
1. The more advanced widget that uses ajax to render content when the accordion header has been clicked
</div>
The format for a common accordion widget (collapsed by default) is as follows:
```html
<div class="crm-accordion-wrapper collapsed">
<div class="crm-accordion-header">
Accordion Title here
</div>
<div class="crm-accordion-body">
<div class="crm-block crm-form-block crm-form-title-here-form-block">
Accordion Body here
</div>
</div>
</div>
```
Use class="crm-accordion-wrapper open" if you want the accordion body to
be open when the page loads.
Dynamic classes that are automatically applied to this type of accordion
are as follows:
Use `class="crm-accordion-wrapper open"` if you want the accordion body to be open when the page loads.
*.crm-container .open .crm-accordion-header* - applied when
crm-accordion-body is visible\
**.crm-container .collapsed .crm-accordion-header* - applied when
crm-accordion-body is hidden\
*
Dynamic classes that are automatically applied to this type of accordion are as follows:
*.crm-accordion-header:hover* - css pseudo-class
* `.crm-container .open .crm-accordion-header` - applied when `crm-accordion-body` is visible
* `.crm-container .collapsed .crm-accordion-header` - applied when `crm-accordion-body` is hidden
* `.crm-accordion-header:hover` - css pseudo-class
crmAccordions function is automatically included in Common.js and does
`crmAccordions` function is automatically included in `common.js` and does
not need to be added to templates that already include that file.
------
to make an ajax accordion work automatically (including opening and
loading accordions on page load):
<div class="code panel" style="border-width: 1px;">
<div class="codeContent panelContent">
// Example from templates/CRM/Contribute/Form/Contribution.tpl// bind first click of accordion header to load crm-accordion-body with snippet
// everything else taken care of by cj().crm-accordions()
CRM.$(function($) {
cj('#adjust-option-type').hide();
cj('.crm-ajax-accordion .crm-accordion-header').one('click', function() {
loadPanes(cj(this).attr('id'));
});
cj('.crm-ajax-accordion:not(.collapsed) .crm-accordion-header').each(function(index) {
loadPanes(cj(this).attr('id'));
});
});
// load panes function calls for snippet based on id of crm-accordion-header
function loadPanes( id ) {
var url = "{/literal}{crmURL p='civicrm/contact/view/contribution' q='snippet=4&formType=' h=0}{literal}" + id;
{/literal}
{if $contributionMode}
url = url + "&mode={$contributionMode}";
{/if}
{if $qfKey}
url = url + "&qfKey={$qfKey}";
{/if}
{literal}
if (! cj('div.'+id).html()) {
var loading = '<img src="{/literal}{$config->resourceBase}i/loading.gif{literal}" alt="{/literal}{ts escape='js'}loading{/ts}{literal}" />&nbsp;{/literal}{ts escape='js'}Loading{/ts}{literal}...';
cj('div.'+id).html(loading);
cj.ajax({
url : url,
success: function(data) { cj('div.'+id).html(data).trigger('crmLoad'); }
});
}
}
</div>
</div>
# Buttons
To make an ajax accordion work automatically (including opening and loading accordions on page load):
```smarty
{literal}
// Example from templates/CRM/Contribute/Form/Contribution.tpl
// bind first click of accordion header to load crm-accordion-body with snippet
// everything else taken care of by cj().crm-accordions()
CRM.$(function($) {
cj('#adjust-option-type').hide();
cj('.crm-ajax-accordion .crm-accordion-header').one('click', function() {
loadPanes(cj(this).attr('id'));
});
cj('.crm-ajax-accordion:not(.collapsed) .crm-accordion-header').each(function(index) {
loadPanes(cj(this).attr('id'));
});
});
// load panes function calls for snippet based on id of crm-accordion-header
function loadPanes( id ) {
var url = "{/literal}{crmURL p='civicrm/contact/view/contribution' q='snippet=4&formType=' h=0}{literal}" + id;
{/literal}
{if $contributionMode}
url = url + "&mode={$contributionMode}";
{/if}
{if $qfKey}
url = url + "&qfKey={$qfKey}";
{/if}
{literal}
if (! cj('div.'+id).html()) {
var loading = '<img src="{/literal}{$config->resourceBase}i/loading.gif{literal}" alt="{/literal}{ts escape='js'}loading{/ts}{literal}" />&nbsp;{/literal}{ts escape='js'}Loading{/ts}{literal}...';
cj('div.'+id).html(loading);
cj.ajax({
url : url,
success: function(data) { cj('div.'+id).html(data).trigger('crmLoad'); }
});
}
}
```
## Buttons
Buttons initiate an immediate action.
......@@ -108,707 +85,295 @@ CiviCRM provides a pre-themed button element, to be used for buttons
throughout the system. Button elements may contain any of the optional
icons provided by CiviCRM.
The code to create a button **with** an icon:
<div class="code panel" style="border-width: 1px;">
<div class="codeContent panelContent">
* Create a button with an icon:
<a class="button_name button" href="#">
<span>
<div class="icon icon_name-icon"></div>
Button Text
</span>
```html
<a title="Button Text" class="button_name button" href="#">
<span>
<div class="icon icon_name-icon"></div>
Button Text
</span>
</a>
```
</div>
</div>
The code to create a button **without** an icon:
<div class="code panel" style="border-width: 1px;">
* Create a button *without* an icon:
<div class="codeContent panelContent">
<a class="button_name button" href="#">
<span>
Button Text
</span>
```html
<a title="Button Text" class="button_name button" href="#">
<span>Button Text</span>
</a>
```
</div>
</div>
an example using the "Edit" button from the Contact View page :
<div class="code panel" style="border-width: 1px;">
<div class="codeContent panelContent">
<a title="Edit" class="edit button" href="#">
<span>
<div class="icon edit-icon"></div>
Edit
</span>
</a>
</div>
</div>
For example, create an "Edit" button from the Contact View page:
```html
<a title="Edit" class="edit button" href="#">
<span>
<div class="icon edit-icon"></div>
Edit
</span>
</a>
```
# crmDatepicker
## Date-picker
crmDatepicker is a jQuery widget with bindings for Angular and
Quickform.
`crmDatepicker` is a jQuery widget with bindings for AngularJS and Quickform.
Usage:
<div class="code panel" style="border-width: 1px;">
```javascript
$('[name=my_field]').crmDatepicker();
```
<div class="codeContent panelContent">
With no options passed in this will create a date/time combo field that displays
according to locale preferences and saves in ISO format.
$('[name=my_field]').crmDatepicker();
Options can be passed as a plain object. In addition to the [options accepted by the jQuery UI datepicker widget](http://api.jqueryui.com/datepicker/), the following CiviCRM-specific options are available:
</div>
| Option | Type | Description |
| -- | -- | -- |
| `allowClear` | bool | provide a button to clear the contents. This defaults to `true` unless the field has the class or attribute "required" |
| `date` | string\|bool | date display format (e.g. "m/d/y") or `true` to use the locale default, or `false` for no date entry. Default: `true`. |
| `time` | number\|bool | time display format (12 or 24) or `true` to use the locale default, or `false` for no time entry. Default: `true`. |
</div>
jQuery example of a date-only field in a custom display format:
<span style="font-size: 10.0pt;line-height: 13.0pt;">With no options
passed in this will create a date/time combo field that displays
according to locale preferences and saves in ISO format.</span>
<span style="font-size: 10.0pt;line-height: 13.0pt;"> </span>Options can
be passed as a plain object. Available options:
- **allowClear**: (bool) provide a button to clear the contents. This
defaults to *true* unless the field has the class or attribute
"required"
- **date**: (string|bool) date display format (e.g. "m/d/y") or *true*
to use the locale default, or *false* for no date entry.
Default: *true*.
- **time**: (number|bool) time display format (12 or 24) or *true* to
use the locale default, or *false* for no time entry<span>.
Default: </span>*true*<span>.</span>
- <span><span>**minDate**: (date|string|number) either a javascript
date object or a unix timestamp or iso datestring (yyyy-mm-dd).
Default *undefined*.</span></span>
- **maxDate**<span
style="font-size: 10.0pt;line-height: 13.0pt;">: (date|string|number)
either a javascript date object or a unix timestamp or iso
datestring
(yyyy-mm-dd).<span> Default </span>*undefined*<span>.</span></span>
- <span style="font-size: 10.0pt;line-height: 13.0pt;"><span>Any other
parameter accepted by the[jQuery UI datepicker
widget](http://api.jqueryui.com/datepicker/){.external-link}.</span></span>
<span>jQuery example of a date-only field in a custom display
format:</span>
<div class="code panel" style="border-width: 1px;">
<div class="codeContent panelContent">
$('[name=my_field]').crmDatepicker({time: false, date: 'dd-mm-yy'});
</div>
</div>
```javascript
$('[name=my_field]').crmDatepicker({time: false, date: 'dd-mm-yy'});
```
Angular example using the same options with data model binding:
<div class="code panel" style="border-width: 1px;">
<div class="codeHeader panelHeader" style="border-bottom-width: 1px;">
**Angular Binding**
</div>
<div class="codeContent panelContent">
<input crm-ui-datepicker="{time: false, date: 'dd-mm-yy'}" ng-model="myobj.datefield"/>
</div>
</div>
From a php class extending CRM_Core_Form:
<div class="code panel" style="border-width: 1px;">
<div class="codeHeader panelHeader" style="border-bottom-width: 1px;">
```html
<input crm-ui-datepicker="{time: false, date: 'dd-mm-yy'}" ng-model="myobj.datefield"/>
```
**PHP - QuickForm Binding**
</div>
From a php class extending `CRM_Core_Form`:
<div class="codeContent panelContent">
```php
// Use default settings
$this->add('datepicker', 'field_name', ts('Field Label'));
// Use default settings
$this->add('datepicker', 'field_name', ts('Field Label'));
// Make it required, customize datepicker and remove time field
$this->add(
'datepicker',
'field_2',
ts('Field 2'),
array('class' => 'some-css-class'),
TRUE,
array('time' => FALSE, 'date' => 'mm-dd-yy', 'minDate' => '2000-01-01')
);
```
// Make it required, customize datepicker and remove time field
$this->add(
'datepicker',
'field_2',
ts('Field 2'),
array('class' => 'some-css-class'),
TRUE,
array('time' => FALSE, 'date' => 'mm-dd-yy', 'minDate' => '2000-01-01')
);
</div>
</div>
<span>\
</span>
# Icons
## Icons
The primary goal of using icons should be to help the user absorb and
process information more efficiently. Icons can be used throughout the
site whenever it would useful to give users a quick visual cue.
Starting with version 4.7, CiviCRM's primary icon system is [Font
Awesome](http://fortawesome.github.io/Font-Awesome/){.external-link}, an
Starting with version 4.7, CiviCRM's primary icon system is [Font Awesome](http://fontawesome.io/), an
open-source icon font. Font Awesome 4.4 is shipped with CiviCRM 4.7,
and any of the [Font Awesome
icons](http://fortawesome.github.io/Font-Awesome/icons/){.external-link}
can be included with an element with the classes "crm-i" and the
"fa-..." class corresponding to the icon.
<div class="panelMacro">
!!! tip{width="16" height="16"} Use <https://github.com/mattwire/uk.co.mjwconsult.fontawesome> if you want access to these icons in earlier versions of CiviCRM (for example, if you have an extension, that uses them).
</div>
and any of the [Font Awesome icons](http://fontawesome.io/icons//)
can be included with an element with the classes `crm-i` and the
`fa-...` class corresponding to the icon.
!!! tip
Use [this extension](https://github.com/mattwire/uk.co.mjwconsult.fontawesome) if you want access to these icons in earlier versions of CiviCRM (for example, if you have an extension, that uses them).
For example, to insert a [bullhorn
icon](http://fortawesome.github.io/Font-Awesome/icon/bullhorn/){.external-link},
icon](http://fortawesome.github.io/Font-Awesome/icon/bullhorn/),
use the following:
<div class="code panel" style="border-width: 1px;">
```html
<div><i class="crm-i fa-bullhorn"></i>Create new announcement</div>
```
<div class="codeContent panelContent">
!!! note "Why `crm-i`?"
Many websites use Font Awesome, and a site's implementation of the `fa` class might differ from CiviCRM's Font Awesome implementation. The version might be different, or other styling might be associated with the class.
<div><i class="crm-i fa-bullhorn"></i> Create new announcement</div>
To avoid this, CiviCRM uses the `crm-i` class alongside the `fa-...` class for the specific icon.
</div>
</div>
<div class="panelMacro">
+--+
| |
+--+
</div>
## Icon meaning and consistency
### Icon meaning and consistency
it's helpful to use icons consistently–to help new users understand the
purpose of an option and to help experienced users navigate quickly.
Here are some brief descriptions of the ways that various icons are
used:
<div class="table-wrap">
+--------------------------+--------------------------+--------------------------+
| Icon class | Use | Compare with |
+==========================+==========================+==========================+
| fa-trash | delete something that's | fa-times to cancel |
| | already been saved | something that hasn't |
| | | been saved yet |
| | | |
| | | fa-undo to roll back a |
| | | bigger process |
+--------------------------+--------------------------+--------------------------+
| fa-arrows | move something | fa-chevron-left and |
| | (anywhere) | fa-chevron-right to |
| | | advance through a series |
+--------------------------+--------------------------+--------------------------+
| fa-trophy | award something a prize | fa-check to confirm |
| | | something |
+--------------------------+--------------------------+--------------------------+
| fa-random | swap places | |
+--------------------------+--------------------------+--------------------------+
| fa-print | print something | |
+--------------------------+--------------------------+--------------------------+
| fa-clipboard | file onto a case | |
| | | |
| | paste something | |
+--------------------------+--------------------------+--------------------------+
| fa-undo | undo things | fa-chevron-left to move |
| | | backwards in a process |
| | (revert things in | |
| | accounting) | fa-trash to delete |
| | | something |
| | | |
| | | fa-times to remove |
| | | something (that hasn't |
| | | yet been saved) or to |
| | | exit without saving |
+--------------------------+--------------------------+--------------------------+
| fa-info-circle | highlight information | fa-lightbulb-o to |
| | | highlight a tip or |
| | | suggestion |
| | | |
| | | fa-exclamation-triangle |
| | | to highlight a danger |
+--------------------------+--------------------------+--------------------------+
| fa-list-alt | display the details of | fa-television to preview |
| | something | something |
| | | |
| | | fa-expand and |
| | | fa-compress to make |
| | | something full-screen or |
| | | a window |
+--------------------------+--------------------------+--------------------------+
| fa-bars | open a menu of options | fa-chevron right to |
| | | advance to the next |
| | | thing |
| | | |
| | | fa-expand to make |
| | | something full-screen |
+--------------------------+--------------------------+--------------------------+
| fa-search | search for things | fa-list-alt to display |
| | | details |
| | | |
| | | fa-search-plus to zoom |
| | | in |
+--------------------------+--------------------------+--------------------------+
| fa-lightbulb-o | an idea to consider | fa-bolt to execute |
| | | something bold |
| | | |
| | | fa-info-circle to |
| | | provide normative |
| | | information |
| | | |
| | | fa-exclamation-triangle |
| | | to highlight a danger |
+--------------------------+--------------------------+--------------------------+
| fa-pencil | edit a value | fa-wrench to edit |
| | | configuration |
| | | |
| | | fa-floppy-o to save a |
| | | value |
+--------------------------+--------------------------+--------------------------+
| fa-exclamation-triangle | provide a warning | fa-info-circle to give |
| | | information |
| | | |
| | | fa-lightbulb-o to |
| | | highlight a tip or |
| | | suggestion |
+--------------------------+--------------------------+--------------------------+
| fa-expand | make a UI element bigger | |
+--------------------------+--------------------------+--------------------------+
| fa-compress | make a UI element | |
| | smaller | |
| | | |
| | merge two things | |
| | together | |
+--------------------------+--------------------------+--------------------------+
| fa-rocket | embark upon an adventure | fa-chevron-right to |
| | | advance to something |
| | | less exciting and/or |
| | | fraught with danger |
| | | |
| | | fa-check to agree to |
| | | something that is |
| | | already a done deal |
| | | |
| | | fa-flag-checkered to |
| | | finish a long process |
| | | |
| | | fa-space-shuttle if you |
| | | need to access your |
| | | payload with the Canada |
| | | Arm |
+--------------------------+--------------------------+--------------------------+
| fa-plus-circle | add a new item | if you have several of |
| | | these side-by-side, try |
| | | to provide more |
| | | illustrative icons for |
| | | what you're adding |
| | | |
| | | fa-bolt to force a new |
| | | thing |
+--------------------------+--------------------------+--------------------------+
| fa-bolt | execute something | fa-floppy-o to saving |
| | forcefully | something normally |
| | | |
| | | fa-check to agree to |
| | | something innocuous |
| | | |
| | | fa-chevron-right to |
| | | advance to the next step |
| | | |
| | | fa-trash to delete |
| | | something |
| | | |
| | | fa-undo to revert to |
| | | something |
+--------------------------+--------------------------+--------------------------+
| fa-television | preview something | fa-search to search for |
| | | things |
| | | |
| | | fa-list-alt to view the |
| | | details of something |
| | | |
| | | fa-times to close the |
| | | edit dialog and see the |
| | | thing itself |
+--------------------------+--------------------------+--------------------------+
| fa-times | close something without | fa-trash to delete |
| | saving anything | something that has been |
| | | saved already |
| | remove something that | |
| | hasn't yet been saved | fa-check to complete |
| | | something (that has just |
| | | been saved or that is to |
| | | be saved upon clicking |
| | | the icon) |
| | | |
| | | fa-undo to roll |
| | | something back |
| | | |
| | | fa-chevron-left to |
| | | return to the previous |
| | | step |
+--------------------------+--------------------------+--------------------------+
| fa-check | complete something | fa-times to close out |
| | | without doing anything |
| | | |
| | | fa-chevron-right to |
| | | advance to the next step |
| | | |
| | | fa-flag-checkered to |
| | | complete something major |
| | | |
| | | fa-rocket to agree to |
| | | start something big |
| | | |
| | | fa-bolt to execute |
| | | something bold |
+--------------------------+--------------------------+--------------------------+
| fa-chevron-right | advance to the next | fa-check to complete |
| | thing | something |
| | | |
| | | fa-rocket to start an |
| | | epic journey |
+--------------------------+--------------------------+--------------------------+
| fa-chevron-left | go back | fa-times to cancel the |
| | | process |
| | | |
| | | fa-undo to revert what |
| | | was done |
+--------------------------+--------------------------+--------------------------+
| fa-floppy-o | save without advancing | fa-check to save and |
| | | complete |
| | | |
| | | fa-pencil to start |
| | | editing a value |
+--------------------------+--------------------------+--------------------------+
| fa-wrench | modify options | fa-pencil to edit values |
| | | |
| | | fa-bolt to do something |
| | | drastic |
+--------------------------+--------------------------+--------------------------+
| fa-paper-plane | send something | fa-envelope to do |
| | | something else about |
| | | email |
| | | |
| | | fa-check, |
| | | fa-chevron-right, |
| | | fa-bolt, fa-rocket or |
| | | others if you are doing |
| | | an action that does not |
| | | send a message |
| | | immediately |
| | | |
| | | fa-fax to send something |
| | | on curly paper |
+--------------------------+--------------------------+--------------------------+
| fa-envelope | do something about email | fa-paper-plane to |
| | other than actually | actually send an email |
| | sending it | |
| | | fa-pencil to edit a |
| | (use judiciously when | value |
| | within CiviMail, where | |
| | everything is about | |
| | email) | |
+--------------------------+--------------------------+--------------------------+
| fa-flag-checkered | complete a multi-step | fa-trophy to award a |
| | action | prize |
| | | |
| | | fa-check to finish |
| | | something quick |
+--------------------------+--------------------------+--------------------------+
| fa-bell-o | sound alarms | fa-paper-plane to send |
| | | an email notification |
| | | |
| | | fa-exclamation-triangle |
| | | to highlight something |
| | | dangerous |
+--------------------------+--------------------------+--------------------------+
| fa-bell-slash-o | hush alarms | fa-times to cancel |
| | | something |
| | | |
| | | fa-user-secret to cloak |
| | | identity |
+--------------------------+--------------------------+--------------------------+
| fa-clock-o | schedule something | fa-history to roll back |
| | | the clock |
| | | |
| | | fa-calendar to display |
| | | dates |
| | | |
| | | fa-birthday-cake to |
| | | schedule a celebration |
+--------------------------+--------------------------+--------------------------+
</div>
## Special effects
| Class | Meaning within CiviCRM |
| -- | -- |
| `.fa-trash` | delete something that's already been saved |
| `.fa-arrows` | move something (anywhere) |
| `.fa-trophy` | award something a prize |
| `.fa-random` | swap places |
| `.fa-print` | print something |
| `.fa-clipboard` | paste something, or file onto a case |
| `.fa-undo` | undo (or revert) things |
| `.fa-info-circle` | highlight information |
| `.fa-list-alt` | display the details of something |
| `.fa-bars` | open a menu of options |
| `.fa-search` | search for things |
| `.fa-lightbulb-o` | an idea to consider |
| `.fa-pencil` | edit a value |
| `.fa-exclamation-triangle` | provide a warning |
| `.fa-expand` | make a UI element bigger |
| `.fa-compress` | make a UI element smaller, or merge two things together |
| `.fa-rocket` | embark upon an adventure |
| `.fa-plus-circle` | add a new item |
| `.fa-bolt` | execute something forcefully |
| `.fa-television` | preview something |
| `.fa-times` | close something without saving anything, or remove something that hasn't yet been saved |
| `.fa-check` | complete something |
| `.fa-chevron-right` | advance to the next thing |
| `.fa-chevron-left` | go back |
| `.fa-floppy-o` | save without advancing |
| `.fa-wrench` | modify options |
| `.fa-paper-plane` | send something |
| `.fa-envelope` | do something about email other than actually sending it *(use judiciously when within CiviMail, where everything is about email)* |
| `.fa-flag-checkered` | complete a multi-step action |
| `.fa-bell-o` | sound alarms |
| `.fa-bell-slash-o` | hush alarms |
| `.fa-clock-o` | schedule something |
### Special effects
Font Awesome includes a number of icon features, including spinners,
orientation options, and stacking. Just replace the "fa" class [in the
examples](http://fortawesome.github.io/Font-Awesome/examples/){.external-link}
with "crm-i".
------------------------------------------------------------------------
# Older icon system
<div class="panelMacro">
+--+
| |
+--+
</div>
orientation options, and stacking. Just replace the `fa` class [in the
examples](http://fortawesome.github.io/Font-Awesome/examples/)
with `crm-i`.
### Older icon system
!!! failure "Deprecated icons"
Prior to 4.7, icons were included in CiviCRM using the jQuery UI icon set as well as custom-developed icons. Those use sprites, which limit the size and color options for icons. As of 4.7, support for older icons remains in CiviCRM, but new features and customizations should use Font Awesome instead.
To use an existing icon simply find the one you want from the list below
and use the following code (in this example we are using the
"delete-icon"):
<div class="code panel" style="border-width: 1px;">
<div class="codeContent panelContent">
<div class="icon delete-icon"></div>
</div>
</div>
<div class="panelMacro">
!!! tip{width="16" height="16"} CiviCRM uses image sprites ([more info](http://www.alistapart.com/articles/sprites){.external-link}) for its two icon sets.
</div>
### The following **CRM-specific** icons are available:
- Individual-icon
- Group-icon
- Household-icon
<!-- -->
- Individual-subtype-icon
- Household-subtype-icon
- Organization-subtype-icon
<!-- -->
- Organization-icon
- Activity-icon
- Case-icon
- Grant-icon
- Contribution-icon
- Pledge-icon
- Membership-icon
- Participant-icon
- Note-icon
- Relationship-icon
### The following **non CRM-specific** icons are available:
- edit-icon
- delete-icon
- dashboard-icon
- user-record-icon
- inform-icon
- tip-icon
`delete-icon`):
```html
<div class="icon delete-icon"></div>
```
!!! tip
CiviCRM uses image sprites ([more info](http://www.alistapart.com/articles/sprites)) for its two icon sets.
The following **CRM-specific** icons are available:
* `Individual-icon`
* `Group-icon`
* `Household-icon`
* `Individual-subtype-icon`
* `Household-subtype-icon`
* `Organization-subtype-icon`
* `Organization-icon`
* `Activity-icon`
* `Case-icon`
* `Grant-icon`
* `Contribution-icon`
* `Pledge-icon`
* `Membership-icon`
* `Participant-icon`
* `Note-icon`
* `Relationship-icon`
The following **non CRM-specific** icons are available:
* `edit-icon`
* `delete-icon`
* `dashboard-icon`
* `user-record-icon`
* `inform-icon`
* `tip-icon`
Non CRM-specific icons can be altered to use one of 4 possible colors:
- light-icon = #888888
- dark-icon = #222222
- red-icon = #cd0a0a
- blue-icon = #2e83ff
| Class | Resulting color |
| -- | -- |
| `light-icon` | <code style="color: white; background-color:#888888">#888888</code> |
| `dark-icon` | <code style="color: white; background-color:#222222">#222222</code> |
| `red-icon` | <code style="color: white; background-color:#cd0a0a">#cd0a0a</code> |
| `blue-icon` | <code style="color: white; background-color:#2e83ff">#2e83ff</code> |
The default icon color is "light-icon" or #222222. To change the color,
simply add the color class to the icon div - in the example below the
The default icon color is `light-icon`. To change the color,
simply add the color class to the icon `<div>`. In the example below the
delete icon will be red:
<div class="code panel" style="border-width: 1px;">
<div class="codeContent panelContent">
<div class="icon red-icon delete-icon"></div>
</div>
</div>
```html
<div class="icon red-icon delete-icon"></div>
```
Non CRM-specific icons used inside of a button will change to
"dark-icons" when you hover over the button (with the exception of the
delete icon, which turns red)
# In-Place Field Editing
## Background
## In-Place Field Editing
In-place field editing was added to CiviCRM circa v4.1 and is built upon
- [The AJAX API](/confluence/display/CRMDOC/AJAX+Interface)
- The [Jeditable
plugin](http://www.appelsiini.net/projects/jeditable){.external-link}
for jQuery
<div class="panelMacro">
+--+
| |
+--+
</div>
## Wrapper (Entity) Properties
* [The AJAX API](/api/interfaces.md#ajax)
* The [Jeditable plugin](http://www.appelsiini.net/projects/jeditable) for jQuery
<div class="table-wrap">
!!! failure "Jeditable EOL"
The Jeditable plugin is outdated and unmaintained. A suitable replacement will need to be found.
Property Default if Omitted Possible Values As Markup As Data
-------------------- -------------------- --------------------------------------------------------- ---------------------- -----------------------
**Declaration** *required* Wrapper must have class "crm-entity" class="crm-entity" *-*
**Entity Name** *required* Any API entity id="**contact**-123" data-entity="contact"
**Entity ID** *required* Numeric id of existing entity or "new" to add an entity id="contact-**123**" data-id="123"
**Default Action** "setvalue" Any api action - data-action="create"
### Wrapper (Entity) Properties
</div>
| Property | Default if Omitted | Possible Values | As Markup | As Data |
| -- | -- | -- | -- | -- |
| **Declaration** | *required* | Wrapper must have class `.crm-entity` | `class="crm-entity"` | - |
| **Entity Name** | *required* | Any API entity | `id="contact-123"` | `data-entity="contact"` |
| **Entity ID** | *required* | Numeric id of existing entity or "new" to add an entity | `id="contact-123"` | `data-id="123"` |
| **Default Action** | "setvalue" | Any api action | - | `data-action="create"` |
## <span>Item (Field) Properties</span>
<div class="table-wrap">
+----------------+----------------+----------------+----------------+----------------+
| Property | Default if | Possible | As Markup | As Data |
| | Omitted | Values | | |
+================+================+================+================+================+
| **Declaration* | *required* | Item must have | class="crm-edi | *-* |
| * | | class | table" | |
| | | "crm-editable" | | |
+----------------+----------------+----------------+----------------+----------------+
| **Field Name** | *required* | Any field for | class="crmf-fi | data-field="fi |
| | | this entity | eld_name" | eld_name" |
+----------------+----------------+----------------+----------------+----------------+
| **Action** | (entity | Any api action | - | data-action="u |
| | default) | (overrides | | pdate" |
| | | default set at | | |
| | | entity level) | | |
+----------------+----------------+----------------+----------------+----------------+
| **Widget | text | text, | - | data-type="tex |
| Type** | | textarea, | | tarea" |
| | | select, | | |
| | | boolean | | |
+----------------+----------------+----------------+----------------+----------------+
| **Empty | - | A string to | | data-empty-opt |
| Option** | | label the | | ion="{ts}- |
| | | "null" option | | none -{/ts}" |
| | | if the field | | |
| | | is of type | | |
| | | select and the | | |
| | | user should be | | |
| | | allowed to | | |
| | | choose | | |
| | | nothing. | | |
+----------------+----------------+----------------+----------------+----------------+
| **Tooltip** | "Click to | Any text | | data-tooltip=" |
| | edit" | | | {ts}Help |
| | | | | text{/ts}" |
+----------------+----------------+----------------+----------------+----------------+
| **Placeholder* | (standard edit | Any markup | | data-placehold |
| * | icon) | | | er="&lt;span&g |
| | | | | t;Click |
| | | | | to |
| | | | | edit&lt;/span& |
| | | | | gt;" |
+----------------+----------------+----------------+----------------+----------------+
| **Select | (automatic) | Json-encoded | | |
| Options** | | options (Note: | | |
| | | this is rarely | | |
| | | needed as | | |
| | | option lists | | |
| | | are | | |
| | | automatically | | |
| | | fetched from | | |
| | | the api by | | |
| | | crmEditable) | | |
+----------------+----------------+----------------+----------------+----------------+
| **Refresh** | false | Boolean | | data-refresh=" |
| | | | | true" |
+----------------+----------------+----------------+----------------+----------------+
### Item (Field) Properties
</div>
| Property | Default if Omitted | Possible Values | As Markup | As Data |
| -- | -- | -- | -- | -- |
| **Declaration** | *required* | Item must have class `.crm-editable` | `class="crm-editable"` | - |
| **Field Name** | *required* | Any field for this entity | `class="crmf-field_name"` | `data-field="field_name"` |
| **Action** | *(entity default)* | Any api action (overrides default set at entity level) | - | `data-action="update"` |
| **Widget Type** | *text* | text, textarea, select, boolean | - | `data-type="textarea"` |
| **Empty Option** | *-* | A string to label the "null" option if the field is of type select and the user should be allowed to choose nothing. | | `data-empty-option="{ts}- none -{/ts}"` |
| **Tooltip** | *"Click to edit"* | Any text | | `data-tooltip="{ts}Help text{/ts}"` |
| **Placeholder** | *(standard edit icon)* | Any markup | | `data-placeholder="<span>Click to edit</span>"` |
| **Select Options** | *(automatic)* | Json-encoded options (Note: this is rarely needed as option lists are automatically fetched from the api by crmEditable) | | |
| **Refresh** | *false* | Boolean | | `data-refresh="true"` |
## <span>Use With Checkboxes</span>
### Use With Checkboxes
<span>If a field is marked-up as &lt;input type="checkbox"&gt; then the
If a field is marked-up as `<input type="checkbox">` then the
"widget type" property will be ignored and the checkbox will save via
ajax whenever the user clicks it.</span>
## <span>Example Markup</span>
<div class="code panel" style="border-width: 1px;">
<div class="codeHeader panelHeader" style="border-bottom-width: 1px;">
**Simplified Example Markup**
</div>
<div class="codeContent panelContent">
<table>
<tr class="crm-entity" id="contact-123">
<td class="crm-editable crmf-first_name">Fred</td> <!-- textfield (default type) -->
<td class="crm-editable crmf-prefix_id" data-type="select" data-empty-option="{ts}- none -{/ts}">Mr.</td> <!-- select list with empty option (note: options will be fetched automatically by the api) -->
<td class="crm-editable crmf-is_deceased" data-type="boolean">No</td> <!-- yes/no select -->
</tr>
</table>
</div>
</div>
## Initializing the crmEditable Widget
ajax whenever the user clicks it.
### Example Markup
```html
<table>
<tr class="crm-entity" id="contact-123">
<!-- textfield (default type) -->
<td class="crm-editable crmf-first_name">Fred</td>
<!-- select list with empty option -->
<!-- (note: options will be fetched automatically by the api) -->
<td class="crm-editable crmf-prefix_id"
data-type="select"
data-empty-option="{ts}- none -{/ts}">Mr.</td>
<!-- yes/no select -->
<td class="crm-editable crmf-is_deceased" data-type="boolean">
No
</td>
</tr>
</table>
```
### Initializing the crmEditable Widget
As of CiviCRM v4.6 you do not need to do anything to initialize
crmEditable, it is handled automatically on every
......@@ -816,291 +381,168 @@ crmEditable, it is handled automatically on every
event.
In previous versions you would need to manually write out the javascript
<span
style="color: rgb(0,51,0);">`$.('crm-editable').crmEditable();`</span>
or else include the smarty template crmeditable.tpl (which contains that
```javascript
$.('crm-editable').crmEditable();
```
or else include the smarty template `crmeditable.tpl` (which contains that
js snippet). This template if used in 4.6+ will output a deprecation
warning to the console, as it no longer serves any purpose and will be
removed in a future version.
# Notifications and Confirmations
## Notifications and Confirmations
<div class="panel"
style="background-color: #FFFFCE;border-color: #000;border-style: solid;border-width: 1px;">
<div class="panelHeader"
style="border-bottom-width: 1px;border-bottom-style: solid;border-bottom-color: #000;background-color: #F7D6C1;">
### Popup Notifications
**Table of Contents**
Popup notifications are the main way of alerting a message to the user in CiviCRM.
</div>
<div class="panelContent" style="background-color: #FFFFCE;">
<div>
- [Popup
Notifications](#NotificationsandConfirmations-PopupNotifications)
<!-- -->
- [Bindings](#NotificationsandConfirmations-Bindings)
- [Message Types](#NotificationsandConfirmations-MessageTypes)
<!-- -->
- [Confirmations](#NotificationsandConfirmations-Confirmations)
- [Unobtrusive
Notifications](#NotificationsandConfirmations-UnobtrusiveNotifications)
- [Static Messages](#NotificationsandConfirmations-StaticMessages)
</div>
</div>
</div>
## Popup Notifications
Popup notifications are the main way of alerting a message to the user
in CiviCRM.
![](/confluence/download/attachments/73924954/notification-shot.png?version=1&modificationDate=1347315131000&api=v2){.confluence-embedded-image
width="100"}
### Bindings
#### Javascript
#### Javascript: CRM.alert() and $().crmError()
CRM.alert opens a CiviCRM-themed alert.
<div class="code panel" style="border-width: 1px;">
<div class="codeContent panelContent">
CRM.alert(message, title, type, options);
</div>
</div>
$.crmError opens an alert as well as changing the form element to be in
`$.crmError` opens an alert as well as changing the form element to be in
an error state. The alert will be cleared automatically when the input
is changed.
<div class="code panel" style="border-width: 1px;">
<div class="codeContent panelContent">
$('#form_element').crmError(ts('Wrong input'));
</div>
</div>
<div class="panelMacro">
!!! note{width="16" height="16"} CRM.alert() is generally preferred to javascript's built-in alert() function to maintain CiviCRM's consistent UI.
```javascript
$('#form_element').crmError(ts('Wrong input'));
```
`CRM.alert` opens a CiviCRM-themed alert.
</div>
#### PHP: CRM_Core_Session::setStatus()
```javascript
CRM.alert(message, title, type, options);
```
<div class="code panel" style="border-width: 1px;">
!!! note
`CRM.alert()` is generally preferred to javascript's built-in `alert()` function to maintain CiviCRM's consistent UI.
<div class="codeContent panelContent">
#### PHP
CRM_Core_Session::setStatus($message, $title, $type, $options);
```php
CRM_Core_Session::setStatus($message, $title, $type, $options);
```
</div>
</div>
### Message Types
#### Message Types
The "type" parameter affects the css class of the notification. Although
it accepts any value, the 4 options supported by CIviCRM's css icons
it accepts any value, the 4 options supported by CiviCRM's css icons
are:
- *alert* (default)
- *success*
- *info*
- *error*
#### Options
* *alert* (default)
* *success*
* *info*
* *error*
Additional options are passed as an array (object in js):
- **unique**: (default: true) Check if this message was already set
* **unique**: (default: true) Check if this message was already set
before adding
- **expires**: how long to display this message before fadeout (in
ms)\
set to 0 for no expiration\
* **expires**: how long to display this message before fadeout (in
ms) set to 0 for no expiration
defaults to 10 seconds for most messages, 5 if it has a title but no
body, or 0 for errors or messages containing links
## Confirmations
### Confirmations
To open a dialog to display a message and give the user 1 or more
choices:
<div class="code panel" style="border-width: 1px;">
<div class="codeContent panelContent">
CRM.confirm(options)
.on('crmConfirm:yes', function() {
// Do something
})
.on('crmConfirm:no', function() {
// Don't do something
});
</div>
</div>
```javascript
CRM.confirm(options)
.on('crmConfirm:yes', function() {
// Do something
})
.on('crmConfirm:no', function() {
// Don't do something
});
```
The **options** object takes any params accepted by jQuery UI dialog
(e.g. 'title') plus a few others:
- **message**: defaults to "Are you sure you want to continue?
- **url**: load content from the server (overrides 'message' param)
- **options**: associative list of buttons keyed by the name of the
event they will trigger. Defaults to\
{no: "Cancel", yes: "Continue"}.\
You could add another button e.g. {maybe: ts('Not sure yet')} and
when clicked it would trigger a crmConfirm:maybe event.\
Note: in your event handler you can call event.preventDefault() to
* **message**: defaults to "Are you sure you want to continue?
* **url**: load content from the server (overrides 'message' param)
* **options**: associative list of buttons keyed by the name of the
event they will trigger. Defaults to
`{no: "Cancel", yes: "Continue"}`.
You could add another button e.g. `{maybe: ts('Not sure yet')}` and
when clicked it would trigger a crmConfirm:maybe event.
Note: in your event handler you can call `event.preventDefault()` to
stop the dialog from closing.
!!! note
`CRM.confirm()` is generally preferred to javascript's built-in `window.confirm()` function to maintain CiviCRM's consistent UI.
Also, unlike `window.confirm()`, `CRM.confirm` is non-blocking and relies on callbacks rather than interrupting script execution.
<div class="panelMacro">
!!! note{width="16" height="16"} CRM.confirm() is generally preferred to javascript's built-in confirm() function to maintain CiviCRM's consistent UI.
NOTE: Unlike window.confirm, CRM.confirm is non-blocking and relies on callbacks rather than interrupting script execution.
</div>
## Unobtrusive Notifications
### Unobtrusive Notifications
Added in CIviCRM 4.5, these small messages tell the user the status of
an api call, form submission, or other asynchronous operation without
getting in the way.
<div class="code panel" style="border-width: 1px;">
<div class="codeHeader panelHeader" style="border-bottom-width: 1px;">
**Basic Async Usage**
</div>
<div class="codeContent panelContent">
CRM.status(messages, request);
</div>
```javascript
CRM.status(messages, request);
```
</div>
- Messages is an object containing start, success, and error keys.
* Messages is an object containing start, success, and error keys.
Each message can be a string, function returning a string, or null
to suppress output.
- Message defaults are {start: "Saving...", success: "Saved", error:
* Message defaults are {start: "Saving...", success: "Saved", error:
(no message, displays an alert warning the user that their
information was not saved)}
- Request is a jQuery deferred object. If you don't pass one in it
* Request is a jQuery deferred object. If you don't pass one in it
will be created for you and returned
<div class="code panel" style="border-width: 1px;">
<div class="codeHeader panelHeader" style="border-bottom-width: 1px;">
**Simple Non-Async Usage**
</div>
<div class="codeContent panelContent">
CRM.status(message, type);
</div>
</div>
```javascript
CRM.status(message, type);
```
- For simple usage without async operations you can pass in a string
* For simple usage without async operations you can pass in a string
as the first param. 2nd param is optional string 'error' if this is
not a success msg.
<div class="code panel" style="border-width: 1px;">
<div class="codeHeader panelHeader" style="border-bottom-width: 1px;">
**Chaining With CRM.api3**
</div>
<div class="codeContent panelContent">
```javascript
CRM.api3(entity, action, params, messages);
```
CRM.api3(entity, action, params, messages);
</div>
</div>
- Unfortunately jQuery deferred objects are not extendable so we can't
* Unfortunately jQuery deferred objects are not extendable so we can't
chain CRM.status to an api call. Instead CRM.api3 provides an
optional 4th param messages which will be passed into CRM.status.
Pass **true** instead of an object to accept the default messages
(defaults are set based on action, e.g. "Saving" for create or
"Loading" for get).
## Static Messages
### Static Messages
To display a static alert box in the document (this was standard in
CiviCRM 4.2 and below):
<div class="code panel" style="border-width: 1px;">
<div class="codeHeader panelHeader" style="border-bottom-width: 1px;">
**From Smarty**
</div>
<div class="codeContent panelContent">
{capture assign=infoMessage}{ts}This is just a yellow box with a message.{/ts}{/capture}
{include file="CRM/common/info.tpl" infoType="no-popup"}
</div>
</div>
<div class="code panel" style="border-width: 1px;">
<div class="codeHeader panelHeader" style="border-bottom-width: 1px;">
```smarty
{capture assign=infoMessage}{ts}This is just a yellow box with a message.{/ts}{/capture}
{include file="CRM/common/info.tpl" infoType="no-popup"}
```
**From PHP**
</div>
<div class="codeContent panelContent">
```php
CRM_Core_Session::setStatus(ts(This is just a yellow box with a message.), '', 'no-popup');
```
CRM_Core_Session::setStatus(ts(This is just a yellow box with a message.), '', 'no-popup');
</div>
</div>
# Section elements
## Section elements
This element is to be used in the case that you have a number of
elements that can be broken down into small groups of information. A
......@@ -1109,94 +551,69 @@ good example of it's use is in the contribution page template.
Here each logical grouping of related form elements are wrapped by a
"section" div:
<div class="code panel" style="border-width: 1px;">
<div class="codeContent panelContent">
<div class="section amount_other-section">
<div class="label">
<label for="amount_other">Other Amount</label>
</div>
<div class="content">
$ <input type="text" class="form-text" id="amount_other" name="amount_other" onfocus="useAmountOther();" maxlength="10" size="10"/>
</div>
<div class="clear"/>
</div>
</div>
</div>
the abstraction of this for elements **with** a label is as follows:
<div class="code panel" style="border-width: 1px;">
<div class="codeContent panelContent">
<div class="section unique_section_name-section">
<div class="label">
<label>Section Label</label>
</div>
<div class="content">
Section Content
</div>
<div class="clear"/>
</div>
</div>
</div>
which is generated using the following .tpl syntax:
<div class="code panel" style="border-width: 1px;">
<div class="codeContent panelContent">
<div class="section {$form.element_name.name}-section">
<div class="label">{$form.element_name.label}</div>
<div class="content">{$form.element_name.html}</div>
<div class="clear"></div>
</div>
</div>
</div>
the abstraction of this for elements **without** a label is as follows
```html
<div class="section amount_other-section">
<div class="label">
<label for="amount_other">Other Amount</label>
</div>
<div class="content">
$
<input
type="text"
class="form-text"
id="amount_other"
name="amount_other"
onfocus="useAmountOther();"
maxlength="10"
size="10"/>
</div>
<div class="clear"/>
</div>
```
The abstraction of this for elements **with** a label is as follows:
```html
<div class="section unique_section_name-section">
<div class="label">
<label>Section Label</label>
</div>
<div class="content">
Section Content
</div>
<div class="clear"/>
</div>
```
You can generate the above by using the following `.tpl` syntax:
```html
<div class="section {$form.element_name.name}-section">
<div class="label">{$form.element_name.label}</div>
<div class="content">{$form.element_name.html}</div>
<div class="clear"></div>
</div>
```
The abstraction of this for elements *without* a label is as follows
(this will keep the content in line with content from other section's
that **are** using labels):
<div class="code panel" style="border-width: 1px;">
<div class="codeContent panelContent">
<div class="section unique_section_name-section">
<div class="content">
Section Content
</div>
<div class="clear"/>
</div>
</div>
that *are* using labels):
```html
<div class="section unique_section_name-section">
<div class="content">Section Content</div>
<div class="clear"/>
</div>
```
the abstraction of this for elements **without** a label is as follows
The abstraction of this for elements *without* a label is as follows
(this allow the content to take up the space normally reserved for
labels):
<div class="code panel" style="border-width: 1px;">
<div class="codeContent panelContent">
<div class="section unique_section_name-section nolabel-section">
<div class="content">
Section Content
</div>
<div class="clear"/>
</div>
```html
<div class="section unique_section_name-section nolabel-section">
<div class="content">Section Content</div>
<div class="clear"/>
</div>
```
</div>
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