aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/guide.contribute.ngdoc27
-rw-r--r--docs/guide.css.ngdoc46
-rw-r--r--docs/guide.downloading.ngdoc35
-rw-r--r--docs/guide.expression.ngdoc207
-rw-r--r--docs/guide.ngdoc1
-rw-r--r--docs/guide.testing.ngdoc8
-rw-r--r--docs/spec/ngdocSpec.js17
-rw-r--r--docs/src/ngdoc.js12
-rw-r--r--docs/src/templates/doc_widgets.js1
-rw-r--r--docs/src/templates/docs.js5
10 files changed, 349 insertions, 10 deletions
diff --git a/docs/guide.contribute.ngdoc b/docs/guide.contribute.ngdoc
new file mode 100644
index 00000000..9e50e661
--- /dev/null
+++ b/docs/guide.contribute.ngdoc
@@ -0,0 +1,27 @@
+@workInProgress
+@ngdoc overview
+@name Developer Guide: Contributing
+@description
+
+# Open Source
+Angular is an open source project licensed under the
+{@link http://github.com/angular/angular.js/blob/master/LICENSE MIT license}. We welcome any
+contributions from the community, but in order to make the contribution process manageable, we ask
+you to follow the following guidelines:
+
+# Source Code
+* Discuss any major changes on our {@link http://groups.google.com/group/angular mailing list}.
+ For small changes and bugfixes, just go ahead and craft your patch and submit it.
+* Use coding style described
+ {@link http://google-styleguide.googlecode.com/svn/trunk/javascriptguide.xml here}.
+* To submit any changes, we ask you to use {@link http://github.com}
+ * Create a github {@link https://github.com/signup/free account}
+ * Clone the {@link http://github.com/angular/angular.js main angular repository}
+ * Create a new branch off of the master (`git branch my-fix-branch`)
+ * Switch to the branch (`git checkout my-fix-branch`), make your changes and commit (`git commit -a`)
+ * For any new features or regressions we require a test(s) to be submitted with the change
+ * Run js lint (`rake lint`) and fix any warnings or errors
+ * Push your branch to github (`git push origin my-fix-branch`)
+ * Send a pull request via github into `angular:master`
+ * Once the patch is reviewed and merged, you can delete your branch (`git push origin :my-fix-branch; git checkout master; git branch -D my-fix-branch`)
+ * TADA!
diff --git a/docs/guide.css.ngdoc b/docs/guide.css.ngdoc
new file mode 100644
index 00000000..6e028f30
--- /dev/null
+++ b/docs/guide.css.ngdoc
@@ -0,0 +1,46 @@
+@workInProgress
+@ngdoc overview
+@name Developer Guide: CSS
+@description
+
+# CSS
+angular includes built-in CSS classes, which in turn have predefined CSS styles.
+
+# Built-in CSS classes
+
+## `ng-exception`
+
+**Usage:** angular applies this class to a DOM element if that element contains an Expression that
+threw an exception when evaluated.
+
+**Styling:** The built-in styling of the ng-exception class displays an error message surrounded
+by a solid red border, for example:
+
+ > <div class="ng-exception">Error message</div>
+
+
+
+You can try to evaluate malformed expressions in {@link angualr.expression expression} to see the
+`ng-exception` class' styling.
+
+## `ng-validation-error`
+
+**Usage:** angular applies this class to an input widget element if that element's input does not
+pass validation. Note that you set the validation criteria on the input widget element using the
+Ng:validate or Ng:required directives.
+
+**Styling:** The built-in styling of the ng-validation-error class turns the border of the input
+box red and includes a hovering UI element that includes more details of the validation error. You
+can see an example in {@link angular.widget.@ng:validate ng:validate example}.
+
+## How to override the styles for built-in classes
+
+To override the styles for these built-in classes, you can do any of the following:
+
+Download the source code, edit angular.css, and host the source on your own server.
+Create a local css file, overriding any styles that you'd like, and link to it from your HTML file
+as you normally would:
+
+<pre>
+<link href="yourfile.css" rel="stylesheet" type="text/css">
+</pre>
diff --git a/docs/guide.downloading.ngdoc b/docs/guide.downloading.ngdoc
new file mode 100644
index 00000000..9f0f2194
--- /dev/null
+++ b/docs/guide.downloading.ngdoc
@@ -0,0 +1,35 @@
+@workInProgress
+@ngdoc overview
+@name Developer Guide: Downloading
+@description
+
+# Downloading
+Follow these steps to download, compile, and host angular.js on your own server:
+
+## Step 0
+
+If you don't already have Rake (Ruby Make) installed, download and install it from
+http://rake.rubyforge.org/.
+
+## Step 1
+
+Download the angular source code from GitHub: http://github.com/angular/angular.js.
+
+## Step 2
+
+The source code should include a Rakefile. Compile the source by typing rake compile.
+
+## Step 3
+
+Host the files on your server. Look through your source tree and make sure that the css and js
+directories are parallel (i.e. share a common root node).
+
+In the js directory you should see these different versions of the angular bootstrap code:
+
+* **angular-?.?.?.js** - this file is unobfuscated, uncompressed, and human-readable. Note that
+ despite the name of the file, there is no additional functionality built in to help you debug
+ your application; it has the prefix debug because you can read the source code.
+* **angular-?.?.?.min.js** - this is a compressed and obfuscated version of `angular-?.?.?.js`.
+ You might want to use this version if you want to load a smaller but functionally equivalent
+ version of the code in your application. Note: this minified version was created using the
+ Closure Compiler.
diff --git a/docs/guide.expression.ngdoc b/docs/guide.expression.ngdoc
new file mode 100644
index 00000000..421dd9c7
--- /dev/null
+++ b/docs/guide.expression.ngdoc
@@ -0,0 +1,207 @@
+@workInProgress
+@ngdoc overview
+@name Developer Guide: Expression
+@description
+
+# Expressions
+Expressions are the bindings that you write in HTML and embed in templates in order to create
+views in angular. They are not equivalent to JavaScript expressions.
+
+For example, these are all valid expressions in angular:
+
+* `1+2={{1+2}}`
+* `3*10|currency`
+* `Hello {{name}}!`
+* `Hello {{'World'}}!`
+
+
+# angular expressions vs. JS expressions
+It might be tempting to think of angular view expressions as JavaScript expressions, but that is
+not entirely correct. angular does not use a simple JavaScript eval of the expression text. You
+can think of angular expressions as JavaScript expressions with these differences:
+
+ * **Attribute Evaluation:** evaluation of all attributes are against the current scope, not to
+ the global window as in JavaScript.
+ * **Forgiving:** expression evaluation is forgiving to undefined and null, unlike in JavaScript.
+ * **No Control Flow Statements:** you cannot do the following from an angular expression:
+ conditionals, loops, or throw.
+ * **Type Augmentation:** the scope expression evaluator augments built-in types.
+ * **Filters:** you can add filters to an expression, for example to convert raw data into a
+ human-readable format.
+ * **The $:** angular reserves this prefix to differentiate its API names from others.
+
+If you want to run arbitrary JavaScript code, make it a controller method and call that. If you
+want to eval an angular expression from JavaScript, use the Scope:$eval() method.
+
+## Example
+<doc:example>
+ <doc:source>
+ 1+2={{1+2}}
+ </doc:source>
+ <doc:scenario>
+ it('should calculate expression in binding', function(){
+ expect(binding('1+2')).toEqual('3');
+ });
+ </doc:scenario>
+</doc:example>
+
+You can try evaluating different expressions here:
+
+<doc:example>
+ <doc:source>
+ <div ng:init="exprs=[]" class="expressions">
+ Expression:
+ <input type='text' name="expr" value="3*10|currency" size="80"/>
+ <button ng:click="exprs.$add(expr)">Evaluate</button>
+ <ul>
+ <li ng:repeat="expr in exprs">
+ [ <a href="" ng:click="exprs.$remove(expr)">X</a> ]
+ <tt>{{expr}}</tt> => <span ng:bind="$parent.$eval(expr)"></span>
+ </li>
+ </ul>
+ </div>
+ </doc:source>
+ <doc:scenario>
+ it('should allow user expression testing', function(){
+ element('.expressions :button').click();
+ var li = using('.expressions ul').repeater('li');
+ expect(li.count()).toBe(1);
+ expect(li.row(0)).toEqual(["3*10|currency", "$30.00"]);
+ });
+ </doc:scenario>
+</doc:example>
+
+# Attribute Evaluation
+
+Evaluation of all attributes are against the current scope. Unlike JavaScript, where names
+default to global window properties, angular expressions have to use $window to refer to the
+global object. E.g. if you want to call alert(), which is defined on window, an expression must
+use $window.alert(). This is done intentionally to prevent accidental access to the global state
+(a common source of subtle bugs).
+
+<doc:example>
+ <doc:source>
+ <div class="example2" ng:init="$window = $service('$window')">
+ Name: <input name="name" type="text" value="World"/>
+ <button ng:click="($window.mockWindow || $window).alert('Hello ' + name)">Greet</button>
+ </div>
+ </doc:source>
+ <doc:scenario>
+ it('should calculate expression in binding', function(){
+ var alertText;
+ this.addFutureAction('set mock', function($window, $document, done) {
+ $window.mockWindow = {
+ alert: function(text){ alertText = text; }
+ };
+ done();
+ });
+ element(':button:contains(Greet)').click();
+ expect(this.addFuture('alert text', function(done) {
+ done(null, alertText);
+ })).toBe('Hello World');
+ });
+ </doc:scenario>
+</doc:example>
+
+## Forgiving
+
+Expression evaluation is forgiving to undefined and null. In JavaScript, evaluating a.b.c throws
+an exception if a is not an object. While this makes sense for a general purpose language, the
+expression evaluations are primarily used for data binding, which often look like this: `{{a.b.c}}`.
+It makes more sense to show nothing than to throw an exception if a is undefined (e.g. perhaps
+we are waiting for the server response, and it will become defined soon). If expression
+evaluation wasn't forgiving we'd have to write bindings that clutter the code, for example:
+`{{((a||{}).b||{}).c}}`
+
+Similarly, invoking a function a.b.c() on undefined or null simply returns undefined.
+
+Assignments work the same way in reverse. a.b.c = 10 creates the intermediary objects even if a
+is undefined.
+
+
+## No Control Flow Statements
+
+You cannot write a control flow statement in an expression. The reason behind this is core to
+the angular philosophy that application logic should be in controllers, not in the view. If you
+need a conditional (including ternary operators), loop, or to throw from a view expression,
+delegate to a JavaScript method instead.
+
+
+## Type Augmentation
+
+Built-in types have methods like [].push(), but the richness of these methods is limited. Consider
+the example below, which allows you to do a simple search over a canned set of contacts. The
+example would be much more complicated if we did not have the Array:$filter(). There is no
+built-in method on Array called $filter and angular doesn't add it to Array.prototype because that
+could collide with other JavaScript frameworks.
+
+For this reason the scope expression evaluator augments the built-in types to make them act like
+they have extra methods. The actual method for $filter() is angular.Array.filter(). You can call
+it from JavaScript.
+
+Extensions: You can further extend the expression vocabulary by adding new methods to
+`angular.Array` or `angular.String`, etc.
+
+<doc:example>
+ <doc:source>
+ <div ng:init="friends = [
+ {name:'John', phone:'555-1212'},
+ {name:'Mary', phone:'555-9876'},
+ {name:'Mike', phone:'555-4321'},
+ {name:'Adam', phone:'555-5678'},
+ {name:'Julie', phone:'555-8765'}]"></div>
+ Search: <input name="searchText"/>
+ <table class="example3">
+ <tr><th>Name</th><th>Phone</th><tr>
+ <tr ng:repeat="friend in friends.$filter(searchText)">
+ <td>{{friend.name}}</td>
+ <td>{{friend.phone}}</td>
+ </tr>
+ </table>
+ </doc:source>
+ <doc:scenario>
+ it('should filter the list', function(){
+ var tr = using('table.example3').repeater('tr.ng-attr-widget');
+ expect(tr.count()).toBe(5);
+ input('searchText').enter('a');
+ expect(tr.count()).toBe(2);
+
+ });
+ </doc:scenario>
+</doc:example>
+
+## Filters
+
+When presenting data to the user, you might need to convert the data from its raw format to a
+user-friendly format. For example, you might have a data object that needs to be formatted
+according to the locale before displaying it to the user. You can pass expressions through a
+chain of filters like this:
+
+<pre>
+name | uppercase
+</pre>
+
+The expression evaluator simply passes the value of name to angular.filter.uppercase.
+
+Chain filters using this syntax:
+
+<pre>
+value | filter1 | filter2
+</pre>
+
+You can also pass colon-delimited arguments to filters, for example, to display the number 123
+with 2 decimal points: 123 | number:2
+
+# The $
+
+You might be wondering, what is the significance of the $ prefix? It is simply a prefix that
+angular chooses to differentiate its API names from others. If angular didn't use $, then
+evaluating a.length() would return undefined because neither a nor angular define such a property.
+Consider that in a future version of angular we might choose to add a length method, in which case
+the behavior of the expression would change. Worse yet, you the developer could create a length
+property and then we would have collision. This problem exists because angular augments existing
+objects with additional behavior. By prefixing its additions with $ we are reserving our namespace
+so that angular developers and developers who use angular can develop in harmony without
+collisions.
+
+
diff --git a/docs/guide.ngdoc b/docs/guide.ngdoc
index b1ac143e..fd5d05df 100644
--- a/docs/guide.ngdoc
+++ b/docs/guide.ngdoc
@@ -34,3 +34,4 @@
* service:$browser(mock)
* {@link guide.downloading Downloading} - How to download, compile, and host the angular
environment on your own server.
+* {@link guide.contribute Contributing} - How to contribute to angular project.
diff --git a/docs/guide.testing.ngdoc b/docs/guide.testing.ngdoc
new file mode 100644
index 00000000..bb3a1441
--- /dev/null
+++ b/docs/guide.testing.ngdoc
@@ -0,0 +1,8 @@
+@workInProgress
+@ngdoc overview
+@name Developer Guide: Testing
+@description
+
+# Testing Angular Applications
+
+to be written...
diff --git a/docs/spec/ngdocSpec.js b/docs/spec/ngdocSpec.js
index 9d84ee7e..d912bf3a 100644
--- a/docs/spec/ngdocSpec.js
+++ b/docs/spec/ngdocSpec.js
@@ -319,6 +319,7 @@ describe('ngdoc', function(){
var doc = new Doc("@description " +
'foo {@link angular.foo}\n\n da {@link angular.foo bar foo bar } \n\n' +
'dad{@link angular.foo}\n\n' +
+ 'external{@link http://angularjs.org}\n\n' +
'{@link angular.directive.ng:foo ng:foo}');
doc.parse();
expect(doc.description).
@@ -329,6 +330,8 @@ describe('ngdoc', function(){
toContain('dad<a href="#!angular.foo"><code>angular.foo</code></a>');
expect(doc.description).
toContain('<a href="#!angular.directive.ng:foo"><code>ng:foo</code></a>');
+ expect(doc.description).
+ toContain('<a href="http://angularjs.org">http://angularjs.org</a>');
});
});
@@ -357,12 +360,16 @@ describe('ngdoc', function(){
});
it('should render description in related method', function(){
- var doc = new Doc();
+ var doc = new Doc('').parse();
doc.ngdoc = 'service';
- doc.methods = [new Doc('@ngdoc method\n@exampleDescription MDesc\n@example MExmp').parse()];
- doc.properties = [new Doc('@ngdoc property\n@exampleDescription PDesc\n@example PExmp').parse()];
- expect(doc.html()).toContain('<p>MDesc</p><div ng:non-bindable=""><pre class="brush: js; html-script: true;">MExmp</pre>');
- expect(doc.html()).toContain('<p>PDesc</p><div ng:non-bindable=""><pre class="brush: js; html-script: true;">PExmp</pre>');
+ doc.methods = [
+ new Doc('@ngdoc method\n@exampleDescription MDesc\n@example MExmp').parse()];
+ doc.properties = [
+ new Doc('@ngdoc property\n@exampleDescription PDesc\n@example PExmp').parse()];
+ expect(doc.html()).toContain('<p>MDesc</p><div ng:non-bindable="">' +
+ '<pre class="brush: js; html-script: true;">MExmp</pre>');
+ expect(doc.html()).toContain('<p>PDesc</p><div ng:non-bindable="">' +
+ '<pre class="brush: js; html-script: true;">PExmp</pre>');
});
});
diff --git a/docs/src/ngdoc.js b/docs/src/ngdoc.js
index e01d9ccf..a3a037cd 100644
--- a/docs/src/ngdoc.js
+++ b/docs/src/ngdoc.js
@@ -114,7 +114,7 @@ Doc.prototype = {
description: markdown(text.replace(match[0], match[2]))
};
} else if(atName == 'description') {
- text.replace(/<doc:scenario>([\s\S]*)<\/doc:scenario>/mi,
+ text.replace(/<doc:scenario>([\s\S]*?)<\/doc:scenario>/gmi,
function(_, scenario){
self.scenarios.push(scenario);
});
@@ -154,7 +154,7 @@ Doc.prototype = {
throw new Error("Don't know how to format @ngdoc: " + self.ngdoc);
}).call(self, dom);
- dom.example(self.exampleDescription, self.example, self.scenario);
+ dom.example(self.exampleDescription, self.example, self.scenarios[0]);
});
return dom.toString();
@@ -438,6 +438,8 @@ Doc.prototype = {
//////////////////////////////////////////////////////////
function markdown (text) {
+ var IS_URL = /^(https?:\/\/|ftps?:\/\/|mailto:)/;
+ var IS_ANGULAR = /^angular\./;
if (!text) return text;
var parts = text.split(/(<pre>[\s\S]*?<\/pre>|<doc:example>[\s\S]*?<\/doc:example>)/),
match;
@@ -462,10 +464,10 @@ function markdown (text) {
text = text.replace(/<angular\/>/gm, '<tt>&lt;angular/&gt;</tt>');
text = text.replace(/{@link ([^\s}]+)((\s|\n)+(.+?))?\s*}/gm,
function(_all, url, _2, _3, title){
- return '<a href="#!' + url + '">'
- + (url.match(/^angular\./) ? '<code>' : '')
+ return '<a href="' + (url.match(IS_URL) ? '' : '#!') + url + '">'
+ + (url.match(IS_ANGULAR) ? '<code>' : '')
+ (title || url)
- + (url.match(/^angular\./) ? '</code>' : '')
+ + (url.match(IS_ANGULAR) ? '</code>' : '')
+ '</a>';
});
text = new Showdown.converter().makeHtml(text);
diff --git a/docs/src/templates/doc_widgets.js b/docs/src/templates/doc_widgets.js
index 39b9ff48..bfa8e5d0 100644
--- a/docs/src/templates/doc_widgets.js
+++ b/docs/src/templates/doc_widgets.js
@@ -56,6 +56,7 @@
});
function indent(text) {
+ if (!text) return text;
var lines = text.split(/\n/);
var lineNo = [];
// remove any leading blank lines
diff --git a/docs/src/templates/docs.js b/docs/src/templates/docs.js
index aaea8c9d..ab96a699 100644
--- a/docs/src/templates/docs.js
+++ b/docs/src/templates/docs.js
@@ -40,4 +40,9 @@ function DocsController($location, $browser, $window) {
}
+// prevent compilation of code
+angular.widget('code', function(element){
+ element.attr('ng:non-bindable', 'true');
+});
+
SyntaxHighlighter['defaults'].toolbar = false;
generated by cgit v1.2.3 (git 2.25.1) at 2025-11-01 22:23:09 +0000