From cf2fc2b2b4fed5f77944a93081e1cd57018b0535 Mon Sep 17 00:00:00 2001 From: Alan Gutierrez Date: Tue, 25 Jun 2013 14:23:58 -0400 Subject: [PATCH] Create and document `stencil` object. File Raw Min Zip Min/Zip index.js 30967/30.24 10077/09.84 7617/07.44 3848/03.76 Closes #119. --- README.md | 42 ++++++++++++++++++++---------------------- index.js | 9 ++++----- 2 files changed, 24 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 02193c9..1fb88c0 100644 --- a/README.md +++ b/README.md @@ -146,28 +146,26 @@ pleasing. But, again, why? Only because I'm doing this stupid thing with prototypes that I'm going to try to document right here... -### The `stencil` Variable - -The `stencil` variable is a special object added to the context by the Stencil -that has properties of the current template. It is not visible in the ordinary -scope of template, (why? why not? I mean really, why was this important? now you -have to add a paragraph explaining special properties? Are you just being a -bonehead? Didn't we talk about that? No really, I can't wait to see this...) - -You can distinguish the context variables set by the Stencil engine from the -context variables set by your application using `hasOwnProperty`. I'm not sure -if this is useful, but it's there. - -(Oh, you're a real prize. Can we please [kill this -poodle](http://www.lileks.com/bleats/archive/03/0103/010301.html#010303)? You -know how else you could distinguish between a property set by the Stencil engine -and a property provided by your application? `key == "stencil"`. Yes. You are a -bonehead. TODO: Don't be such a bonehead. Then you don't have to document this. -You might not be able to accept this right now, but there are people in this -world how are smart enough to figure that out for themselves, I know, hard to -accept that world won't embrace the genius of your using object prototypes to do -something, that you know what you're doing, but there are object prototypes -involved and that's really special, so, I can't even, I can't.) +### The `stencil` Object + +The `stencil` variable contains a special object added to the context by the +Stencil that has properties of the current template. The `stencil` variable is +constantly reset and overrides and variable assignments by the user. + +The `stencil` Object offers the following properties and methods. + + * `url` — The URL of the current Stencil. + * `absolutize(base, path)` — Creates an absolute path using the given + base and sub-path. If the sub-path begins with a `/`, it is treated as a full + qualified path. + * `normalize(path)` — Normalizes a file path so that + `/docs/./articles/../posts/post.html` is normalized to + `/docs/posts/post.html`. + * `json(url)` — Returns a Stencil callback that will fetch the given URL + and parse it as JSON. + +TK: Find a place to write more about `json(url)` and send the readers of this +section to that place. ## Tag Libraries diff --git a/index.js b/index.js index 3cedf53..315b480 100644 --- a/index.js +++ b/index.js @@ -479,7 +479,8 @@ function rewrite (parent, frames, page, template, includes, named, directives, path, context, generating, callback) { var okay = validator(callback), prefix = '$'; - context = extend(Object.create(template.context), context); + context = extend({}, context); + context.stencil = template.stencil; if (frames[0].attributes) { frames[0].attributes.forEach(function (attributes) { context[prefix + 'attributes'] = attributes; @@ -655,10 +656,8 @@ // Create our template. templates[url] = { url: url, page: page, directives: directives, tags: tags, - context: { - stencil: { - url: url, absolutize: absolutize, normalize: normalize, json: json - } + stencil: { + url: url, absolutize: absolutize, normalize: normalize, json: json } };