iSharkFly-Docs/angular-docs-cn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix for makeExample styling without linenumbers losing scrollbar + default handling of makeExamples with only one line

Browse Source 
closes #427
This commit is contained in:
Jay Traband 2015-12-01 00:02:48 -08:00 committed by Ward Bell
parent 83fab41666
commit 46ac6bdaa9
4 changed files with 368 additions and 371 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
public/_includes/_util-fns.jade
View File

@ -2,8 +2,9 @@
mixin makeExample(filePath, region, title, stylePatterns) mixin makeExample(filePath, region, title, stylePatterns)
- var language = attributes.language || getExtn(filePath); - var language = attributes.language || getExtn(filePath);
- var format = attributes.format || "linenums";
- var frag = getFrag(filePath, region); - var frag = getFrag(filePath, region);
- var defaultFormat = frag.split('\n').length > 2 ? "linenums" : "";
- var format = attributes.format || defaultFormat;
if (title) if (title)
.example-title #{title} .example-title #{title}
code-example(language="#{language}" format="#{format}") code-example(language="#{language}" format="#{format}")

721
public/docs/_includes/styleguide/_code-examples.jade
View File

@ -9,484 +9,479 @@ include ../../../_includes/_util-fns
p Below are some examples of how you can add/customize code examples in a page. p Below are some examples of how you can add/customize code examples in a page.
.showcase-content .showcase-content
.l-sub-section :marked
### Including a code example from the `_examples` folder
:marked One of the design goals for this documention was that any code samples that appear within the documentation be 'testable'.
### Including a code example from the `_examples` folder In practice this means that a set of standalone testable examples exist somewhere in the same repository as the rest
of the documentation. These examples will each typically consist of a collection of html, javascript and css files.
One of the design goals for this documention was that any code samples that appear within the documentation be 'testable'. Clearly there also needs to be some mechanism for including fragments of these files into the jade/harp generated
In practice this means that a set of standalone testable examples exist somewhere in the same repository as the rest html. By convention all of the 'testable' examples within this repository should be created within the `docs/_examples` folder.
of the documentation. These examples will each typically consist of a collection of html, javascript and css files.
Clearly there also needs to be some mechanism for including fragments of these files into the jade/harp generated To include an example from somewhere in the `doc/_examples` folder you can use the `makeExample` mixin.
html. By convention all of the 'testable' examples within this repository should be created within the `docs/_examples` folder. This mixin along with the `makeTabs` mixin both require that the 'included' file be marked
up with special comment markers. This markup will be described a bit later.
To include an example from somewhere in the `doc/_examples` folder you can use the `makeExample` mixin. In addition there are several custom gulp tasks that must be run before any of the edits described below will actually appear
This mixin along with the `makeTabs` mixin both require that the 'included' file be marked in the generated documentation. These gulp tasks are documented elsewhere.
up with special comment markers. This markup will be described a bit later.
In addition there are several custom gulp tasks that must be run before any of the edits described below will actually appear In order to use the `makeExample` or `makeTabs` mixins each page that references the mixins must include the '_utilFns.jade'
in the generated documentation. These gulp tasks are documented elsewhere. file on the current page. This is usually accomplished simply by adding a path to this file at the top of any
page that needs either of these mixins.
In order to use the `makeExample` or `makeTabs` mixins each page that references the mixins must include the '_utilFns.jade' code-example(language="js").
file on the current page. This is usually accomplished simply by adding a path to this file at the top of any include ../../../../_includes/_util-fns
page that needs either of these mixins.
code-example(language="js"). :marked
include ../../../../_includes/_util-fns The syntax for the `makeExample` mixin is:
:marked #### +makeExample(filePath, region, title, stylePattern)
The syntax for the `makeExample` mixin is: - *filePath:* path to the example file under the '_examples' folder
- *region:* (optional or null) region from the example file to display
- *title:* (optional or null) title displayed above the included text.
- *stylePattern:* (optional or null) allows additional styling via regular expression ( described later).
#### +makeExample(filePath, region, title, stylePattern) #### Example:
- *filePath:* path to the example file under the '_examples' folder
- *region:* (optional or null) region from the example file to display
- *title:* (optional or null) title displayed above the included text.
- *stylePattern:* (optional or null) allows additional styling via regular expression ( described later).
#### Example:
code-example(format="linenums" language="js").
+makeExample('styleguide/js/index.html', null, 'index.html')
:marked
This will read the *_examples/styleguide/js/index.html* file and include it
with the heading 'index.html'. Note that the file will be properly escaped and
color coded according to the extension on the file ( html in this case).
code-example(format="linenums" language="js").
+makeExample('styleguide/js/index.html', null, 'index.html') +makeExample('styleguide/js/index.html', null, 'index.html')
:marked :marked
The second parameter with a value of 'null' will be described later in this document. This will read the *_examples/styleguide/js/index.html* file and include it
with the heading 'index.html'. Note that the file will be properly escaped and
color coded according to the extension on the file ( html in this case).
There is a similar `makeTabs` mixin that provides the same service but for multiple examples +makeExample('styleguide/js/index.html', null, 'index.html')
within a tabbed interface.
#### +makeTabs(filePaths, regions, titles, stylePatterns) :marked
- *filePaths:* a comma delimited string of filePaths to example files under the '_examples' folder The second parameter with a value of 'null' will be described later in this document.
- *regions:* (optional or null) region from the example file to display
- *titles:* (optional or null) a comma delimited string of titles corresponding to each of the filePaths above.
- *stylePatterns:* (optional or null) allows additional styling via regular expression( described later).
#### Example: There is a similar `makeTabs` mixin that provides the same service but for multiple examples
within a tabbed interface.
code-example(format="linenums" language="js"). #### +makeTabs(filePaths, regions, titles, stylePatterns)
+makeTabs('styleguide/js/index.html, styleguide/js/spec.js', null, 'index.html,unit test') - *filePaths:* a comma delimited string of filePaths to example files under the '_examples' folder
- *regions:* (optional or null) region from the example file to display
- *titles:* (optional or null) a comma delimited string of titles corresponding to each of the filePaths above.
- *stylePatterns:* (optional or null) allows additional styling via regular expression( described later).
:marked #### Example:
This will create two tabs, each with its own title and appropriately color coded.
code-example(format="linenums" language="js").
+makeTabs('styleguide/js/index.html, styleguide/js/spec.js', null, 'index.html,unit test') +makeTabs('styleguide/js/index.html, styleguide/js/spec.js', null, 'index.html,unit test')
.l-sub-section :marked
:marked This will create two tabs, each with its own title and appropriately color coded.
### Marking up an example file for use by the `makeExample` and `makeTabs` mixins
At a minimum, marking up an example file simply consists of adding a single comment line to the top of the file +makeTabs('styleguide/js/index.html, styleguide/js/spec.js', null, 'index.html,unit test')
containing the string `#docregion`. Following this a second string that is the 'name' of the region is also allowed
but not required. A file may have any number of `#docregion` comments with the only requirement being that the names
of each region within a single file be unique. This also means that there can only be one *blank* docregion.
#### Example of a simple #docregion
code-example(format="linenums" language="js"). :marked
// #docregion ### Marking up an example file for use by the `makeExample` and `makeTabs` mixins
describe("Jasmine sample test", function() {
it("1+1 should be 2", function() { At a minimum, marking up an example file simply consists of adding a single comment line to the top of the file
var result = 1 + 1; containing the string `#docregion`. Following this a second string that is the 'name' of the region is also allowed
expect(result).toBe(2); but not required. A file may have any number of `#docregion` comments with the only requirement being that the names
}); of each region within a single file be unique. This also means that there can only be one *blank* docregion.
#### Example of a simple #docregion
code-example(format="linenums" language="js").
// #docregion
describe("Jasmine sample test", function() {
it("1+1 should be 2", function() {
var result = 1 + 1;
expect(result).toBe(2);
}); });
});
:marked :marked
If a file only has a single `#docregion` then the entire file AFTER the `#docregion` comment is available for inclusion If a file only has a single `#docregion` then the entire file AFTER the `#docregion` comment is available for inclusion
via mixin. Portions of the file can be indicated by surrounding an area of the file with via mixin. Portions of the file can be indicated by surrounding an area of the file with
`#docregion` and an `#enddocregion` tags. These regions, each with its own name, may be nested to any level and any regions that are not 'ended' explicitly `#docregion` and an `#enddocregion` tags. These regions, each with its own name, may be nested to any level and any regions that are not 'ended' explicitly
are assumed to be ended automatically at the bottom of the file. Regions may either be ended/closed by name or if the name is left blank then the most recent are assumed to be ended automatically at the bottom of the file. Regions may either be ended/closed by name or if the name is left blank then the most recent
unclosed docregion defined earlier will be closed. Any individual region within the file is accessible unclosed docregion defined earlier will be closed. Any individual region within the file is accessible
to the `makeExample` and `makeTabs` mixins. to the `makeExample` and `makeTabs` mixins.
#### Example of a nested #docregion #### Example of a nested #docregion
code-example(format="linenums" language="js" escape="html"). code-example(format="linenums" language="js" escape="html").
(function() { (function() {
// #docregion // #docregion
// #docregion class-w-annotations // #docregion class-w-annotations
var AppComponent = ng var AppComponent = ng
// #docregion component // #docregion component
.Component({ .Component({
selector: 'my-app' selector: 'my-app'
}) })
// #enddocregion component // #enddocregion component
// #docregion view // #docregion view
.View({ .View({
template: '<h1 id="output">My First Angular 2 App</h1>' template: '<h1 id="output">My First Angular 2 App</h1>'
}) })
// #enddocregion view // #enddocregion view
// #docregion class // #docregion class
.Class({ .Class({
constructor: function () { } constructor: function () { }
}); });
// #enddocregion // #enddocregion
// #enddocregion // #enddocregion
:marked :marked
Multiple `#docregion` tags may be defined on a single line as shown below. In addition, anytime a file contains multiple Multiple `#docregion` tags may be defined on a single line as shown below. In addition, anytime a file contains multiple
`#docregion` tags with the same name they will automatically be combined. Each of the individually tagged sections of the combined document `#docregion` tags with the same name they will automatically be combined. Each of the individually tagged sections of the combined document
will be separated from one another by a comment consisting of '. . .'. This default separator, known will be separated from one another by a comment consisting of '. . .'. This default separator, known
as 'plaster' can be overriden anywhere within the affected file via a `#docplaster` comment as shown below. This example creates as 'plaster' can be overriden anywhere within the affected file via a `#docplaster` comment as shown below. This example creates
a separator that consists of `/* more code here */` in the output file. a separator that consists of `/* more code here */` in the output file.
code-example(format="linenums" language="js" escape="html"). code-example(format="linenums" language="js" escape="html").
// #docplaster more code here // #docplaster more code here
// #docregion import,twoparts // #docregion import,twoparts
import {Component, View, bootstrap} from 'angular2/angular2'; import {Component, View, bootstrap} from 'angular2/angular2';
// #enddocregion twoparts, import // #enddocregion twoparts, import
@Component({ @Component({
selector: 'my-app' selector: 'my-app'
}) })
@View({ @View({
template: '<h1 id="output">My first Angular 2 App</h1>' template: '<h1 id="output">My first Angular 2 App</h1>'
}) })
class AppComponent { class AppComponent {
} }
// #docregion bootstrap, twoparts // #docregion bootstrap, twoparts
bootstrap(AppComponent); bootstrap(AppComponent);
// #enddocregion twoparts // #enddocregion twoparts
doSomethingInteresting(); doSomethingInteresting();
// #enddocregion // #enddocregion
:marked :marked
HTML files can also contain #docregion comments: HTML files can also contain #docregion comments:
code-example(format="linenums" language="html" escape="html"). code-example(format="linenums" language="html" escape="html").
<!-- #docregion --> <!-- #docregion -->
... ...
<script src="https://code.angularjs.org/2.0.0-alpha.34/angular2.sfx.dev.js"></script> <script src="https://code.angularjs.org/2.0.0-alpha.34/angular2.sfx.dev.js"></script>
<script src="app.js"></script> <script src="app.js"></script>
... ...
:marked :marked
as can CSS files: as can CSS files:
code-example(format="linenums" language="css"). code-example(format="linenums" language="css").
/* #docregion bar */ /* #docregion bar */
.center-global { .center-global {
max-width: 1020px; max-width: 1020px;
margin: 0 auto; margin: 0 auto;
} }
.l-sub-section
:marked
### Including a named #docregion via the makeExample or makeTabs mixins.
In order to include just a portion of an example file that has been marked up with a 'named' `#docregion` :marked
you will pass the name of the desired region as the 2nd parameter to the makeExample call. ### Including a named #docregion via the makeExample or makeTabs mixins.
#### Example In order to include just a portion of an example file that has been marked up with a 'named' `#docregion`
code-example(format="linenums" language="js"). you will pass the name of the desired region as the 2nd parameter to the makeExample call.
+makeExample('styleguide/js/app.js', 'class-w-annotations', "Extracted region")
:marked
is a request to include just the `class-w-annotations` region from the `app.js` file in the `_examples/styleguide`
folder and results in the following:
#### Example
code-example(format="linenums" language="js").
+makeExample('styleguide/js/app.js', 'class-w-annotations', "Extracted region") +makeExample('styleguide/js/app.js', 'class-w-annotations', "Extracted region")
.l-sub-section :marked
:marked is a request to include just the `class-w-annotations` region from the `app.js` file in the `_examples/styleguide`
### Additional styling folder and results in the following:
In some cases you may want to add additional styling to an external file after it had been included in the documentation. +makeExample('styleguide/js/app.js', 'class-w-annotations', "Extracted region")
This styling is accomplished via the `stylePattern` and `stylePatterns` parameters in the `makeExample` and `makeTabs`
mixins. A `stylePattern` is actually just a javascript object where the keys are the names of styles to be applied to
some portion of the included text as defined by a regular expression ( or expressions). These regular expressions are the
value of each key. Each regular expression MUST specify at least a single capture group; the contents of the capture
group being what the style will actually apply to, not the entire regular expression. The idea here is that you may
need to include a contextual match in a regular expression but only want your styling to be applied to a subset
of the entire regular expression.
Current there are only three types of highlight styles available: Outlined (otl), Pink (pnk), and Black (blk), however the
mechanism described above will work with any style defined on the page.
#### Example :marked
code-example(format="linenums" language="js" escape="none"). ### Additional styling
+makeExample('styleguide/js/index.html', null, 'index.html', {pnk: /script (src=.*&ampquot;)/g})
:marked In some cases you may want to add additional styling to an external file after it had been included in the documentation.
Which will mark all of the quoted contents of each `script` tag within the index.html file in pink. This styling is accomplished via the `stylePattern` and `stylePatterns` parameters in the `makeExample` and `makeTabs`
mixins. A `stylePattern` is actually just a javascript object where the keys are the names of styles to be applied to
some portion of the included text as defined by a regular expression ( or expressions). These regular expressions are the
value of each key. Each regular expression MUST specify at least a single capture group; the contents of the capture
group being what the style will actually apply to, not the entire regular expression. The idea here is that you may
need to include a contextual match in a regular expression but only want your styling to be applied to a subset
of the entire regular expression.
.alert.is-important. Current there are only three types of highlight styles available: Outlined (otl), Pink (pnk), and Black (blk), however the
Note that expression replacement occurs AFTER the fragment has been included and html escaped. mechanism described above will work with any style defined on the page.
This means that your regular expression must use escaped html text; i.e. the '&ampquot' in the regex above.
+makeExample('styleguide/js/index.html', null, 'index.html', {pnk: /script (src=.*&quot;)/g}) #### Example
code-example(format="linenums" language="js" escape="none").
+makeExample('styleguide/js/index.html', null, 'index.html', {pnk: /script (src=.*&ampquot;)/g})
:marked :marked
A more complicated example might be: Which will mark all of the quoted contents of each `script` tag within the index.html file in pink.
code-example(format="linenums" language="js"). .alert.is-important.
- var stylePattern = { pnk: /script (src=.*&ampquot;)/g, otl: /(\S*my-app.*$)/m }; Note that expression replacement occurs AFTER the fragment has been included and html escaped.
+makeExample('styleguide/js/index.html', null, 'index.html', stylePattern ) This means that your regular expression must use escaped html text; i.e. the '&ampquot' in the regex above.
:marked +makeExample('styleguide/js/index.html', null, 'index.html', {pnk: /script (src=.*&quot;)/g})
Which applies multiple styles and uses an intermediate javascript object as opposed to a literal.
- var stylePattern = { pnk: /script (src=.*&quot;)/g, otl: /(\S*my-app.*$)/m }; :marked
A more complicated example might be:
code-example(format="linenums" language="js").
- var stylePattern = { pnk: /script (src=.*&ampquot;)/g, otl: /(\S*my-app.*$)/m };
+makeExample('styleguide/js/index.html', null, 'index.html', stylePattern ) +makeExample('styleguide/js/index.html', null, 'index.html', stylePattern )
:marked :marked
`makeTabs` support for `stylePatterns` is slightly different from the `makeExample` mixin in that you can also Which applies multiple styles and uses an intermediate javascript object as opposed to a literal.
pass in an array of stylePattern objects where each is paired with its corresponding 'tab'. If only a single stylePattern
object is passed in then it is assumed to apply to all of the tabs.
code-example(format="linenums" language="js"). - var stylePattern = { pnk: /script (src=.*&quot;)/g, otl: /(\S*my-app.*$)/m };
-var stylePatterns = [{ pnk: /script (src=.*&ampquot;)/g }, {pnk: /(result)/ }]; +makeExample('styleguide/js/index.html', null, 'index.html', stylePattern )
+makeTabs('styleguide/js/index.html, styleguide/js/spec.js', null, 'index.html,unit test', stylePatterns)
-var stylePatterns = [{ pnk: /script (src=.*&quot;)/g }, {pnk: /(result)/ }]; :marked
`makeTabs` support for `stylePatterns` is slightly different from the `makeExample` mixin in that you can also
pass in an array of stylePattern objects where each is paired with its corresponding 'tab'. If only a single stylePattern
object is passed in then it is assumed to apply to all of the tabs.
code-example(format="linenums" language="js").
-var stylePatterns = [{ pnk: /script (src=.*&ampquot;)/g }, {pnk: /(result)/ }];
+makeTabs('styleguide/js/index.html, styleguide/js/spec.js', null, 'index.html,unit test', stylePatterns) +makeTabs('styleguide/js/index.html, styleguide/js/spec.js', null, 'index.html,unit test', stylePatterns)
.l-sub-section -var stylePatterns = [{ pnk: /script (src=.*&quot;)/g }, {pnk: /(result)/ }];
:marked +makeTabs('styleguide/js/index.html, styleguide/js/spec.js', null, 'index.html,unit test', stylePatterns)
### Including a JSON file or just parts of one
To include an '.json' file from somewhere in the `doc\_examples` folder you can use the `makeJson` mixin. The `makeExample`
and `makeTabs` mixins cannot be used for this purpose because there is no standard 'comment' marker in a json file.
The `makeJson` mixin does however provide a similar capability to selectively pick which portions of the '.json' file :marked
to display. ### Including a JSON file or just parts of one
The syntax for the `makeJson` mixin is: To include an '.json' file from somewhere in the `doc\_examples` folder you can use the `makeJson` mixin. The `makeExample`
and `makeTabs` mixins cannot be used for this purpose because there is no standard 'comment' marker in a json file.
#### +makeJson(filePath, jsonConfig, title, stylePattern) The `makeJson` mixin does however provide a similar capability to selectively pick which portions of the '.json' file
- *filePath:* path to the example file under the '_examples' folder to display.
- *jsonConfig:* (optional) an object that defines which portions of the .json file to select for display.
- *rootPath:* (optional default=null) a json property path at which the 'paths' parameter below should start.
- *paths:* a comma delimited list of property paths for those elements to be selected.
- *space:* (optional default=" " [2 spaces]) a String or Number object that's used to insert white space into the output JSON
- *title:* (optional) title displayed above the included text.
- *stylePattern:* (optional) allows additional styling via regular expression ( described above).
#### Example: The syntax for the `makeJson` mixin is:
code-example(format="linenums" language="js"). #### +makeJson(filePath, jsonConfig, title, stylePattern)
+makeJson('styleguide/package.json', null, "Entire package.json file") - *filePath:* path to the example file under the '_examples' folder
- *jsonConfig:* (optional) an object that defines which portions of the .json file to select for display.
- *rootPath:* (optional default=null) a json property path at which the 'paths' parameter below should start.
- *paths:* a comma delimited list of property paths for those elements to be selected.
- *space:* (optional default=" " [2 spaces]) a String or Number object that's used to insert white space into the output JSON
- *title:* (optional) title displayed above the included text.
- *stylePattern:* (optional) allows additional styling via regular expression ( described above).
#### Example:
code-example(format="linenums" language="js").
+makeJson('styleguide/package.json', null, "Entire package.json file") +makeJson('styleguide/package.json', null, "Entire package.json file")
:marked +makeJson('styleguide/package.json', null, "Entire package.json file")
A subset of the '.json' file can also be selected.
code-example(format="linenums" language="js"). :marked
+makeJson('styleguide/package.json', { paths: 'version, scripts.tsc, scripts.start '}, "Selected parts of the package.json file" ) A subset of the '.json' file can also be selected.
code-example(format="linenums" language="js").
+makeJson('styleguide/package.json', { paths: 'version, scripts.tsc, scripts.start '}, "Selected parts of the package.json file" ) +makeJson('styleguide/package.json', { paths: 'version, scripts.tsc, scripts.start '}, "Selected parts of the package.json file" )
:marked +makeJson('styleguide/package.json', { paths: 'version, scripts.tsc, scripts.start '}, "Selected parts of the package.json file" )
Styling selected portions of the json is also supported.
code-example(format="linenums" language="js"). :marked
+makeJson('styleguide/package.json', {paths: 'dependencies'}, "package.json dependencies", { pnk: [/(\S*traceur.*)/, /(\Sangular2.*)/, /(\Ssystem.*)/ ]}) Styling selected portions of the json is also supported.
code-example(format="linenums" language="js").
+makeJson('styleguide/package.json', {paths: 'dependencies'}, "package.json dependencies", { pnk: [/(\S*traceur.*)/, /(\Sangular2.*)/, /(\Ssystem.*)/ ]}) +makeJson('styleguide/package.json', {paths: 'dependencies'}, "package.json dependencies", { pnk: [/(\S*traceur.*)/, /(\Sangular2.*)/, /(\Ssystem.*)/ ]})
:marked +makeJson('styleguide/package.json', {paths: 'dependencies'}, "package.json dependencies", { pnk: [/(\S*traceur.*)/, /(\Sangular2.*)/, /(\Ssystem.*)/ ]})
As well as styling across multiple lines.
code-example(format="linenums" language="js"). :marked
- var styles = { pnk: /(^.*dependencies[\s\S]* \})/gm }; As well as styling across multiple lines.
+makeJson('styleguide/package.json', {paths: 'name, version, dependencies '}, "Foo", styles )
code-example(format="linenums" language="js").
- var styles = { pnk: /(^.*dependencies[\s\S]* \})/gm }; - var styles = { pnk: /(^.*dependencies[\s\S]* \})/gm };
+makeJson('styleguide/package.json', {paths: 'name, version, dependencies '}, "Foo", styles ) +makeJson('styleguide/package.json', {paths: 'name, version, dependencies '}, "Foo", styles )
.l-sub-section - var styles = { pnk: /(^.*dependencies[\s\S]* \})/gm };
:marked +makeJson('styleguide/package.json', {paths: 'name, version, dependencies '}, "Foo", styles )
### Inline code and code examples provided directly i.e. not from an example file.
The `makeExample` and `makeTabs` mixins are both both built on top of a custom jade 'style'; `code-example`. :marked
In those cases where you want to include code directly inline i.e. not from some external file; you can use ### Inline code and code examples provided directly i.e. not from an example file.
this style.
This style has several named attributes
#### code-example attributes The `makeExample` and `makeTabs` mixins are both both built on top of a custom jade 'style'; `code-example`.
- *name:* Name displayed in Tab (required for tabs) In those cases where you want to include code directly inline i.e. not from some external file; you can use
- *language:* javascript, html, etc. this style.
- *escape:* html (escapes html, woot!) This style has several named attributes
- *format:* linenums (or linenums:4 specify starting line)
#### Example #### code-example attributes
- *name:* Name displayed in Tab (required for tabs)
- *language:* javascript, html, etc.
- *escape:* html (escapes html, woot!)
- *format:* linenums (or linenums:4 specify starting line)
code-example(format="linenums" language="html"). #### Example
code-example(format="linenums" language="javascript").
//SOME CODE
.l-sub-section code-example(format="linenums" language="html").
h3 Specify starting line number code-example(format="linenums" language="javascript").
//SOME CODE
code-example(language="javascript" format="linenums:4").
code-example(language="html" format="linenums:4").
var title = "This starts on line four";
.l-sub-section h3 Specify starting line number
h3 Specify a language
p. code-example(language="javascript" format="linenums:4").
Prettify makes a best effort to guess the language but code-example(language="html" format="linenums:4").
works best with C-like and HTML-like languages. For var title = "This starts on line four";
others, there are special language handlers that are
chosen based on language hints. Add a class that matches
your desired language (example below uses <strong>.lang-html</strong>)
code-example(language="html" format="linenums").
&lt;h1&gt;Title&lt;/h1&gt;
&lt;p&gt;This is some copy...&lt;/p&gt;
.l-sub-section h3 Specify a language
h3 Code Highlighting
p.
There are three types of highlights available
<strong>Outlined</strong>, <strong>Pink</strong>, and
<strong>Black</strong>. You can see examples below and
the class names needed for each type.
code-example(format="linenums"). p.
// Pink Background Version Prettify makes a best effort to guess the language but
// class="pnk" works best with C-like and HTML-like languages. For
var elephants = "The <span class='pnk'>pink</span> elephants were marching..."; others, there are special language handlers that are
chosen based on language hints. Add a class that matches
your desired language (example below uses <strong>.lang-html</strong>)
// Black Background Version code-example(language="html" format="linenums").
// class="blk" &lt;h1&gt;Title&lt;/h1&gt;
var night = "The night was pitch <span class='blk'>black</span>."; &lt;p&gt;This is some copy...&lt;/p&gt;
// Outlined Version
// class="otl"
var match = "The <span class='otl'>bird</span> ate <span class='otl'>bird</span> seed near the <span class='otl'>bird</span> bath ";
.l-sub-section h3 Code Highlighting
h3 Code Tabs p.
p. There are three types of highlights available
Code Tabs are a great way to show different languages and versions <strong>Outlined</strong>, <strong>Pink</strong>, and
of a particular piece of code. When using these tabs make sure the <strong>Black</strong>. You can see examples below and
<strong>content is always related</strong>. the class names needed for each type.
code-example(format="linenums").
// Pink Background Version
// class="pnk"
var elephants = "The <span class='pnk'>pink</span> elephants were marching...";
// Black Background Version
// class="blk"
var night = "The night was pitch <span class='blk'>black</span>.";
// Outlined Version
// class="otl"
var match = "The <span class='otl'>bird</span> ate <span class='otl'>bird</span> seed near the <span class='otl'>bird</span> bath ";
h3 Code Tabs
p.
Code Tabs are a great way to show different languages and versions
of a particular piece of code. When using these tabs make sure the
<strong>content is always related</strong>.
code-tabs
code-pane(language="javascript" format="linenums" name="ES5").
// ES5
var hello = 'blah';
code-pane(language="javascript" format="linenums" name="TypeScript").
// TypeScript
var hello = 'blah';
p To create code tabs simply use the directives below
code-example(format="linenums").
code-tabs code-tabs
code-pane(language="javascript" format="linenums" name="ES5"). code-pane(format="linenums" name="Tab 1").
// ES5 // TAB 1 CONTENT
var hello = 'blah'; code-pane(format="linenums" name="Tab 2").
// TAB 2 CONTENT
code-pane(language="javascript" format="linenums" name="TypeScript"). :marked
// TypeScript ### Combining makeExample, makeTabs mixins with code-example style attributes
var hello = 'blah'; As mentioned above the `makeExample` and `makeTabs` mixins are built on top of the `code-example` style. By default
the mixins automatically determine a language based on the example file's extensions and always include line numbers.
p To create code tabs simply use the directives below You can override this behavior by including code-example attributes within parentheses after the mixin parameters.
code-example(format="linenums").
code-tabs
code-pane(format="linenums" name="Tab 1").
// TAB 1 CONTENT
code-pane(format="linenums" name="Tab 2").
// TAB 2 CONTENT
.l-sub-section #### Example
:marked
### Combining makeExample, makeTabs mixins with code-example style attributes
As mentioned above the `makeExample` and `makeTabs` mixins are built on top of the `code-example` style. By default
the mixins automatically determine a language based on the example file's extensions and always include line numbers.
You can override this behavior by including code-example attributes within parentheses after the mixin parameters.
#### Example
code-example().
+makeExample('styleguide/js/app.js', "class-w-annotations")(format="linenums:15")
:marked
Starts the numbering of the example at line 15.
code-example().
+makeExample('styleguide/js/app.js', "class-w-annotations")(format="linenums:15") +makeExample('styleguide/js/app.js', "class-w-annotations")(format="linenums:15")
:marked :marked
Or to suppress line numbering completely you can use Starts the numbering of the example at line 15.
code-example(). +makeExample('styleguide/js/app.js', "class-w-annotations")(format="linenums:15")
+makeExample('styleguide/js/app.js', 'class-w-annotations')(format=".")
:marked
Or to suppress line numbering completely you can use
code-example().
+makeExample('styleguide/js/app.js', 'class-w-annotations')(format=".") +makeExample('styleguide/js/app.js', 'class-w-annotations')(format=".")
.l-sub-section +makeExample('styleguide/js/app.js', 'class-w-annotations')(format=".")
:marked
### Code examples in angular/angular source code
References to embedded example code in the angular/angular source make use of the same mixins as defined above, but with a slightly different
syntax. Inline tags in source code comments like {@example ...} and {@exampleTabs ...} actually generate 'makeExample' and 'makeTabs' mixins
calls in the documentation. The order of 'arguments' in the inline tags is also the same as that of the mixins defined above. However, optional
parameters can also be specified via name (optionally prefixed with a '-'), as will be shown by example below. Parameters that include spaces should
be enclosed in either single or double quotes. This syntax is intended to mirror standard command line argument patterns.
.alert.is-important. :marked
The '@example' and '@exampleTabs' inline tags MUST always appear at the beginning of a line. ### Code examples in angular/angular source code
Example files referenced by inline tags are all assumed to be in the 'modules/angular2' folder in the angular/angular repo. References to embedded example code in the angular/angular source make use of the same mixins as defined above, but with a slightly different
syntax. Inline tags in source code comments like {@example ...} and {@exampleTabs ...} actually generate 'makeExample' and 'makeTabs' mixins
calls in the documentation. The order of 'arguments' in the inline tags is also the same as that of the mixins defined above. However, optional
parameters can also be specified via name (optionally prefixed with a '-'), as will be shown by example below. Parameters that include spaces should
be enclosed in either single or double quotes. This syntax is intended to mirror standard command line argument patterns.
:marked .alert.is-important.
#### @example inline tag parameters The '@example' and '@exampleTabs' inline tags MUST always appear at the beginning of a line.
- *filePath:* path to the example file under the '_examples' folder
- *region:* (optional or null) region from the example file to display
- *title:* (optional or null) title displayed above the included text.
- *stylePattern:* (optional or null) allows additional styling via regular expression ( described later).
#### Examples Example files referenced by inline tags are all assumed to be in the 'modules/angular2' folder in the angular/angular repo.
code-example(format="linenums" language="js"). :marked
/** #### @example inline tag parameters
* An example with no region - *filePath:* path to the example file under the '_examples' folder
* {@example core/directives/ng_if_spec.ts -title='Whole other component' } - *region:* (optional or null) region from the example file to display
* - *title:* (optional or null) title displayed above the included text.
* An example with a region and a title both specified by name - *stylePattern:* (optional or null) allows additional styling via regular expression ( described later).
* {@example core/directives/ng_if_spec.ts region='ng-if' title='Partial' }
*
* Another example with a region and a title with only the title specified explicitly.
* {@example core/directives/ng_if_spec.ts foo title='Foo' }
**/
:marked #### Examples
#### @exampleTabs inline tag parameters
- *filePaths:* a comma delimited string of filePaths to example files under the '_examples' folder
- *regions:* (optional or null) region from the example file to display
- *titles:* (optional or null) a comma delimited string of titles corresponding to each of the filePaths above.
- *stylePatterns:* (optional or null) allows additional styling via regular expression( described later).
#### Examples code-example(format="linenums" language="js").
/**
* An example with no region
* {@example core/directives/ng_if_spec.ts -title='Whole other component' }
*
* An example with a region and a title both specified by name
* {@example core/directives/ng_if_spec.ts region='ng-if' title='Partial' }
*
* Another example with a region and a title with only the title specified explicitly.
* {@example core/directives/ng_if_spec.ts foo title='Foo' }
**/
code-example(format="linenums" language="js"). :marked
/** #### @exampleTabs inline tag parameters
* An example with multiple tabs each with its own region and title. - *filePaths:* a comma delimited string of filePaths to example files under the '_examples' folder
* {@exampleTabs core/directives/test1_spec.ts,core/directives/test2_spec.ts regions='aaa,bbb,' -titles='Test 1,Test 2' } - *regions:* (optional or null) region from the example file to display
* - *titles:* (optional or null) a comma delimited string of titles corresponding to each of the filePaths above.
**/ - *stylePatterns:* (optional or null) allows additional styling via regular expression( described later).
.l-sub-section #### Examples
:marked
### Cross references to Developer guide pages in angular/angular source comments.
The '{@linkDevGuide ... }' inline tag is intended to be used to create links from api documentation to dev guide code-example(format="linenums" language="js").
documentation. /**
* An example with multiple tabs each with its own region and title.
* {@exampleTabs core/directives/test1_spec.ts,core/directives/test2_spec.ts regions='aaa,bbb,' -titles='Test 1,Test 2' }
*
**/
#### @linkDevGuide inline tag parameters
- *filePath:* a filePath that points to a jade page in the DevGuide without the .jade extension ( under public/docs ).
- *title:* The title of link. If the title is omitted an attempt will be made to determine the title of the jade page
being pointed to. If not found the then title will simply be the link.
#### Examples
code-example(format="linenums" language="js"). :marked
/** ### Cross references to Developer guide pages in angular/angular source comments.
* An link to the Developer guide example with a link title
* This can appear anywhere in a comment line: {@linkDevGuide /js/latest/guide/gettingStarted 'Getting Started' } The '{@linkDevGuide ... }' inline tag is intended to be used to create links from api documentation to dev guide
* and the same link can also be expressed with an explicit 'title' param documentation.
* {@linkDevGuide /js/latest/guide/gettingStarted title='Getting Started' }
* Or... an attempt will be made to infer the title if it is omitted. #### @linkDevGuide inline tag parameters
* {@linkDevGuide /js/latest/guide/gettingStarted } - *filePath:* a filePath that points to a jade page in the DevGuide without the .jade extension ( under public/docs ).
**/ - *title:* The title of link. If the title is omitted an attempt will be made to determine the title of the jade page
being pointed to. If not found the then title will simply be the link.
#### Examples
code-example(format="linenums" language="js").
/**
* An link to the Developer guide example with a link title
* This can appear anywhere in a comment line: {@linkDevGuide /js/latest/guide/gettingStarted 'Getting Started' }
* and the same link can also be expressed with an explicit 'title' param
* {@linkDevGuide /js/latest/guide/gettingStarted title='Getting Started' }
* Or... an attempt will be made to infer the title if it is omitted.
* {@linkDevGuide /js/latest/guide/gettingStarted }
**/

12
public/docs/ts/latest/guide/displaying-data.jade
View File

@ -186,7 +186,7 @@ figure.image-display
advantage of a TypeScript short-cut in our declaration of the constructor parameters. advantage of a TypeScript short-cut in our declaration of the constructor parameters.
Consider the first parameter: Consider the first parameter:
+makeExample('displaying-data/ts/src/app/hero.ts', 'id-parameter')(format=".") +makeExample('displaying-data/ts/src/app/hero.ts', 'id-parameter')
:marked :marked
That brief syntax simultaneously That brief syntax simultaneously
@ -221,7 +221,7 @@ figure.image-display
The Angular `NgIf` directive will insert or remove an element based on a truthy/falsey condition. The Angular `NgIf` directive will insert or remove an element based on a truthy/falsey condition.
We can see it in action by adding the following paragraph at the bottom of the template: We can see it in action by adding the following paragraph at the bottom of the template:
+makeExample('displaying-data/ts/src/app/app.final.ts', 'message')(format=".") +makeExample('displaying-data/ts/src/app/app.final.ts', 'message')
.alert.is-important .alert.is-important
:marked :marked
Don't forget the leading asterisk (\*) in front of `*ng-if`. It is an essential part of the syntax. Don't forget the leading asterisk (\*) in front of `*ng-if`. It is an essential part of the syntax.
@ -243,11 +243,11 @@ figure.image-display
As with the `NgFor`, we must add the `NgIf` directive to the component's metadata. As with the `NgFor`, we must add the `NgIf` directive to the component's metadata.
We should extend our `import` statement as before ... We should extend our `import` statement as before ...
+makeExample('displaying-data/ts/src/app/app.3.ts', 'import-ng-if')(format=".") +makeExample('displaying-data/ts/src/app/app.3.ts', 'import-ng-if')
:marked :marked
... and add it to the directives array: ... and add it to the directives array:
+makeExample('displaying-data/ts/src/app/app.3.ts', 'directives')(format=".") +makeExample('displaying-data/ts/src/app/app.3.ts', 'directives')
:marked :marked
Try it out. We have four items in the array so the message should appear. Try it out. We have four items in the array so the message should appear.
@ -267,11 +267,11 @@ figure.image-display
Let's simplify our lives, discard the `NgFor` and `NgIf`, use the constant for all of them. Let's simplify our lives, discard the `NgFor` and `NgIf`, use the constant for all of them.
We'll revise our `import` statement one last time. We'll revise our `import` statement one last time.
+makeExample('displaying-data/ts/src/app/app.final.ts', 'imports')(format=".") +makeExample('displaying-data/ts/src/app/app.final.ts', 'imports')
:marked :marked
and update the `directives` metadata and update the `directives` metadata
+makeExample('displaying-data/ts/src/app/app.final.ts', 'directives')(format=".") +makeExample('displaying-data/ts/src/app/app.final.ts', 'directives')
:marked :marked
Pro tip: we register this constant in almost every template we write. Pro tip: we register this constant in almost every template we write.

3
public/resources/css/module/_code.scss
View File

@ -26,7 +26,8 @@
background: $steel; background: $steel;
font-family: $mono-font; font-family: $mono-font;
color: $snow; color: $snow;
overflow: hidden; width: auto;
overflow: auto;
position: relative; position: relative;
padding: 0px; padding: 0px;
font-size: 15px; font-size: 15px;