basis/html/templates/templates-docs.factor

   1 IN: html.templates
   2 USING: help.markup help.syntax io strings quotations xml.data
   3 continuations urls ;
   4
   5 HELP: template
   6 { $class-description "The class of HTML templates." } ;
   7
   8 HELP: call-template*
   9 { $values { "template" template } }
  10 { $contract "Writes a template to " { $link output-stream } ", possibly using " { $vocab-link "html.forms" } " state."
  11 $nl
  12 "In addition to methods added by other vocabularies, this generic word has methods on the following classes:"
  13 { $list
  14     { { $link string } " - the simplest type of template; simply written to " { $link output-stream } }
  15     { { $link callable } " - a custom quotation, called to yield output" }
  16     { { $link xml } " - written to " { $link output-stream } }
  17     { "an input stream - copied to " { $link output-stream } }
  18 } } ;
  19
  20 HELP: call-template
  21 { $values { "template" template } }
  22 { $description "Writes a template to " { $link output-stream } ", possibly using " { $vocab-link "html.forms" } " state."
  23 $nl
  24 "This word calls " { $link call-template* } ", wrapping it in a " { $link recover } " form which improves error reporting by combining the underlying error with the template object." } ;
  25
  26 HELP: set-title
  27 { $values { "string" string } }
  28 { $description "Sets the title of the current page. This is usually called by child templates, and a master template calls " { $link write-title } "." } ;
  29
  30 HELP: write-title
  31 { $description "Writes the title of the current page, previously set by " { $link set-title } ". This is usually called by a master template after rendering a child template." } ;
  32
  33 HELP: add-style
  34 { $values { "string" string } }
  35 { $description "Adds some CSS markup to the CSS stylesheet of a master template. Usually called by child templates which need to insert CSS style information in the " { $snippet "<head>" } " tag of the resulting HTML page." } ;
  36
  37 HELP: write-style
  38 { $description "Writes a CSS stylesheet assembled from " { $link add-style } " calls by child templates. Usually called by the master template to emit a CSS style in the " { $snippet "<head>" } " tag of the resulting HTML page." } ;
  39
  40 HELP: add-atom-feed
  41 { $values { "title" string } { "url" "a " { $link string } " or " { $link url } } }
  42 { $description "Adds an Atom feed link to the list of feeds in a master template. Usually called by child templates which need to insert an Atom feed link information in the " { $snippet "<head>" } " tag of the resulting HTML page." } ;
  43
  44 HELP: write-atom-feeds
  45 { $description "Writes a list of Atom feed links assembled from " { $link add-atom-feed } " calls by child templates. Usually called by the master template to emit a list of Atom feed links in the " { $snippet "<head>" } " tag of the resulting HTML page." } ;
  46
  47 HELP: nested-template?
  48 { $var-description "Set to a true value if the current call to " { $link call-template } " is nested inside a " { $link with-boilerplate } " and will therefore appear as part of another template. In this case, XML processing instructions and document type declarations should be omitted." } ;
  49
  50 HELP: call-next-template
  51 { $description "Calls the next innermost child template from a master template. This is used to implement the " { $snippet "t:call-next-template" } " tag in the " { $vocab-link "html.templates.chloe" } " templating engine." } ;
  52
  53 HELP: with-boilerplate
  54 { $values { "child" template } { "master" template } }
  55 { $description "Calls the child template, storing its output in a string, then calls the master template. The master template may call " { $link call-next-template } " to insert the output of the child template at any point; both templates may also use the master/child interface words documented in " { $link "html.templates.boilerplate" } "." } ;
  56
  57 HELP: template-convert
  58 { $values { "template" template } { "output" "a pathname string" } }
  59 { $description "Calls the template and writes its output to a file with UTF8 encoding." } ;
  60
  61 ARTICLE: "html.templates.boilerplate" "Boilerplate support"
  62 "The following words define the interface between a templating engine and the " { $vocab-link "furnace.boilerplate" } " vocabulary."
  63 $nl
  64 "The master/child template interface follows a pattern where for each concept there is a word called by the child to store an entity, and another word to write the entity out; this solves the problem where certain HTML tags, such as " { $snippet "<title>" } " and " { $snippet "<link>" } " must appear inside the " { $snippet "<head>" } " tag, even though those tags are usually precisely those that the child template will want to set."
  65 { $subsection set-title }
  66 { $subsection write-title }
  67 { $subsection add-style }
  68 { $subsection write-style }
  69 { $subsection add-atom-feed }
  70 { $subsection write-atom-feeds }
  71 "Processing a master template with a child:"
  72 { $subsection with-boilerplate }
  73 { $subsection call-next-template } ;
  74
  75 ARTICLE: "html.templates" "HTML template interface"
  76 "The " { $vocab-link "html.templates" } " vocabulary implements an abstract interface to HTML templating engines. The " { $vocab-link "html.templates.fhtml" } " and " { $vocab-link "html.templates.chloe" } " vocabularies are two implementations of this."
  77 $nl
  78 "An HTML template is an instance of a mixin:"
  79 { $subsection template }
  80 "HTML templates must also implement a method on a generic word:"
  81 { $subsection call-template* }
  82 "Calling an HTML template:"
  83 { $subsection call-template }
  84 "Usually HTML templates are invoked dynamically by the Furnace web framework and HTTP server. They can also be used in static HTML generation tools:"
  85 { $subsection template-convert }
  86 { $subsection "html.templates.boilerplate" } ;
  87
  88 ABOUT: "html.templates"