-
Andie Hunt authoredAndie Hunt authored
User Interface Reference
Accordions
CiviCRM uses accordions throughout its UI to minimize the visual weight of the page (hiding less used pieces of content).
There are two types of accordions in use in CiviCRM:
- The more commonly used accordion widget which hides content already in the rendered page
- 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="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:
-
.crm-container .open .crm-accordion-header
- applied whencrm-accordion-body
is visible -
.crm-container .collapsed .crm-accordion-header
- applied whencrm-accordion-body
is hidden -
.crm-accordion-header:hover
- css pseudo-class
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):
{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}" /> {/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.
If you need to offer two opposing functions, such as Edit and Save, consider using two separate buttons instead of one dual-purpose button that changes state.
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.
-
Create a button with an icon:
<a title="Button Text" class="button_name button" href="#"> <span> <div class="icon icon_name-icon"></div> Button Text </span> </a>
-
Create a button without an icon:
<a title="Button Text" class="button_name button" href="#"> <span>Button Text</span> </a>
For example, create an "Edit" button from the Contact View page:
<a title="Edit" class="edit button" href="#">
<span>
<div class="icon edit-icon"></div>
Edit
</span>
</a>
Date-picker
crmDatepicker
is a jQuery widget with bindings for AngularJS and Quickform.
Usage:
$('[name=my_field]').crmDatepicker();
With no options passed in this will create a date/time combo field that displays according to locale preferences and saves in ISO format.
Options can be passed as a plain object. In addition to the options accepted by the jQuery UI datepicker widget, the following CiviCRM-specific options are available:
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 . |
jQuery example of a date-only field in a custom display format:
$('[name=my_field]').crmDatepicker({time: false, date: 'dd-mm-yy'});
Angular example using the same options with data model binding:
<input crm-ui-datepicker="{time: false, date: 'dd-mm-yy'}" ng-model="myobj.datefield"/>
From a php class extending CRM_Core_Form
:
// 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')
);
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, an
open-source icon font. Font Awesome 4.4 is shipped with CiviCRM 4.7,
and any of the Font Awesome icons
can be included with an element with the classes crm-i
and the
fa-...
class corresponding to the icon.
!!! tip Use this extension 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, use the following:
<div><i class="crm-i fa-bullhorn"></i>Create new announcement</div>
!!! 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.
To avoid this, CiviCRM uses the `crm-i` class alongside the `fa-...` class for the specific icon.
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:
Class | Meaning within CiviCRM | Compare with |
---|---|---|
.fa-arrows |
move something (anywhere) |
.fa-chevron-left and .fa-chevron-right to advance through a series |
.fa-bars |
open a menu of options |
.fa-chevron-right to advance to the next thing.fa-expand to make something full-screen |
.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-bolt |
execute something forcefully |
.fa-floppy-o to save 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-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 thing |
.fa-check to complete 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-clipboard |
paste something, or file onto a case | |
.fa-clock-o |
schedule something |
.fa-history to roll back the clock.fa-calendar to display dates.fa-birthday-cake to schedule a celebration |
.fa-compress |
make a UI element smaller, or merge two things together | |
.fa-envelope |
do something about email other than actually sending it (use judiciously when within CiviMail, where everything is about email) |
.fa-paper-plane to actually send an email.fa-pencil to edit 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-flag-checkered |
complete a multi-step action |
.fa-trophy to award a prize.fa-check to finish something quick |
.fa-floppy-o |
save without advancing |
.fa-check to save and complete.fa-pencil to start editing a value |
.fa-info-circle |
highlight information |
.fa-lightbulb-o to highlight a tip or suggestion.fa-exclamation-triangle to highlight a danger |
.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-list-alt |
display the details of something |
.fa-television to preview something.fa-expand and .fa-compress to make something full-screen or a window |
.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-pencil |
edit a value |
.fa-wrench to edit configuration.fa-floppy-o to save a value |
.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-print |
print something | |
.fa-random |
swap places | |
.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-search |
search for things |
.fa-list-alt to display details.fa-search-plus to zoom in |
.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 saving anything, or remove something that hasn't yet been saved |
.fa-trash to delete something that has been saved already.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-trash |
delete something that's already been saved |
.fa-times to cancel something that hasn't been saved yet.fa-undo to roll back a bigger process |
.fa-trophy |
award something a prize |
.fa-check to confirm something |
.fa-undo |
undo (or revert) 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-wrench |
modify options |
.fa-pencil to edit values.fa-bolt to do something drastic |
Special effects
Font Awesome includes a number of icon features, including spinners,
orientation options, and stacking. Just replace the fa
class in the
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="icon delete-icon"></div>
!!! tip CiviCRM uses image sprites (more info) 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:
Class | Resulting color |
---|---|
light-icon |
#888888 |
dark-icon |
#222222 |
red-icon |
#cd0a0a |
blue-icon |
#2e83ff |
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="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
In-place field editing was added to CiviCRM circa v4.1 and is built upon
- The AJAX API
- The Jeditable plugin for jQuery
!!! failure "Jeditable EOL" The Jeditable plugin is outdated and unmaintained. A suitable replacement will need to be found.
Wrapper (Entity) Properties
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" |
Item (Field) Properties
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" |
|
Params | JSON-encoded parameters to add to the api call when saving updates | data-params='{"key":"value"}' |
Use With Checkboxes
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.
Example Markup
<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 crmLoad event.
In previous versions you would need to manually write out the 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
Popup Notifications
Popup notifications are the main way of alerting a message to the user in CiviCRM.
Javascript
$.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.
$('#form_element').crmError(ts('Wrong input'));
CRM.alert
opens a CiviCRM-themed alert.
CRM.alert(message, title, type, options);
!!! note
CRM.alert()
is generally preferred to javascript's built-in alert()
function to maintain CiviCRM's consistent UI.
PHP
CRM_Core_Session::setStatus($message, $title, $type, $options);
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 are: