diff options
Diffstat (limited to 'specs/~inheritance.yml')
| -rw-r--r-- | specs/~inheritance.yml | 50 |
1 files changed, 38 insertions, 12 deletions
diff --git a/specs/~inheritance.yml b/specs/~inheritance.yml index 8881ee5..46eb625 100644 --- a/specs/~inheritance.yml +++ b/specs/~inheritance.yml @@ -1,16 +1,42 @@ overview: | - Parent tags are used to expand an external template into the current template, - with optional parameters delimited by block tags. - - These tags' content MUST be a non-whitespace character sequence NOT containing - the current closing delimiter; each Parent tag MUST be followed by an End - Section tag with the same content within the matching parent tag. - - Block tags are used inside of parent tags to assign data onto the context - stack prior to rendering the parent template. Outside of parent tags, block - tags are used to indicate where value set in the parent tag should be placed. - If no value is set then the content in between the block tags, if any, is - rendered. + Like partials, Parent tags are used to expand an external template into the + current template. Contrary to partials, Parent tags may contain optional + arguments delimited by block tags. For this reason, Parent tags may also be + referred to as Parametric Partials. + + The Parent tags' content MUST be a non-whitespace character sequence NOT + containing the current closing delimiter; each Parent tag MUST be followed by + an End Section tag with the same content within the matching Parent tag. + + This tag's content names the Parent template to inject. Set Delimiter tags + MUST NOT affect the parsing of a Parent template. The Parent MUST be rendered + against the context stack local to the tag. If the named Parent cannot be + found, the empty string SHOULD be used instead, as in interpolations. + + Parent tags SHOULD be treated as standalone when appropriate. If this tag is + used standalone, any whitespace preceding the tag should be treated as + indentation, and prepended to each line of the Parent before rendering. + + The Block tags' content MUST be a non-whitespace character sequence NOT + containing the current closing delimiter. Each Block tag MUST be followed by + an End Section tag with the same content within the matching Block tag. This + tag's content determines the parameter or argument name. + + Block tags may appear both inside and outside of Parent tags. In both cases, + they specify a position within the template that can be overridden; it is a + parameter of the containing template. The template text between the Block tag + and its matching End Section tag defines the default content to render when + the parameter is not overridden from outside. + + In addition, when used inside of a Parent tag, the template text between a + Block tag and its matching End Section tag defines content that replaces the + default defined in the Parent template. This content is the argument passed + to the Parent template. + + The practice of injecting an external template using a Parent tag is referred + to as inheritance. If the Parent tag includes a Block tag that overrides a + parameter of the Parent template, this may also be referred to as + substitution. tests: - name: Default desc: Default content should be rendered if the block isn't overridden |