From 8b4edcc7adc73957f08b546b84b7b3acefd180ec Mon Sep 17 00:00:00 2001 From: Pete Bacon Darwin Date: Wed, 22 Mar 2017 20:24:40 +0000 Subject: [PATCH] build(aio): output `{@example}` tags as `` elements (#15382) --- aio/e2e/app.e2e-spec.ts | 7 +- aio/e2e/app.po.ts | 6 ++ .../inline-tag-defs/example.js | 68 +++++++++++-------- .../inline-tag-defs/example.spec.js | 63 +++++++++++++++++ .../services/parseArgString.js | 5 +- .../templates/example-region.template.html | 8 +-- 6 files changed, 118 insertions(+), 39 deletions(-) create mode 100644 aio/transforms/examples-package/inline-tag-defs/example.spec.js diff --git a/aio/e2e/app.e2e-spec.ts b/aio/e2e/app.e2e-spec.ts index d7ed0a5eda..6a17b01ab1 100644 --- a/aio/e2e/app.e2e-spec.ts +++ b/aio/e2e/app.e2e-spec.ts @@ -31,7 +31,12 @@ describe('site App', function() { expect(page.getDocViewerText()).toMatch(/Tutorial: Tour of Heroes/i); }); - it('should convert a doc with a code-example'); + it('should render `{@example}` dgeni tags as `` elements with HTML escaped content', () => { + page.navigateTo('guide/component-styles'); + const codeExample = element.all(by.css('code-example')).first(); + expect(page.getInnerHtml(codeExample)) + .toContain('@Component({\n selector: \'hero-app\',\n template: `\n <h1>Tour of Heroes</h1>'); + }); describe('api-docs', () => { it('should show a link to github', () => { diff --git a/aio/e2e/app.po.ts b/aio/e2e/app.po.ts index fb634f67b8..3dc3d4a02f 100644 --- a/aio/e2e/app.po.ts +++ b/aio/e2e/app.po.ts @@ -28,6 +28,12 @@ export class SitePage { return this.docViewer.getText(); } + getInnerHtml(element) { + // `getInnerHtml` was removed from webDriver and this is the workaround. + // See https://github.com/angular/protractor/blob/master/CHANGELOG.md#breaking-changes + return browser.executeScript('return arguments[0].innerHTML;', element); + } + /** * Replace the ambient Google Analytics tracker with homebrew spy * don't send commands to GA during e2e testing! diff --git a/aio/transforms/examples-package/inline-tag-defs/example.js b/aio/transforms/examples-package/inline-tag-defs/example.js index 3b7b11d8f3..e48f6d3aae 100644 --- a/aio/transforms/examples-package/inline-tag-defs/example.js +++ b/aio/transforms/examples-package/inline-tag-defs/example.js @@ -28,40 +28,48 @@ module.exports = function exampleInlineTagDef( var unnamedArgs = tagArgs._; var relativePath = unnamedArgs[0]; var regionName = tagArgs.region || (unnamedArgs.length > 1 ? unnamedArgs[1] : ''); - var title = tagArgs.title || (unnamedArgs.length > 2 ? unnamedArgs[2] : null); + if (regionName === '\'\'') regionName = ''; + var title = tagArgs.title || (unnamedArgs.length > 2 ? unnamedArgs.slice(2).join(' ') : null); + var linenums = tagArgs.linenums; var stylePattern = tagArgs.stylePattern; // TODO: not yet implemented here - // Find the example in the folders - var exampleFile; - // Try an "annotated" version first - EXAMPLES_FOLDERS.some( - EXAMPLES_FOLDER => { return exampleFile = exampleMap[EXAMPLES_FOLDER][relativePath + '.annotated']; }); + const sourceCode = getExampleRegion(); - // If no annotated version is available then try the actual file - if (!exampleFile) { - EXAMPLES_FOLDERS.some( - EXAMPLES_FOLDER => { return exampleFile = exampleMap[EXAMPLES_FOLDER][relativePath]; }); + const attributes = []; + if (title) attributes.push(` title="${title}"`); + if (linenums !== undefined) attributes.push(` linenums="${linenums}"`); + + return '\n' + sourceCode + '\n'; + + + function getExampleRegion() { + // Find the example in the folders + var exampleFile; + // Try an "annotated" version first + EXAMPLES_FOLDERS.some(EXAMPLES_FOLDER => { return exampleFile = exampleMap[EXAMPLES_FOLDER][relativePath + '.annotated']; }); + + // If no annotated version is available then try the actual file + if (!exampleFile) { + EXAMPLES_FOLDERS.some(EXAMPLES_FOLDER => { return exampleFile = exampleMap[EXAMPLES_FOLDER][relativePath]; }); + } + + // If still no file then we error + if (!exampleFile) { + log.error(createDocMessage('Missing example file... relativePath: "' + relativePath + '".', doc)); + log.error('Example files can be found in: ' + EXAMPLES_FOLDERS.join(', ')); + return ''; + } + + var sourceCodeDoc = exampleFile.regions[regionName]; + if (!sourceCodeDoc) { + log.error(createDocMessage('Missing example region... relativePath: "' + relativePath + '", region: "' + regionName + '".', doc)); + log.error('Regions available are:', Object.keys[exampleFile.regions]); + return ''; + } + + return sourceCodeDoc.renderedContent; } - - // If still no file then we error - if (!exampleFile) { - log.error( - createDocMessage('Missing example file... relativePath: "' + relativePath + '".', doc)); - log.error('Example files can be found in: ' + EXAMPLES_FOLDERS.join(', ')); - return ''; - } - - var sourceCode = exampleFile.regions[regionName]; - if (!sourceCode) { - log.error(createDocMessage( - 'Missing example region... relativePath: "' + relativePath + '", region: "' + - regionName + '".', - doc)); - log.error('Regions available are:', Object.keys[exampleFile.regions]); - return ''; - } - - return sourceCode.renderedContent; } }; }; + diff --git a/aio/transforms/examples-package/inline-tag-defs/example.spec.js b/aio/transforms/examples-package/inline-tag-defs/example.spec.js new file mode 100644 index 0000000000..5c32c38682 --- /dev/null +++ b/aio/transforms/examples-package/inline-tag-defs/example.spec.js @@ -0,0 +1,63 @@ +var testPackage = require('../../helpers/test-package'); +var Dgeni = require('dgeni'); + +describe('example inline-tag-def', function() { + let injector, tag, collectExamples, exampleMap; + + beforeEach(() => { + const dgeni = new Dgeni([testPackage('examples-package', true)]); + injector = dgeni.configureInjector(); + tag = injector.get('exampleInlineTagDef'); + collectExamples = injector.get('collectExamples'); + exampleMap = injector.get('exampleMap'); + }); + + it('should be available as a service', () => { + expect(tag).toBeDefined(); + expect(tag.name).toEqual('example'); + }); + + describe('handler', () => { + let handler; + + beforeEach(() => { + handler = tag.handler; + collectExamples.exampleFolders = ['examples']; + exampleMap['examples'] = { + 'test/url': { regions: { + '': { renderedContent: 'whole file' }, + 'region-1': { renderedContent: 'region 1 contents' } + } } + }; + }); + + it('should return a tag', () => { + expect(handler({}, 'example', 'some/uri')).toEqual('\n\n'); + }); + + it('should contain the whole contents from the example file if no region is specified', () => { + expect(handler({}, 'example', 'test/url')).toEqual('\nwhole file\n'); + }); + + it('should contain the region contents from the example file if a region is specified', () => { + expect(handler({}, 'example', 'test/url region-1')).toEqual('\nregion 1 contents\n'); + }); + + it('should add a title if specified', () => { + expect(handler({}, 'example', 'test/url region-1 \'Some Title\'')).toEqual('\nregion 1 contents\n'); + expect(handler({}, 'example', 'test/url region-1 Some Title')).toEqual('\nregion 1 contents\n'); + }); + + it('should contain the whole contents from the example file if an empty ("") region is specified', () => { + expect(handler({}, 'example', 'test/url \'\'')).toEqual('\nwhole file\n'); + expect(handler({}, 'example', 'test/url \'\' Some Title')).toEqual('\nwhole file\n'); + }); + + it('should add in linenum attribute if specified', () => { + expect(handler({}, 'example', 'test/url --linenums=\'false\'')).toEqual('\nwhole file\n'); + expect(handler({}, 'example', 'test/url --linenums=\'true\'')).toEqual('\nwhole file\n'); + expect(handler({}, 'example', 'test/url --linenums=\'15\'')).toEqual('\nwhole file\n'); + }); + }); +}); + diff --git a/aio/transforms/examples-package/services/parseArgString.js b/aio/transforms/examples-package/services/parseArgString.js index b19ce46be6..6bfa79a322 100644 --- a/aio/transforms/examples-package/services/parseArgString.js +++ b/aio/transforms/examples-package/services/parseArgString.js @@ -39,7 +39,10 @@ module.exports = function parseArgString() { } else { if (arg.substr(arg.length - 1) === '=') { key = arg.substr(0, arg.length - 1); - // remove leading '-' if it exists. + // remove leading '-' (or '--') if it exists. + if (key.substr(0, 1) == '-') { + key = key.substr(1); + } if (key.substr(0, 1) == '-') { key = key.substr(1); } diff --git a/aio/transforms/templates/example-region.template.html b/aio/transforms/templates/example-region.template.html index d6dcfa830c..8ecb1e9941 100644 --- a/aio/transforms/templates/example-region.template.html +++ b/aio/transforms/templates/example-region.template.html @@ -1,7 +1 @@ -
-{% marked %} -``` -{$ doc.contents $} -``` -{% endmarked %} -
\ No newline at end of file +{$ doc.contents | escape $} \ No newline at end of file