.. Pytemplates documentation master file, created by
   sphinx-quickstart on Wed Dec 18 22:36:32 2013.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Pytemplates Documentation
=======================================
Pytemplates is a lightweight HTML template engine written in Python.

Features
--------
- Pure Python Syntax
- Template Inheritance
- Blocks
- Macros
- Context
- Comes with a Django plugin


Installation Instructions
-------------------------
To install pytemplates, run ``pip install pytemplates``.

Django Plugin
+++++++++++++
To use the Django plugin, import the *render_to_response* function included in the *django_plugin* module and use it in your views.


Basic Syntax
------------
Elements
++++++++
An element must be placed in a list or a tuple. The first entry in the list or tuple must be the tag definition, and is placed in a set. The second entry is the content of that element. ::

    [{'div'}, "I am a div element."]

Tags
++++
A tag is the first entry in an element. Attributes are passed in as tuples, or written in short form. Content is the second entry in the element. ::

    # Long form
    # Putting your element in a tuple will create a html element with no closing tag
    ({'input', ('value', 'This is a disabled input field'), ('disabled',)},)

    # Output: <input value="This is a disabled input field" disabled>

    # Putting your element in a list will create an html element with a closing tag
    [{'ul', ('class', 'unstyled'), ('id', 'my_list')},
        [{'li'}, 'One'],
        [{'li'}, 'Two'],
    ]

    # Output: <ul class="unstyled" id="my_list"><li>One</li><li>Two</li></ul>

    # Short form
    ({'input[value="This is a disabled input field"]:disabled'},)

    [{'ul#my_list.unstyled'},
        [{'li'}, 'One'],
        [{'li'}, 'Two'],
    ]

Template
++++++++
Your template is a class that extends the Template class. ::

    from pytemplates.pytemplates import Template
    class MyTemplate(Template):
        def template(self, *args):
            # Your template code goes here and is returned by this method
            template = [{'div'}, "Hello"]
            return template

Context
+++++++
Context is passed in from your view when you call your render function. It is also accessible from the instance ::

    # In your views.py
    class MyView(TemplateView):
        def get(self, request, *args):
            context = {'test': 'Hello World'}
            return render_to_response(request, 'my_template', context)

    #### In your template file:
    class MyTemplate(Template):
        def template(self, *args):
            c = self.context
            template = [{'div'}, c['test']]
            return template

Blocks
++++++
A block is defined as an instance method inside your template, with the **@block** decorator. Blocks are passed to your template function and are accessible from the instance. ::

    from pytemplates.pytemplates import Template, block
    class MyTemplate(Template):
        @block
        def my_block(self, *args):
            return [{'span'}, "It works!"]

        def template(self, *args):
            b = self.blocks
            # You can access all your blocks from variable b
            template = [{'div'}, b.my_block]
            return template

    class MyOtherTemplate(MyTemplate):
        @block
        def my_block(self, *args):
            # You can also access the context in your blocks
            c = self.context
            return [{'div'}, c['test']]

Macros
++++++
A macro is any function that returns valid template code. You must use the **@macro** decorator to let your template know about your macro.

You can also group many macros as static methods inside a class that is decorated with the **@macro** decorator as well. ::

    from pytemplates.pytemplates import Template, macro
    class MyTemplate(Template):
        @macro
        def list_maker(n):
            out = [{'ul'}] + [
                [{'li'}, i] for i in range(n)
            ]
            return out

        def template(self, c, b, m):
            template = [{'div'}, m.list_maker(10)]
            return template

Includes
++++++++
You can include any external file with an include statement. This will render that file wherever you put the include statement. This can be used to include embedded javascript code, css code, or raw html code, or any other text you would like to include in your templates. ::

    from pytemplates.pytemplates import Template
    class MyTemplate(Template):
        def template(self, c, b, m):
            template = [{'div'}, self.include('some_external_file.html')]
            return template


Rendering the Template
++++++++++++++++++++++
To render your template, create an instance of the template and call its render() function. ::

    template = MyTemplate()

    # This will output the rendered HTML template
    template.render()

    # You can pass the context to the render function as a dictionary:
    template.render({'some_variable': 1234})


Full Example
++++++++++++
::

    ### In your views.py
    from pytemplates.django_plugin import render_to_response
    from django.views.generic.base import TemplateView

    class MyView(TemplateView):
        def get(self, request, *args):
            context_test = {'test': '<strong>Hello World</strong>'}
            return render_to_response(request, 'templates.test_template', context_test)


    ### In your urls.py
    from myapp.views import MyView
    urlpatterns = patterns('',
        url(r'^$', MyView.as_view(), name='home'),
    )


    ### In templates/test_template.py
    from pytemplates.pytemplates import Template
    from pytemplates.pytemplates import block
    from pytemplates.pytemplates import macro
    from pytemplates.pytemplates import render


    # You can define macros inside or outside the template
    # If you define them outside, just put them in a list
    # called "extra_macros" in your class.
    @macro
    def select(name, options=[], value=None):
        # Render a select field
        out = [_.select()] + [
            [_.option('checked' if o[0] == value else '', value=o[0]),
            o[1]] for o in options]
        return out


    # You can also define a group of macros under a class (e.g. to group related macros)
    @macro
    class group_of_macros:
        @staticmethod
        def macro1():
            return [{'div'}, "macro_1"]
        @staticmethod
        def macro2():
            return [{'div'}, "macro_2"]
        @staticmethod
        def macro3():
            return [{'div'}, "macro_3"]


    # This is the actual template
    class MyTemplate(Template):
        extra_macros = [group_of_macros, select]

        # Blocks can be overridden in any class extending Template
        @block
        def title(*args):
            content = "It works!"
            return content

        def template(self, c, b, m):
            # c, b, and m are variables that contain the context,
            # blocks, and macros available respectively. They are also
            # accessible from self.context, self.macros, and self.blocks
            template = \
                [{'html'},
                    [{'head'},
                        [{'title'}, b.title],
                        ({'link',
                            ('rel', "stylesheet"),
                            ('href', "//netdna.bootstrapcdn.com/bootstrap/3.0.0/css/bootstrap.min.css")},),
                        ({'link',
                            ('rel', "stylesheet"),
                            ('href', "http://getbootstrap.com/examples/starter-template/starter-template.css")},),
                        [{'script',
                            ('src', "//netdna.bootstrapcdn.com/bootstrap/3.0.0/js/bootstrap.min.js")},],
                    ],
                    [{'body'},
                        [{'div.navbar.navbar-inverse.navbar-fixed-top'},
                            [{'div.container'},
                                [{'div.navbar-header'},
                                    [{'a.navbar-brand', ('href', '#')}, "PyTemplates Test"],
                                ],
                            ],
                        ],
                        [{'div.container'},
                            [{'div.starter-template'},
                                [{'button.btn:disabled'}, "I'm a disabled button!"],
                                [{'input.form-control', ('disabled',), ('value', "I'm a disabled input field.")}],
                                [{'h1'}, "Hello World!"],
                                [{'p'},
                                    ('safe', """This is just an example template using <strong>PyTemplates</strong>,
                                        <strong>Bootstrap</strong>, and <strong>Django</strong>.""")],

                                # Here's an example of an if statement that will test context variable 'test':
                                ('test' in c) * [{'p'},('safe',
                                    "You passed {0} as context variable 'test'".format(
                                        c['test']))] or [{'p'}, "You did not pass 'test' in the context"],
                            ],
                            m.group_of_macros.macro1(),
                            m.group_of_macros.macro2(),
                            m.group_of_macros.macro3(),
                        ],
                    ]
                ]
            return template


.. toctree::
   :maxdepth: 2