introducing 'example' inline tag
This commit is contained in:
Jay Traband
parent
d6940e8c93
commit
9922372447
|
|
@ -74,6 +74,7 @@ module.exports = new Package('angular.io', [basePackage])
|
|||
|
||||
.config(function(templateEngine, getInjectables) {
|
||||
templateEngine.filters = templateEngine.filters.concat(getInjectables([require('./rendering/trimBlankLines')]));
|
||||
templateEngine.filters = templateEngine.filters.concat(getInjectables([require('./rendering/indentNonMixin')]));
|
||||
});
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,49 @@
|
|||
module.exports = function(encodeCodeBlock) {
|
||||
var MIXIN_PATTERN = /\S*\+\S*\(.*/;
|
||||
return {
|
||||
name: 'indentNonMixin',
|
||||
process: function (str, width, indentfirst) {
|
||||
str = normalize(str, '');
|
||||
|
||||
if (str === '') return '';
|
||||
|
||||
width = width || 4;
|
||||
var res = '';
|
||||
var lines = str.split('\n');
|
||||
var sp = repeat(' ', width);
|
||||
var spMixin = repeat(' ', width - 2);
|
||||
|
||||
for (var i = 0; i < lines.length; i++) {
|
||||
if (i === 0 && !indentfirst) {
|
||||
res += lines[i] + '\n';
|
||||
}
|
||||
else {
|
||||
// indent lines that match mixin pattern by 2 less.
|
||||
if (lines[i].indexOf('{@example') != -1) {
|
||||
res += spMixin + lines[i] + '\n';
|
||||
} else {
|
||||
res += sp + lines[i] + '\n';
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return res;
|
||||
}
|
||||
};
|
||||
|
||||
function normalize(value, defaultValue) {
|
||||
if(value === null || value === undefined || value === false) {
|
||||
return defaultValue;
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
function repeat(char_, n) {
|
||||
var str = '';
|
||||
for(var i=0; i<n; i++) {
|
||||
str += char_;
|
||||
}
|
||||
return str;
|
||||
};
|
||||
|
||||
};
|
||||
|
|
@ -8,7 +8,7 @@ p.location-badge.
|
|||
defined in {$ githubViewLink(doc) $}
|
||||
|
||||
:markdown
|
||||
{$ doc.description | indent(2, true) | trimBlankLines $}
|
||||
{$ doc.description | indentNonMixin(2, true) | trimBlankLines $}
|
||||
|
||||
{%- if doc.decorators %}
|
||||
.l-main-section
|
||||
|
|
@ -37,7 +37,7 @@ p.location-badge.
|
|||
{$ doc.constructorDoc.name $}{$ paramList(doc.constructorDoc.parameters) | indent(8, false) | trim $}
|
||||
{% endif %}
|
||||
:markdown
|
||||
{$ doc.constructorDoc.description | indent(6, true) | replace('## Example', '') | replace('# Example', '') | trimBlankLines $}
|
||||
{$ doc.constructorDoc.description | indentNonMixin(6, true) | replace('## Example', '') | replace('# Example', '') | trimBlankLines $}
|
||||
|
||||
|
||||
{% endif -%}
|
||||
|
|
@ -52,7 +52,7 @@ p.location-badge.
|
|||
{$ member.name $}{$ paramList(member.parameters) | indent(8, false) | trim $}{$ returnType(doc.returnType) $}
|
||||
{% endif %}
|
||||
:markdown
|
||||
{$ member.description | indent(6, true) | replace('## Example', '') | replace('# Example', '') | trimBlankLines $}
|
||||
{$ member.description | indentNonMixin(6, true) | replace('## Example', '') | replace('# Example', '') | trimBlankLines $}
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -17,6 +17,6 @@
|
|||
defined in {$ githubViewLink(doc) $}
|
||||
|
||||
:markdown
|
||||
{$ doc.description | indent(4, true) | trimBlankLines $}
|
||||
{$ doc.description | indentNonMixin(4, true) | trimBlankLines $}
|
||||
|
||||
{% endblock %}
|
||||
|
|
@ -8,5 +8,5 @@
|
|||
defined in {$ githubViewLink(doc) $}
|
||||
|
||||
:markdown
|
||||
{$ doc.description | indent(4, true) | trimBlankLines $}
|
||||
{$ doc.description | indentNonMixin(4, true) | trimBlankLines $}
|
||||
{% endblock %}
|
||||
|
|
|
|||
|
|
@ -3,10 +3,12 @@ var Package = require('dgeni').Package;
|
|||
module.exports = new Package('links', [])
|
||||
|
||||
.factory(require('./inline-tag-defs/link'))
|
||||
.factory(require('./inline-tag-defs/example'))
|
||||
.factory(require('dgeni-packages/ngdoc/services/getAliases'))
|
||||
.factory(require('dgeni-packages/ngdoc/services/getDocFromAlias'))
|
||||
.factory(require('./services/getLinkInfo'))
|
||||
|
||||
.config(function(inlineTagProcessor, linkInlineTagDef) {
|
||||
.config(function(inlineTagProcessor, linkInlineTagDef, exampleInlineTagDef) {
|
||||
inlineTagProcessor.inlineTagDefinitions.push(linkInlineTagDef);
|
||||
inlineTagProcessor.inlineTagDefinitions.push(exampleInlineTagDef);
|
||||
});
|
||||
|
|
|
|||
|
|
@ -0,0 +1,33 @@
|
|||
var INLINE_EXAMPLE = /(\S+)\s*(\S*)\s*(title=(?:".*?"|'.*?'))?\s*(stylePattern=(?:".*?"|'.*?'))?/
|
||||
|
||||
/**
|
||||
* @dgService exampleInlineTagDef
|
||||
* @description
|
||||
* Process inline example tags (of the form {@example some/uri region title='some title' stylePattern='{some style pattern}' }), replacing them with HTML anchors
|
||||
* @kind function
|
||||
* @param {Object} url The url to match
|
||||
* @param {Function} docs error message
|
||||
* @return {String} The html link information
|
||||
*
|
||||
* @property {boolean} relativeLinks Whether we expect the links to be relative to the originating doc
|
||||
*/
|
||||
module.exports = function exampleInlineTagDef(getLinkInfo, createDocMessage, log) {
|
||||
return {
|
||||
name: 'example',
|
||||
description: 'Process inline example tags (of the form {@example some/uri Some Title}), replacing them with HTML anchors',
|
||||
handler: function(doc, tagName, tagDescription) {
|
||||
|
||||
// Parse out the uri and title
|
||||
return tagDescription.replace(INLINE_EXAMPLE, function(match, uri, region, attr1, attr2) {
|
||||
|
||||
//var linkInfo = getLinkInfo(uri, title, doc);
|
||||
//
|
||||
//if ( !linkInfo.valid ) {
|
||||
// log.warn(createDocMessage(linkInfo.error, doc));
|
||||
//}
|
||||
|
||||
return "+makeExample('styleguide', 'js/index.html', 'index.html')";
|
||||
});
|
||||
}
|
||||
};
|
||||
};
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
doctype
|
||||
html(lang="en" ng-app="angularIOApp")
|
||||
html(lang="en" ng-app="angularIOApp" itemscope itemtype="http://schema.org/Framework")
|
||||
head
|
||||
!= partial("../_includes/_head-include")
|
||||
|
||||
|
|
@ -11,7 +11,7 @@ html(lang="en" ng-app="angularIOApp")
|
|||
|
||||
|
||||
if current.path[3] == 'api'
|
||||
article(class="l-content-small grid-fluid docs-content" ng-non-bindable)
|
||||
article(class="l-content-small grid-fluid docs-content")
|
||||
!= yield
|
||||
|
||||
else
|
||||
|
|
|
|||
|
|
@ -1,120 +0,0 @@
|
|||
include ../../../../_includes/_util-fns
|
||||
|
||||
.l-main-section
|
||||
:markdown
|
||||
## Install Angular2
|
||||
There are four steps to create any Angular app:
|
||||
|
||||
1. Create an entry point HTML file where users will start
|
||||
1. Load the Angular library at the top of the file
|
||||
1. Make a root component for your application
|
||||
1. Bootstrap Angular
|
||||
|
||||
You can edit and test out your apps by serving local files with a web server. Follow the steps in the <a href="../quickstart.html">quickstart</a> to get Typescript setup.
|
||||
|
||||
When you're serving local files, edit and save them and start a web server that serves files in that directory. If you have Python installed, you can run a basic HTTP server from the root of your code directory with:
|
||||
|
||||
pre.prettyprint.lang-bash
|
||||
code python -m SimpleHTTPServer 8000
|
||||
|
||||
.callout.is-helpful
|
||||
header Typescript vs ES5
|
||||
:markdown
|
||||
Although we work through the examples in TypeScript, you can also use
|
||||
regular ES5. Click the ES5 link in any code box to see the ES5 JavaScript
|
||||
version. Note that in ES5, you'd want to name your files `.js` rather than
|
||||
`.ts`.
|
||||
|
||||
.l-main-section
|
||||
:markdown
|
||||
## Create an entry point
|
||||
Create an `index.html` file and add the Angular library tags and a `main.ts` file where
|
||||
you'll build your first component.
|
||||
|
||||
In the `<body>`, add an element called `<my-app>` that will be the root of your
|
||||
application.
|
||||
|
||||
The TypeScript setup includes System.js, a third-party open-source library that adds ES6 module loading functionality to browsers. This step isn't needed for the ES5 version.
|
||||
|
||||
+makeTabs('gettingstarted', 'ts/index.html,js/index.html', 'TypeScript, JavaScript')
|
||||
|
||||
.callout.is-helpful
|
||||
header Don't use code.angularjs.org in a live app
|
||||
:markdown
|
||||
This example serves the Angular library from <a href="http://code.angularjs.org">code.angularjs.org</a>. This is
|
||||
fine for examples, but you'd want to serve it yourself or use a CDN for real deployment.
|
||||
|
||||
.l-main-section
|
||||
:markdown
|
||||
## Set up the starting component
|
||||
|
||||
In `main.ts`, create a class called `AppComponent`, configure it to bind to the
|
||||
`<my-app>` element in `index.html`, and call Angular's `bootstrap()` to kick
|
||||
it all off like this:
|
||||
|
||||
+makeTabs("gettingstarted", "ts/main.ts, js/main.js", "TypeScript, JavaScript")
|
||||
|
||||
.callout.is-helpful
|
||||
header Annotations vs Decorators
|
||||
:markdown
|
||||
If you are transpiling using a tool that translates the `@` symbols to
|
||||
annotations (for example Traceur), you will need to import the annotation versions of
|
||||
Component and View. That can be easily achieved using
|
||||
`import {ComponentAnnotation as Component, ViewAnnotation as View}`.
|
||||
|
||||
.l-main-section
|
||||
:markdown
|
||||
## Run it!
|
||||
|
||||
Open `index.html` through your web server and you should see:
|
||||
|
||||
figure.image-display
|
||||
img(src='/resources/images/examples/setup-example1.png' alt="Example of Todo App")
|
||||
|
||||
.l-main-section
|
||||
:markdown
|
||||
## Explanations
|
||||
|
||||
This basic Angular app contains the structure for any app you'll build.
|
||||
|
||||
.l-sub-section
|
||||
:markdown
|
||||
### It's all a tree
|
||||
|
||||
You can think of Angular apps as a tree of components. This root component we've been talking about acts as the top
|
||||
level container for the rest of your application. You've named this one `AppComponent`, but there's
|
||||
nothing special about the name and you can use whatever makes sense to you.
|
||||
|
||||
The root component's job is to give a location in the `index.html` file where your application will
|
||||
render through its element, in this case `<my-app>`. There is also nothing special about this
|
||||
element name; you can pick it as you like.
|
||||
|
||||
The root component loads the initial template for the application that will load other components to perform
|
||||
whatever functions your application needs - menu bars, views, forms, etc. We'll walk through examples of all of
|
||||
these in the following pages.
|
||||
|
||||
.l-sub-section
|
||||
:markdown
|
||||
### @Component and @View annotations
|
||||
|
||||
A component annotation describes details about the component. An annotation can be identified by its at-sign (`@`).
|
||||
|
||||
The `@Component` annotation defines the HTML tag for the component by specifying the component's CSS selector.
|
||||
|
||||
The `@View` annotation defines the HTML that represents the component. The component you wrote uses an inline template, but you can also have an external template. To use an external template, specify a <code>templateUrl</code> property and give it the path to the HTML file.
|
||||
|
||||
.l-sub-section
|
||||
:markdown
|
||||
### import vs. window.angular
|
||||
|
||||
The main difference between the ES5 and TypeScript versions is the loading of modules.
|
||||
|
||||
**TypeScript**<br/>
|
||||
TypeScript supports ES6 module loading syntax. ES6 modules allow for modular loading of JavaScript code. Using ES6 modules you can cherry-pick only what you need for your app.
|
||||
|
||||
**Javascript**<br/>
|
||||
In ES5 the script file creates an angular property on the window of the browser. This property contains every piece of Angular core, whether you need it or not.
|
||||
|
||||
+makeTabs('gettingstarted', 'ts/main-import.ts', 'TypeScript')
|
||||
|
||||
+makeExample('gettingstarted/js', 'main-bootstrap.js', 'JavaScript')
|
||||
Loading…
Reference in New Issue