1616cae5cf
This processor will eventually replace the `{@example}` inline tags
because it provides a cleaner approach that also supports tabbed examples
straight out of the box.
The idea is that authors will simply add a `path` and (optionally) a `region`
attribute to `<code-example>` or `<code-pane>` elements in their docs.
This indicates to dgeni that the relevant example needs to be injected
into the content of this element.
For example, assume that there is an example file `toh-pt1/index.hml` with
a region called `title`, which looks like:
```
<h1>Tour of Heroes</h1>
```
Then the document author could get this to appear in the docs as a
standalone example:
```
<code-example path="toh-pt1" region="title"></code-example>
```
Or as part of a tabbed group:
```
<code-tabs>
<code-pane path="toh-pt1" region="title"></code-pane>
</code-tabs>
```
If no `path` attribute is provided then the element is ignored, which
enables authors to provide inline code instead:
```
<code-example>
Some <html> escaped code
</code-example>
```
Also all attributes other than `path` and `region` are ignored and passed
through to the final rendered output allowing the author to provide
styling hints:
```
<code-example path="toh-pt1" region="title" linenums"15" class="important">
</code-example>
```
85 lines
3.6 KiB
JavaScript
85 lines
3.6 KiB
JavaScript
var testPackage = require('../../helpers/test-package');
|
|
var Dgeni = require('dgeni');
|
|
var path = require('path');
|
|
|
|
describe('renderExamples processor', () => {
|
|
var injector, processor, exampleMap, regionParser, collectExamples, exampleMap;
|
|
|
|
beforeEach(function() {
|
|
const dgeni = new Dgeni([testPackage('examples-package', true)]);
|
|
injector = dgeni.configureInjector();
|
|
|
|
exampleMap = injector.get('exampleMap');
|
|
processor = injector.get('renderExamples');
|
|
collectExamples = injector.get('collectExamples');
|
|
exampleMap = injector.get('exampleMap');
|
|
|
|
collectExamples.exampleFolders = ['examples'];
|
|
exampleMap['examples'] = {
|
|
'test/url': { regions: {
|
|
'': { renderedContent: 'whole file' },
|
|
'region-1': { renderedContent: 'region 1 contents' }
|
|
} }
|
|
};
|
|
});
|
|
|
|
it('should run before the correct processor', () => {
|
|
expect(processor.$runBefore).toEqual(['writing-files'])
|
|
});
|
|
|
|
it('should run after the correct processor', () => {
|
|
expect(processor.$runAfter).toEqual(['docs-rendered']);
|
|
});
|
|
|
|
['code-example', 'code-pane'].forEach(CODE_TAG =>
|
|
describe(CODE_TAG, () => {
|
|
it(`should ignore a <${CODE_TAG}> tags with no path attribute`, () => {
|
|
const docs = [
|
|
{ renderedContent: `Some text\n<${CODE_TAG}>Some code</${CODE_TAG}>\n<${CODE_TAG} class="anti-pattern" title="Bad Code">do not do this</${CODE_TAG}>` }
|
|
];
|
|
processor.$process(docs);
|
|
expect(docs[0].renderedContent).toEqual(`Some text\n<${CODE_TAG}>Some code</${CODE_TAG}>\n<${CODE_TAG} class="anti-pattern" title="Bad Code">do not do this</${CODE_TAG}>`);
|
|
});
|
|
|
|
it(`should replace the content of the <${CODE_TAG}> tag with the whole contents from an example file if a path is provided`, () => {
|
|
const docs = [
|
|
{ renderedContent: `<${CODE_TAG} path="test/url">Some code</${CODE_TAG}>`}
|
|
];
|
|
processor.$process(docs);
|
|
expect(docs[0].renderedContent).toEqual(`<${CODE_TAG}>\nwhole file\n</${CODE_TAG}>`);
|
|
});
|
|
|
|
it('should contain the region contents from the example file if a region is specified', () => {
|
|
const docs = [
|
|
{ renderedContent: `<${CODE_TAG} path="test/url" region="region-1">Some code</${CODE_TAG}>` }
|
|
];
|
|
processor.$process(docs);
|
|
expect(docs[0].renderedContent).toEqual(`<${CODE_TAG}>\nregion 1 contents\n</${CODE_TAG}>`);
|
|
});
|
|
|
|
it(`should replace the content of the <${CODE_TAG}> tag with the whole contents from an example file if the region is empty`, () => {
|
|
const docs = [
|
|
{ renderedContent: `<${CODE_TAG} path="test/url" region="">Some code</${CODE_TAG}>` }
|
|
];
|
|
processor.$process(docs);
|
|
expect(docs[0].renderedContent).toEqual(`<${CODE_TAG}>\nwhole file\n</${CODE_TAG}>`);
|
|
});
|
|
|
|
it('should remove the path and region attributes but leave the other attributes alone', () => {
|
|
const docs = [
|
|
{ renderedContent: `<${CODE_TAG} class="special" path="test/url" linenums="15" region="region-1" id="some-id">Some code</${CODE_TAG}>` }
|
|
];
|
|
processor.$process(docs);
|
|
expect(docs[0].renderedContent).toEqual(`<${CODE_TAG} class="special" linenums="15" id="some-id">\nregion 1 contents\n</${CODE_TAG}>`);
|
|
});
|
|
|
|
it('should cope with spaces and double quotes inside attribute values', () => {
|
|
const docs = [
|
|
{ renderedContent: `<${CODE_TAG} title='a "quoted" value' path="test/url"></${CODE_TAG}>`}
|
|
];
|
|
processor.$process(docs);
|
|
expect(docs[0].renderedContent).toEqual(`<${CODE_TAG} title="a "quoted" value">\nwhole file\n</${CODE_TAG}>`);
|
|
});
|
|
})
|
|
);
|
|
}); |