└── README.md /README.md: -------------------------------------------------------------------------------- 1 | # Specification for reusable AngularJS components 2 | 3 | _**Attention**: This document is a **WIP**! Since we want to collect as many opinions as possible, feel free to fork and send a Pull Request. 4 | We hope that once this specification is called final, developers of angular components will do things the same way, which will allow the Angular Team to provide better tooling._ 5 | 6 | ### Preface 7 | This specification should help you as a developer, as well as a consumer of Angular components, to find, use and develop reusable Angular components. 8 | Angular components are distributed as Bower packages. 9 | See [bower.io](http://bower.io) for more information. 10 | 11 | It has two parts: 12 | 13 | 1. [The **consumer** perspective](#angularjs-components-consumer) 14 | 2. [The **creator/forker** perspective](#angularjs-components-creator) 15 | 16 | The consumer perspective covers all topics on finding and using Angular components, whereas the creator or forker part gives an in-depth description of how to create, structure and publish an Angular component, as well as which naming conventions to follow for the component itself and the resulting bower package. 17 | 18 | ### Dependencies 19 | 20 | This specification also expects that needed tools are already installed and ready to use. 21 | Which means the following commands should be used to install the needed tools on a local machine: 22 | 23 | **Node Package Manager** 24 | 25 | Visit [https://nodejs.org/download/](https://nodejs.org/download) 26 | 27 | **Bower Package Manager** 28 | ```shell 29 | $ npm install -g bower 30 | ``` 31 | 32 | ### Definitions in this specification 33 | 34 | This specification contains expressions like _components_, _packages_ and _modules_. 35 | These are the definitions: 36 | 37 | #### Component 38 | _Component_ is a Bower concept. 39 | A _component_ is a repo which contains some files for client-side use in a web browser. 40 | This may include, but is not limited to, JavaScript, CSS, HTML, and images. 41 | A Bower _component_ has a component.json (or bower.json) file that describes the _component_ and its dependencies. 42 | 43 | #### Package 44 | _Package_ is a Bower concept. 45 | For the time being, one can think of the terms _package_ and _component_ as being interchangeable in the context of Bower. 46 | In general, _package_ is the thing that you can download, and contains a _component_, which is a group of one or more assets. 47 | Saying one can think of them as interchangeable for now, is because there's a one-to-one correspondence of package to component. 48 | 49 | #### Module 50 | When the word _module_ appears, this specification means an AngularJS module. 51 | An AngularJS module may have multiple directives, services, or filters. 52 | For _components_, each _module_ typically has its own file. 53 | Bower _components_ typically contain just one AngularJS _module_, though in theory there can be more. 54 | 55 | ## AngularJS Components Consumer 56 | 57 | _This part of the **Reusable AngularJS components** specification is highly inspired by @btford 's [blog post](http://briantford.com/blog/angular-bower.html)._ 58 | 59 | ### Table Of Contents 60 | 61 | * [Naming Conventions](#naming-conventions) 62 | * [Registered Angular components](#registered-angular-components) 63 | * [Searching and Finding](#searching-and-finding) 64 | * [Search for packages](#search-for-packages) 65 | * [Finding packages with keywords](#finding-packages-with-keywords) 66 | * [Installing packages](#installing-packages) 67 | * [Installing unregistered packages](#installing-unregistered-packages) 68 | 69 | ### Naming Conventions 70 | 71 | #### Registered Angular components 72 | To make searching and filtering for Angular components with Bower as easy as possible, the name under which Angular components get registered should match the following pattern. 73 | 74 | ``` 75 | angular-[optional-namespace]-[thing-name]-[optional-thing-type] 76 | ``` 77 | 78 | Name should be prefixed with `angular-`. 79 | 80 | ##### optional-namespace 81 | Can be used to group similar components such as 82 | ``` 83 | angular-phonegap-ready 84 | angular-phonegap-geolocation 85 | ``` 86 | 87 | ##### thing-name 88 | This is the actual module name. 89 | It should match the functionality of the module. 90 | E.g. the `geolocation` in `angular-phonegap-geolocation`. 91 | Or the `translate` in `angular-translate`. 92 | 93 | ##### optional-thing-type 94 | Could be `filter`, `directive` or `service`. 95 | This is for clarification if `[thing-name]` isn't enough. 96 | 97 | 98 | ### Searching and Finding 99 | 100 | #### Search for packages 101 | Since registered Angular components follow a **naming convention**, finding them can be achieved by simply searching for all registered Bower packages which have an _angular_ in their registry name. 102 | 103 | ```shell 104 | $ bower search angular 105 | ``` 106 | Should return a list of registered bower packages with an _angular_ in their name. 107 | 108 | #### Finding packages with keywords 109 | Bower doesn't currently support a search with keywords. 110 | Filtering packages by keyboard can be done by using `bower search` in combination with the `grep` command. 111 | So the following command searches for Angular packages with the keyword "phonegap". 112 | 113 | ```shell 114 | $ bower search angular | grep "phonegap" 115 | ``` 116 | 117 | ### Installing packages 118 | Once the right package is found, one can install it using the Bower `install` command. 119 | E.g. installing AngularJS itself as a package would look like this: 120 | 121 | ```shell 122 | $ bower install angular 123 | ``` 124 | 125 | This will download the specified package into the folder which is configured as components folder via `.bowerrc`. 126 | 127 | #### Installing unregistered packages 128 | It is possible that there's an AngularJS component on GitHub, which is not registered as bower component. 129 | This could have several reasons: 130 | 131 | * The author doesn't plan to publish it as a Bower component 132 | * The name the author wants to register it is already been taken 133 | * The package is actually registered but the endpoint is broken (which unfortunately happens often, and there's currently no way to take care of that as a package maintainer. 134 | See [https://github.com/twitter/bower/issues/120](https://github.com/twitter/bower/issues/120) 135 | 136 | In that cases one can install the package by specifying the GitHub user and the repository. 137 | This works for **every** GitHub repository. 138 | 139 | ```shell 140 | $ bower install / 141 | ``` 142 | 143 | ## TL;DR 144 | 145 | Your modules should be publicly distributed with this convention ('Publicly' as in bower names, repository names, website names, etc): 146 | ``` 147 | angular-[optional-namespace]-[thing-name]-[optional-thing-type] 148 | ``` 149 | Example: 150 | ```javascript 151 | angular-phonegap-ready 152 | angular-superman-directives 153 | ``` 154 | 155 | Your angular modules in the source should have this convention: 156 | ``` 157 | [author-name].[thing-name].[thing-type] 158 | ``` 159 | Example: 160 | ```javascript 161 | angular.module('btford.phonegap-ready', []); 162 | angular.module('doctor-evil.superman-directives.kryptonite', []) 163 | ``` 164 | 165 | 166 | ## Bad Practices 167 | 168 | Please don't do these things. 169 | 170 | ### Registering controllers, services, filters, etc. on the `ng` module 171 | 172 | ```javascript 173 | // this is bad 174 | angular.module('ng').filter('tel', function (){}); 175 | ``` 176 | 177 | Instead create your own module and add it as a dependency to your application's top-level module. 178 | 179 | **Why:** this is needlessly frail. See [this issue](https://github.com/angular/angular.js/issues/7709#issuecomment-46300969). 180 | 181 | 182 | ## References 183 | 184 | * [Kick-off discussion](https://gist.github.com/PascalPrecht/5411171) 185 | * [Brian's blog post](http://briantford.com/blog/angular-bower.html) 186 | --------------------------------------------------------------------------------