资源说明：Load shpaml (haml-like html alternative) templates in django seamlessly. Should work fine extending normal HTML templates and being extended by them.

[![Build Status](https://travis-ci.org/Rootbuzz/shpaml.png?branch=travis)](https://travis-ci.org/Rootbuzz/shpaml)

## Installation ##

pip install django-shpaml

- OR -

Copy the "shpaml" directory into your python path or run ``python
setup.py install``.


## Use ##

The loader wraps existing django template loaders, so any django template loader
can be used to load shpaml templates.

Shpaml templates *must* use the file extension *.shpaml


### Template Loaders ###
  
I am using filesystem and app_directories for examples here
but you can use any template loader provided by django
  
FOR DJANGO 1.2+

Shapml Loader wraps other loaders (like the caching loader)

    TEMPLATE_LOADERS = (
        ('shpaml.Loader',
            ('django.template.loaders.filesystem.Loader',)
        ),
        'django.template.loaders.filesystem.Loader',
        'django.template.loaders.app_directories.Loader',
    )
    
if you want Caching as well (recommended)...

    TEMPLATE_LOADERS = (
        ('django.template.loaders.cached.Loader',
            ('shpaml.Loader',
                ('django.template.loaders.filesystem.Loader',)
            ),
            'django.template.loaders.filesystem.Loader',
            'django.template.loaders.app_directories.Loader',
        )
    )     
     
### Setup ###
  
Pick one of the template loaders and add it to your TEMPLATE_LOADERS
setting in the settings.py file like so:
      
    TEMPLATE_LOADERS = (
        # Using the django 1.2+ method in this example
        'shpaml_loader.filesystem',
		    ...
    )
    
The shpaml loader **must be first** or else the django loaders will take 
over.

In django template caching can yield some 
pretty nice **performance gains**, but it is inconvenient for development 
(because you have to keep clearing the cache).

Here is my reccommended approach:

    TEMPLATE_LOADERS = (
        ('shpaml.Loader',
            ('django.template.loaders.filesystem.Loader',)
        ),
        'django.template.loaders.filesystem.Loader',
        'django.template.loaders.app_directories.Loader',
    )  
    
    if not DEBUG:
        TEMPLATE_LOADERS = (
            ('django.template.loaders.cached.Loader', TEMPLATE_LOADERS),
        )
     
     
### How Templates Are Located ###
  	
There is a shpaml template loader for each built-in django template
loader. The templates are located using the django template loader
but pre-processed to convert the shpaml markup to HTML before being
returned.

Templates are determined to be shpaml by file extension, so they have to
be *.shpaml files or else they will not be processed.


## Shpaml ##

Here is a quick and dirty shpaml reference...

### Use indentation for block tags

The goal of this tutorial is to take you through one SHPAML concept at a time. 
At each step you can edit the SHPAML to create HTML. The goal is to learn by 
reading and writing at the same time.

The most important concept in SHPAML is that you can use indentation to indicate
where HTML blocks should end with a close tag. Try adding a third item to the 
list to see it in action.

We will mostly use two spaces for indentation in this tutorial, but you can use
more if you like.

    ul
      li
        This it the first item.
      li
        This is the second item.
    
    div
        The number of spaces that you indent
        gets preserved.
        
#### Output

    

      

        This it the first item.
      
      

        This is the second item.
      
    
    
    

        The number of spaces that you indent
        gets preserved.
    


### Use pipes for inline content

For HTML one-liners you can use the pipe character followed by a space to 
separate markup from content.

Try adding an item to this list.

    ol
      li | apple
      li | banana
      li | orange
      
#### Output

    

      
apple
      
banana
      
orange
    
      
### Use pipes for indented content 

When authoring SHPAML, you use indentation and certain punctuation to identify 
structure. This leads to terseness at one level, but what if you want your 
content to include indentation and structure?

The solution is to prefix content lines with the pipe character ('|') followed 
by a space. Try removing the second pipe to see the problem, and then reinsert 
it to see the solution.

    pre
      | Without pipes to show a block of content,
      |  SHPAML would be confused
      |    by this strangely indented
      |       text, or by me using | and
      |          < symbols.
    
    pre
      || You can also dedent text
      ||   with double pipes
    
    p
      For most text, advanced users can omit the
      pipes for maximum terseness, and SHPAML will
      just do the right thing.  It detects that lines
      have no indentation beneath them and treats them
      as content.
      
#### Output

    
      Without pipes to show a block of content,
       SHPAML would be confused
         by this strangely indented
            text, or by me using | and
               < symbols.
    
    
    
    You can also dedent text
      with double pipes
    
    
    

      For most text, advanced users can omit the
      pipes for maximum terseness, and SHPAML will
      just do the right thing.  It detects that lines
      have no indentation beneath them and treats them
      as content.
    
    
### Use HTML as needed 

SHPAML does not force you to abandon HTML.

Most well-formatted HTML passes through the preprocessor untouched. This can 
be helpful when dealing with legacy code or inline tags.

    
      
    
    
    body
      

        

          
close tags
          
lots of angle brackets
        
      
    
      div class="mixed"
        p
          Use indentation to denote
          structure!

#### Output

    
      
    
    
    
      

        

          
close tags
          
lots of angle brackets
        
      
    
      

        

          Use indentation to denote
          structure!
        
      
    

### Use dot for class=... 

You can abbreviate 'div class="free_text"' as "div.free_text" as shown in the 
example.

Although it reduces typing for the HTML author, the real goal here is to make 
the HTML look more like CSS (for your designer) and jQuery too.

Try modifying the ul tag to emulate the same syntax as the div.

    div.free_text
      This is some text.
    
    ul class="list_of_names"
      li | Alice
      li | Bob
      li | Cindy
    
    div.class1.class2
      You can have multiple classes.
      
#### Output

    

      This is some text.
    
    
    

      
Alice
      
Bob
      
Cindy
    
    
    

      You can have multiple classes.
    
    
### Use pound for id=...

You can abbreviate 'p class="free_text" id="greeting"' as "p.free_text#greeting" 
as shown in the example.

Try adding an id to the ul tag.

    p.free_text#greeting
      Hello World!
    
    ul.list_of_names
      li | Alice
      li | Bob
      li | Cindy
      
#### Output

    

      Hello World!
    
    
    

      
Alice
      
Bob
      
Cindy
    
    
### Div can be implied 

Any tag starting with "." or "#" is implied to be a div tag. The div shortcut is a 
feature borrowed from haml, as divs are used very commonly.

Try enclosing "Goodbye" inside a div tag using the implied-div syntax.

    .free_text.salutation#hello
      Hello World!
    
    #how_are_you.free_text.salutation
     How are you?
    
    Goodbye.
    
#### Output

    

      Hello World!
    
    
    

     How are you?
    
    
    Goodbye.
    
### Comments

You can use the ::comment directive to include comments in your shpaml. 
Comments do not get written to the output.

    ::comment
      This text is for your eyes only.
    .main
      This text passes through.

#### Output


  This text passes through.


### Use > for self-closing tags 

You can use '>' syntax for self-closing tags like "br" and "hr," or you can 
just use explicit HTML.

    > br
    

    

    
    > input.widget type="text"
    
#### Output

    

    

    

    
    
    
### Empty Tags

Sometimes you want an empty tag with no whitespace. Use the double pipe (||)

    script type="text/javascript" ||
    
#### Output
    
    
    
### Disabling Shpaml within a block (inline javascript or css)

Sometimes you want to disable shpaml so you can inline some js or css in a 
page. You can use the VERBATIM tag to tell shpaml not to process the contents
of a tag.

VERBATIM must be all caps, and it must be the last thing in the line

    script VERBATIM type="text/javascript"
        // this is no good...
        $("div")
            .hide()
            .fadeIn(function() {
                // uh oh
            });
            

    script type="text/javascript" VERBATIM
        // this is the way to do it :)
        $("div")
            .hide()
            .fadeIn(function() {
                // uh oh
            });
            
#### Output

    
            

    
    
### Django Template Tags

Lines starting with a percent sign (%) will be converted to django template 
tags.

if the template tag as contents an "end" tag will be added, otherwise it will 
be treated as having no end tag (double pipe syntax and PASS are supported as 
well)

you can also user the pipe percent (|%) operator for non-closing template tags
similarly to the pipe operator...

    % block content
        this will get an "endblock" tag because it has contents
        
        form action="."
            the csrf token tag doesn't get a closing tag because it 
            has no contents...
            % csrf_token
            
            {{ form.as_p }}
            
            button type="reset" | Cancel
            button type="submit" | Save
            
     This is an empty block:
     footer
        © Me
        span.current-time |% now "Y"
        
        % block more_footer ||
            
#### Output
    
    {% block content %}
        this will get an "endblock" tag because it has contents
        
        

            the csrf token tag doesn't get a closing tag because it 
            has no contents...
            {% csrf_token %}
            
            {{ form.as_p }}
            
            Cancel
            Save
        
    {% endblock %}
    
    This is an empty block:
    
    
### Django Variable Insertion

You can insert django variables using the equals sign (=). You can
also use the pipe equals operator similarly to the pipe operator.
    
    .profile-info
        a href="{{ user.get_absolute_url }}" |= user.get_full_name
        p.user-name
            strong | username:
            = user.username
    
#### Output

    

        {{ user.get_full_name }}
        

            username:
            {{ user.username }}
        
    
        
### Other shortcuts 

You can leave quotes off attribute values when the name and value are single 
words.

You can also have multiple inline tags on the same line.

    > input type=text name=department value="Computer Science"
    
    .greeting > strong > p | Hello

#### Output

    

    
Hello
    

联系我们：verysource_com

CopyRight © 2008-2022 verySource.Com All Rights reserved.　京ICP备17048824号-1　京公网安备：11010502034788