ang-folder.md

The ang folder is used in civicrm-core and civix-based extensions to define AngularJS modules.

Functional Perspective

The folder is generally based on hook_civicrm_angularModules. Each module is mapped to a list of JS/HTML/CSS files, e.g.

  $angularModules['myBigAngularModule'] = array(
    'ext' => 'org.example.mymod',
    'js' => array('ang/myBigangularModule/*.js'),
    'css' => array('ang/myBigangularModule/*.css'),
    'partials' => array('ang/myBigangularModule'),
  );

As long as you list the JS/CSS/HTML-partials in the declaration, it can work.

This leaves a lot of room to organize the files differently -- e.g. many small files or large aggregated files. However, to provide more predictability, most of the code in civicrm-core or generated by civix will follow some naming convention.

Small Module Convention

This convention is based on the idea that "the Angular module does one small thing".

• ang/{mymodule}.ang.php - The data required by hook_civicrm_angularModules.
• ang/{mymodule}.js - All Javascript for the module
• ang/{mymodule}.css - All CSS for the module (if applicable)

Large Module Convention

This convention is based on the idea that "the Angular module is composed of many loosely coupled elements" -- the directives, controllers, and services. Each of these elements may have different aspects (JS/HTML/CSS) which should be named identically.

The civix code-generator should comply with this convention, but civicrm-core code may not follow it religiously.

• Module
  • ang/{mymodule}.ang.php - The data required by hook_civicrm_angularModules.
  • ang/{mymodule}.js - General metadata for the module.
  • ang/{mymodule}.css - General/transcendent CSS that applies throughout the module.
• Directives
  • ang/{mymodule}/{FooBar}.js - The declaration and logic for a directive named mymoduleFooBar or <div mymodule-foo-bar>.
  • ang/{mymodule}/{FooBar}.html - The main/default template for the directive (if applicable).
  • ang/{mymodule}/{FooBar}/{Extra}.html - If you have extra templates loaded via ng-include (or conditional/alternative templates), then put them in a subdir.
  • ang/{mymodule}/{FooBar}.css - Any CSS specifically intended for mymoduleFooBar (if applicable).
• Controllers (These follow the same convention as directives, but they have the suffix Ctrl.)
  • ang/{mymodule}/{FooBar}Ctrl.js - The declaration and logic for a controller named MymoduleFooBarCtrl.
  • ang/{mymodule}/{FooBar}Ctrl.html - The main/default template for the controller (if applicable).
  • ang/{mymodule}/{FooBar}Ctrl/{Extra}.html - If you have extra templates loaded via ng-include (or conditional/alternative templates), then put them in a subdir.
  • ang/{mymodule}/{FooBar}Ctrl.css - Any CSS specifically intended for MymoduleFooBarCtrl (if applicable).
• Services
  • ang/{mymodule}/{FooBar}.js - The declaration and logic for a service named mymoduleFooBar.

Proposed Amendment

• Put documentation and examples for each directive or controller in a *.md file, adjacent to the *.js file. The format is handy for reading/writing/code-snippets, and it won't bloat the final *.js output.