AngularJS is a client-side framework for development of rich web applications. The core CiviCRM application uses AngularJS for several administrative screens, and extensions increasingly use AngularJS for "leaps" that add or replace major parts of the application.
This documentation aims to explain how AngularJS works within a CiviCRM context.
- CiviCRM use AngularJS 1.x which has documentation at docs.angularjs.org
- In version 2.x (and onwards) the framework is just called "Angular" and is a significantly different framework from 1.x. The Angular website is angular.io, which you should steer clear of while learning AngularJS.
To determine the specific version of AngularJS used within your site:
- Go to the default Angular base page for your site at
- Open a browser console
angular.versionwithin the console
CiviCRM is an extensible PHP application (similar to Drupal, Joomla, or WordPress). In this culture, the common expectation is that an administrator installs the main application. To customize it, they download, evaluate, and configure a set of business-oriented modules. The administrator's workflow is dominated by web-based config screens and CLI commands.
The CiviCRM-AngularJS integration must balance the expectations of these two cultures. The balance works as follows:
- Build/Activation: The process of building or activating modules
should meet administrators' expectations. It should be managed by the
PHP application. (This means that you won't see
gruntorchestrating the final build -- because PHP logic fills that role.)
- Backend Code uses Civi API (PHP): The general structure of web-services should meet the backend developers' expectations. These are implemented in PHP (typically with CiviCRM APIv3).
The first interaction comes when CiviCRM generates the initial HTML page:
- CiviCRM listens for requests to the path
civicrm/a. (It does this in a way which is compatible with multiple CMSs -- Drupal, Joomla, WordPress, etc.)
- CiviCRM builds the list of CSS/JS/JSON resources in lines 3-5. (It does this in a way which allows extensions to add new CSS/JS/JSON. See also: Resource Reference.)
- CiviCRM ensures that the page includes the site-wide elements, such as lines 8 and 10. (It does this in a way which is compatible with multiple CMSs.)
Once the page is loaded, it works just like any AngularJS 1.x application.
It uses concepts like
ng-app, "module", "directive", "service", "component", and
Read more about AngularJS 1.x
A good resource for understanding AngularJS concepts is the official AngularJS tutorial.
Read more about CiviCRM API
A good resource for understanding CiviCRM API concepts is the APIv3: Intro.
In the remainder of this document, we'll try to avoid in-depth discussion about the internals of AngularJS 1.x or APIv3. You should be able to follow the discussion if you have a beginner-level understanding of both.