{{ Toc( float='right' ) }}

h3. Overview

Tayra templating is a full-featured abstract markup language used to describe
web-documents. It is primarily inspired from
[[ http://www.makotemplates.org/ | mako-templates ]] and
[[ http://haml-lang.com/ | HAML ]] (especially the indentation based
markup definitions). Although it is young and relatively a new kid among
the old-timers, it can be considered as the evolutionary next step for some of
them ( if not all :) ). And probably it is the only templating
language that allows developers to build and distribute their templates
as plugins, not to mention the fact that tayra's implementation itself is
heavily based on plugins. We will finish this short introduction by stating
that, inspite of being a younger sibling to its likes, it is faster than many
of them.

h3. Install tayra

Installing via package management

{{{ Code bash
  # -Z to do unzipped install. The reason for installing it in un-zipped form
  #    is to make use of the command line tool.
  # -U to upgrade install
  easy_install -Z -U tayra
}}}

''Source code''

Download the latest tar.gz from http://pypi.python.org/pypi/tayra

Check out hg repository from [[ http://code.google.com/p/tayra/ | google-code ]]
{{{ Code bash
  hg clone https://code.google.com/p/tayra/
}}}

h3. Command line usage

Make sure that tayra package is installed in your environment (using
easy_install) or available via //PYTHONPATH//. 
''tayra/tyr.py'' script under tayra-package can be used as command
line tool. Either invoke it from its original path, or create a symbolic link
to a bin/ directory.

script-file:    <site-package>/tayra/tyr.py

symbolic link to your binary path, like,

{{{ Code bash

    ln -s <site-package>/tayra/tyr.py $(HOME)/bin/tyr.py
    # or,
    ln -s <site-package>/tayra/tyr.py /usr/bin/tyr.py

}}}

Once `tyr.py` is available as an executable command and `tayra` module 
in your python path, use the command-line tool, like,

{{{ Code bash

  # A corresponding .html file will be generated in the same directory
  tyr.py <template-file>
  # For more help, try
  tyr.py -h

}}}
   
h3. Using it as library, in python

{{{ Code python
    from   tayra  import Renderer

    # `ttlloc` specifies the path to template file, ttlloc is interpreted as
    # relative path or asset specification format
    # `ttlconfig` passes the configuration parameters
    r = Renderer( ttlloc=ttlloc, ttlconfig=ttlconfig )
    html = r( context=context )
    codecs.open( htmlfile, mode='w', encoding=encoding).write( html )

    # To pass template text directly (instead of file-path)
    r = Renderer( ttltext=ttltext, ttlconfig=ttlconfig )
    html = r( context=context )

}}}
  
h3. Development

It is always better to setup the development tree under a virtual environemnt.
To begin with, first checkout the source tree from the latest repository tree
and then use the ''make'' command to create a development environment.

{{{ Code sh
  cd tayra
  make develop
}}}

which,
* sets-up a virtual environment under // tayra-env/ // directory.
* Installs tayra under the virtual environment in development mode,
  [<PRE python ./setup.py develop >]

To start using the tayra package, enter the virtual environment by doing,
``{c} source ./tayra-env/bin/activate ``

''To create an egg packages'',

{{{ Code bash
  make bdist_egg        # For creating binary distribution
  make sdist            # For creating source distribution
}}}

The .egg package will be availabe under dist/ directory

''To test the package'',

{{{ Code bash
  source tayra-env/bin/activate
  make test
}}}

''Finally, Build the egg and upload it into pypi''

{{{ Code bash
  make upload
}}}

-----

{{{ Nested 
# { 'font-size' : 'small', 'color' : 'gray' }
Document edited using Vim <br>
/* vim: set filetype=etx : */
}}}

