From be1afcd114d148dbfedb7a3fc068af64a83b5991 Mon Sep 17 00:00:00 2001 From: Gibheer Date: Mon, 26 Nov 2012 21:45:33 +0100 Subject: refreshed documentation --- doc/Zero/Renderer.html | 463 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 325 insertions(+), 138 deletions(-) (limited to 'doc/Zero/Renderer.html') diff --git a/doc/Zero/Renderer.html b/doc/Zero/Renderer.html index 4ce1cee..0ff7fb7 100644 --- a/doc/Zero/Renderer.html +++ b/doc/Zero/Renderer.html @@ -102,22 +102,22 @@

Overview

-

This class helps with rendering of content.

+

the base renderer for getting render containers

-

The purpose of this class is to render templates. All variables pushed into -the renderer should be already processed, so that the raw data can be used.

+

This class handles templates and render coontainers, which can be used for +the actual rendering.

-

The workflow of this class is like the following.

-
  • -

    setup the type mapping

    -
  • -

    create a new instance of the class to prepare rendering

    -
  • -

    call #render to process the template

    -
+

To use this renderer you have to give it a template path and optionally a +map of shorthand type descriptions to fully types. This will then be used +to extend the internal map of templates to possible formats in a way, that +you will be able to answer xhtml and html requests with the same template.

-

The call to #render will return the String representation of the template -with all data given.

+

When the object is initialized and you are sure, everything is loaded, call +#read_template_path! and the template tree will be built. Without this +step, you will probably don't get any output.

+ +

After the setup, the renderer can be used to build render containers, which +then can be used to actually render something.

@@ -129,21 +129,13 @@ with all data given.

- - - - -

- Class Method Summary - (collapse) -

- - + + + +

Instance Method Summary @@ -224,7 +235,7 @@ with all data given.

  • - - (Renderer) initialize(path, context, accept_types) + - (Renderer) initialize(template_path, type_map = {}) @@ -241,7 +252,7 @@ with all data given.

    -

    take the path and render the template within the context.

    +

    initializes a new Renderer.
    • @@ -250,7 +261,7 @@ with all data given.

  • - - (String) render + - (Self) read_template_path! @@ -265,7 +276,31 @@ with all data given.

    -

    render the template within the context.

    +

    load the template tree.

    +
     + +
    • + + +
  • + + + - (String) render(name, type, context) + + + + + + + + + + + + + +
    +

    render a template.
    • @@ -280,7 +315,7 @@ with all data given.

    - - (Renderer) initialize(path, context, accept_types) + - (Renderer) initialize(template_path, type_map = {}) @@ -289,18 +324,46 @@ with all data given.

    -

    take the path and render the template within the context

    +

    initializes a new Renderer

    + +

    This method takes a path to the base template directory and a type map. +This type map is used to extend the possible renderings for different +types, which the clients sends.

    -

    Parameters:

    + +
    +

    Examples:

    + + +

    +

    create a simple renderer

    +

    + + 
    Renderer.new('app/templates')
+
    + + +

    +

    create a renderer with a small map

    +

    + + 
    Renderer.new('app', {
+  'html' => ['text/html', 'application/html+xml'],
+  'json' => ['application/json', 'application/aweomse+json']
+})
+
    + +
    +

    Parameters:

    • - path + template_path (String) @@ -309,38 +372,29 @@ with all data given.

      —
      -

      the relative path to the template

      +

      a string to templates

    • - context + type_map - (Object) + (Hash) + + (defaults to: {}) —
      -

      the object to process on

      +

      a map of simple types to complex ones

      • -
    • - - accept_types - - - - - - -
      • -
    @@ -350,19 +404,17 @@ with all data given.

     
 
-49
-50
-51
-52
-53
    +36 +37 +38 +39 - 
    # File 'lib/zero/renderer.rb', line 49
+      
    # File 'lib/zero/renderer.rb', line 36
 
-def initialize(path, context, accept_types)
-  accept_types ||= Request::Accept.new('text/html')
-  @path    = find_template(path, accept_types)
-  @context = context
+def initialize(template_path, type_map = {})
+  @template_path = template_path + '/'
+  @type_map = type_map
 end
 
    
     
@@ -372,15 +424,15 @@ with all data given.
    - -
    -

    Class Method Details

    - +
    +

    Instance Attribute Details

    + +
    -

    +

    - + (Object) template_path=(path) + - (String) template_path (readonly) @@ -389,19 +441,18 @@ with all data given.

    -

    set a base path for template search

    +

    get the path to the templates

    -

    Parameters:

    -
      + +

      Returns:

      +
      • - path - (String) @@ -409,29 +460,28 @@ with all data given.

        —
        -

        the path to the template base dir

        +

        the base template path

      -
    @@ -439,10 +489,12 @@ with all data given.

     
 
-20
-21
-22
    +46 +47 +48     		- 
    # File 'lib/zero/renderer.rb', line 20
+      
    # File 'lib/zero/renderer.rb', line 46
 
-def template_path=(path)
-  @@path = path + '/'
+def template_path
+  @template_path
 end
    + +
    -

    +

    - + (Hash) type_map + - (Hash) templates (readonly) @@ -450,8 +502,12 @@ with all data given.

    - -

    returns the type map

    +

    + This method is part of a private API. + You should avoid using this method if possible, as it may be removed or be changed in the future. +

    + +

    get the tree of templates

    @@ -470,7 +526,7 @@ with all data given.

    —
    -

    the mapping for types

    +

    the template tree

    @@ -483,15 +539,15 @@ with all data given.

     
 
-40
-41
-42
    +50 +51 +52 - 
    # File 'lib/zero/renderer.rb', line 40
+      
    # File 'lib/zero/renderer.rb', line 50
 
-def type_map
-  @@map ||= {}
+def templates
+  @templates
 end
 
    
     
@@ -499,10 +555,12 @@ with all data given.
    + +
    -

    +

    - + (Object) type_map=(map) + - (Hash) type_map (readonly) @@ -511,32 +569,18 @@ with all data given.

    -

    save a mapping hash for the type

    - -

    With that it is possible to map long and complex contant types to simpler -representations. These get then used in the finding process for the best -fitting template.

    +

    returns the hash of type conversions

    -
    -

    Examples:

    - - - 
    Zero::Renderer.map = {'text/html' => 'html'}
-
    - -
    -

    Parameters:

    -
      +

      Returns:

      +
      • - map - (Hash) @@ -544,29 +588,28 @@ fitting template.

        —
        -

        maps the content type to a simple representation

        +

        type conversion

      -
    @@ -576,14 +619,15 @@ fitting template.

    +

    Instance Method Details

    -

    +

    - - (String) render + - (Self) read_template_path! @@ -592,7 +636,11 @@ fitting template.

    -

    render the template within the context

    +

    load the template tree

    + +

    This method gets all templates in the `template_path` and builds an +internal tree structure, where templates and types direct the request to +the wanted template.

    @@ -605,13 +653,13 @@ fitting template.

  • - (String) + (Self) —
    -

    the rendered template

    +

    returns the object

    • @@ -624,15 +672,154 @@ fitting template.

     
 
-57
 58
-59
    +59 +60 +61 +62 +63 +64 +65 +66 +67 +68 +69 +70 +71 +72 + +
    + +
     
 
-34
-35
-36
    +43 +44 +45     		- 
    # File 'lib/zero/renderer.rb', line 34
+      
    # File 'lib/zero/renderer.rb', line 43
 
-def type_map=(map)
-  @@map = map
+def type_map
+  @type_map
 end
    		+ 
    # File 'lib/zero/renderer.rb', line 58
+
+def read_template_path!
+  # TODO clean up later
+  @templates = {}
+  search_files.each do |file|
+    parts = file.gsub(/#{template_path}/, '').split('.')
+    @templates[parts[0]] ||= {}
+    if parts.count > 2 then
+      read_type(parts[1]).each do |type|
+        @templates[parts[0]][type] = file
+      end
+    else
+      @templates[parts[0]][''] = file
+    end
+  end
+end
+
    +
    +
    + +
    +

    + + - (String) render(name, type, context) + + + + + +

    +
    + +

    render a template

    + +

    This method will render the given template, based on the type in the given +context.

    + + +
    +
    +
    +

    Parameters:

    +
      + +
    • + + name + + + (String) + + + + — +
      +

      the name of the template

      +
      + +
      • + +
    • + + type + + + (Array) + + + + — +
      +

      a list of accept types used to find the template

      +
      + +
      • + +
    • + + context + + + (Object) + + + + — +
      +

      the context in which to evaluate the template

      +
      + +
      • + +
    + +

    Returns:

    +
      + +
    • + + + (String) + + + + — +
      +

      the rendered content

      +
      + +
      • + +
    + +
    + + @@ -645,7 +832,7 @@ fitting template.

    -- cgit v1.2.3-70-g09d2
    + 
    +
+
+82
+83
+84
    		 - 
    # File 'lib/zero/renderer.rb', line 57
+      
    # File 'lib/zero/renderer.rb', line 82
 
-def render
-  Tilt.new(@path).render(@context)
+def render(name, type, context)
+  template(name, type).render(context)
 end