Skip to content

AngularJS: Quick Start

Let's create a new CiviCRM extension with an AngularJS page. It will present a small "About Me" screen.

Create a CiviCRM extension

First, we'll need a skeletal CiviCRM extension:

$ civix generate:module org.example.aboutme
Initalize module org.example.aboutme
Write org.example.aboutme/info.xml
Write org.example.aboutme/aboutme.php
Write org.example.aboutme/aboutme.civix.php
Write org.example.aboutme/LICENSE.txt

Create an Angular module

Of course, AngularJS also has its own module system -- any Angular routes, directives, or services need to live within an Angular module. Let's create one.

$ cd org.example.aboutme
$ civix generate:angular-module
Initialize Angular module "aboutme"
Write ang/aboutme.ang.php
Write ang/aboutme.js
Write ang/aboutme.css

Tip: Angular module names

By default, civix assumes that your Angular module name matches your extension name. In this case, both are named aboutme. However, this is not required -- the option --am can specify a different name. This can be useful if you want to organize your code into multiple modules.

Note: ang/ folder

By convention, AngularJS source code is stored in the ang/ folder, and each item is named after its module. The convention is discussed in more detail in AngularJS: File Names

The first file, ang/aboutme.ang.php, provides metadata for the PHP-based file-loader, e.g.

return array(
  'requires' => array('ngRoute', 'crmUi', 'crmUtil'),
  'js' => array('ang/aboutme.js', 'ang/aboutme/*.js', 'ang/aboutme/*/*.js'),
  'css' => array('ang/aboutme.css'),
  'partials' => array('ang/aboutme'),
  'settings' => array(),
);

The second file, ang/aboutme.js, provides metadata for the JS-based Angular runtime, e.g.

  angular.module('aboutme', [
    'ngRoute', 'crmUi', 'crmUtil'
  ]);

Tip: angular.module() and CRM.angRequires()

The list of dependencies is declared once in PHP and once in JS. To remove this duplication, call CRM.angRequires(...), as in:

angular.module('aboutme', CRM.angRequires('aboutme'));

Add an Angular-based page

Now let's add a new Angular-based page. This page will require a route with a controller and an HTML template. The command civix generate:angular-page will create each of these:

$ civix generate:angular-page EditCtrl about/me
Initialize Angular page "AboutmeEditCtrl" (civicrm/a/#/about/me)
Write ang/aboutme/EditCtrl.js
Write ang/aboutme/EditCtrl.html

If you inspect the code, you'll find a basic AngularJS app which uses $routeProvider, angular.module(...).controller(...), and so on.

The generated code will display a small "About Me" screen with the current user's first-name and last-name.

Tip: Flush caches or enable debug mode

By default, CiviCRM aggregates AngularJS files and caches them. You can flush this cache manually (cv flush). However, it may be easier to disable some of the aggregation/caching features by enabling debug mode.

Open the page

Finally, we'd like to take a look at this page in the web-browser.

By default, CiviCRM combines all Angular modules into one page, civicrm/a. The URL of this page depends on your system configuration. Here are a few examples:

# Example: Lookup the URL on Drupal 7
$ cv url 'civicrm/a/#/about/me'
"http://dmaster.l/civicrm/a/#/about/me"

# Example: Lookup the URL on WordPress
$ cv url 'civicrm/a/#/about/me'
"http://wpmaster.l/wp-admin/admin.php?page=CiviCRM&q=civicrm/a/#/about/me"

Tip: Open the browser from the command-line

If you're developing locally on a Linux/OSX workstation, pass the option --open to automatically open the page in a web browser.