[ZPT] CVS: Products/PageTemplates/help - metal-define-macro.stx:1.1 metal-define-slot.stx:1.1 metal-fill-slot.stx:1.1 metal-use-macro.stx:1.1 metal.stx:1.1

[Amos Latteier]

Update of /cvs-repository/Products/PageTemplates/help
In directory cvs.zope.org:/tmp/cvs-serv22636

Added Files:
	metal-define-macro.stx metal-define-slot.stx 
	metal-fill-slot.stx metal-use-macro.stx metal.stx 
Log Message:
first cut at METAL reference

=== Added File Products/PageTemplates/help/metal-define-macro.stx ===
define-macro - Define a macro

  Syntax

    'metal:define-macro' syntax::

      argument ::= Name

  Description

    The 'metal:define-macro' statement defines a macro. The macro is
    named by the statement expression, and is defined as the element
    and its sub-tree.

    In Zope, a macro definition is available as a sub-object of a
    template's 'macros' object. For example, to access a macro named
    'header' in a template named 'master.html', you could use the path
    expression 'master.html/macros/header'.

  Examples

    Simple macro definition::

      <p metal:define-macro="copyright">
        Copyright 2001, <em>Foobar</em> Inc.
      </p>

  See Also

    "metal:use-macro":metal-use-macro.stx"

    "metal:define-slot":metal-define-slot.stx
    


=== Added File Products/PageTemplates/help/metal-define-slot.stx ===
define-slot - Define a macro customization point

  Syntax

    'metal:define-slot' syntax::
   
      argument ::= Name

  Description

    The 'metal:define-slot' statement defines a macro customization
    point or *slot*. When a macro is used, its slots can be replaced,
    in order to customize the macro. Slot definitions provide default
    content for the slot. You will get the default slot contents if
    you decides not to customize the macro when using it.

    The 'metal:define-slot' statement must be used inside a
    'metal:define-macro' statement.

    Slot names must be unique within a macro.

  Examples

    Simple macro with slot::

      <p metal:define-macro="hello">
        Hello <b metal:define-slot="name">World</b>
      </p>
 
    This example defines a macro with one slot named 'name'. When you
    use this macro you can customize the 'b' element by filling the
    'name' slot.

  See Also

    "metal:fill-slot":metal-fill-slot.stx





=== Added File Products/PageTemplates/help/metal-fill-slot.stx ===
fill-slot - Customize a macro

  Syntax

    'metal:fill-slot' syntax::
   
      argument ::= Name

  Description

    The 'metal:fill-slot' statement customizes a macro by replacing a
    *slot* in the macro with the statement element (and its content).

    The 'metal:fill-slot' statement must be used inside a
    'metal:use-macro' statement.

    Slot names must be unique within a macro.

    If the named slot does not exist within the macro, Zope will raise
    an error.

  Examples

   Given this macro::

      <p metal:define-macro="hello">
        Hello <b metal:define-slot="name">World</b>
      </p>
 
    You can fill the 'name' slot like so::

      <p metal:use-macro="container/master.html/macros/hello">
        Hello <b metal:fill-slot="name">Kevin Bacon</b>
      </p>
 
  See Also
    
    "metal:define-slot":metal-define-slot.stx

=== Added File Products/PageTemplates/help/metal-use-macro.stx ===
use-macro - Use a macro

  Syntax

    'metal:use-macro' syntax::
   
      argument ::= expression

  Description

    The 'metal:use-macro' statement replaces the statement element
    with a macro. The statement expression describes a macro
    definition. 

    In Zope the expression will generally be a path expression
    referring to a macro defined in another template. See
    "metal:define-macro" for more information.

    The effect of expanding a macro is to graft a subtree from another
    document (or from elsewhere in the current document) in place of
    the statement element, replacing the existing sub-tree.  Parts of
    the original subtree may remain, grafted onto the new subtree, if
    the macro has *slots*. See
    "metal:define-slot":metal-define-slot.stx for more information. If
    the macro body uses any macros, they are expanded first.

    When a macro is expanded, its 'metal:define-macro' attribute is
    replaced with the 'metal:use-macro' attribute from the statement
    element.  This makes the root of the expanded macro a valid
    'use-macro' statement element.

  Examples

    Basic macro usage::

      <p metal:use-macro="container/other.html/macros/header">
        header macro from defined in other.html template
      </p>

    This example refers to the 'header' macro defined in the
    'other.html' template which is in the same folder as the current
    template. When the macro is expanded, the 'p' element and its
    contents will be replaced by the macro. Note: there will still be
    a 'metal:use-macro' attribute on the replacement element.

  See Also

    "metal:define-macro":metal-define-macro.stx

    "metal:use-slot":metal-use-slot.stx



=== Added File Products/PageTemplates/help/metal.stx ===
METAL Overview

  The *Macro Expansion Template Attribute Language* (METAL) standard
  is a facility for HTML/XML macro preprocessing. It can be used in
  conjunction with or independently of "TAL":tal.stx and
  "TALES":tales.stx.

  Macros provide a way to define a chunk of presentation in one
  template, and share it in others, so that changes to the macro are
  immediately reflected in all of the places that share it.
  Additionally, macros are always fully expanded, even in a template's
  source text, so that the template appears very similar to its final
  rendering.

  METAL Namespace

    The METAL namespace URI and recommended alias are currently
    defined as::

      xmlns:metal="http://xml.zope.org/namespaces/metal"

    Just like the TAL namespace URI, this URI is not attached to a web
    page; it's just a unique identifier.

  METAL Statements 

    METAL defines a number of statements:

    * "metal:define-macro":metal-define-macro.stx - Define a macro.

    * "metal:use-macro":metal-use-macro.stx" - Use a macro.

    * "metal:define-slot":metal-define-slot.stx - Define a macro
    * customization point.

    * "metal:use-slot":metal-use-slot.stx - Customize a macro.

    Although METAL does not define the syntax of expression
    non-terminals, leaving that up to the implementation, a canonical
    expression syntax for use in METAL arguments is described in
    "TALES Specification":tales.stx.

  See Also

    "TAL Overview":tal.stx

    "TALES Overview":tales.stx

    "metal:define-macro":metal-define-macro.stx

    "metal:use-macro":metal-use-macro.stx"

    "metal:define-slot":metal-define-slot.stx

    "metal:use-slot":metal-use-slot.stx