-
Notifications
You must be signed in to change notification settings - Fork 82
Templating Guide
Hyde templates are full-featured Django templates. Any template tag or filter that works with Django can be used in Hyde templates. Hyde comes with a few template tags of its own. The major difference between Hyde templates and Django templates are Page Context Variables. Django templates are provided with variables in a dictionary thats usually populated by the controller(usually with model objects). Hyde provides the context dictionary through a variable thats defined as a part of settings. The default template has an empty dictionary for CONTEXT.
If you need to provide site wide variables / settings to the templates, you can define them as key value pairs inside the CONTEXT dictionary in settings.py. Apart from this, Hyde also allows Context variables to be defined as part of every page using the special {% hyde %} template tag. The variables are defined as key value pairs in YAML format.
Note:
If the {% hyde %} template tag is not excluded using blocks it will get rendered in the output. For example, in order to use the {% hyde %} tag in .htaccess you must add {%extends "skeleton/_root.html" %} to inherit from the root template and enclose the content in the all block leaving out the hyde tag.
See example for root template usage
Hyde provides the templates with the following variables.
The current page that is being rendered. All variables specified inside of the {% hyde %} template tag of the page are exposed as attributes of this object. These attributes are available in addition to the following:
- name: The file name of the page.
- page_name: The file name without extension
- url: The relative url of the page prefixed with the SITE_ROOT setting.
- full_url: The complete url for the page prefixed with the SITE_WWW_URL setting.
- listing: Does this page provide a list of the pages in the current node.
- display_in_list: Can this page be displayed in a list. Determines if this page is a content page i.e., something that is not a listing page.
- node: The node to which the page belongs to. See page.node below.
- file: The file object representing the page.
-
prev: Previous page in the current node. Previous is determined by reverse sorting the pages using the
createdattribute.createdattribute must be provided(using page context) for every page, if the attribute is not provided the date defaults to 2000-01-01. - next: Next page in the current node.
- name: The name of the node. The root node gets the name of the site. Other nodes inherit the folder name.
- url: The relative url of the node prefixed with the SITE_ROOT setting.
- full_url: The complete url for the page prefixed with the SITE_WWW_URL setting.
- folder: The folder object that represents the node.
- ancestors: List of all parent nodes including the site root.
- listing_page: The page that provides the listing for this node. Can be used in breadcrumb and site navigation links.
- listing_url: The url for the listing page.
- module: The top most ancestor that is the child of the site root. Can be used in site navigation to highlight tabs or menu items.
- walk: Walks all the child nodes, depth first. Note: The first node returned is itself.
- walk_pages: Walks all the pages that belong to itself and its child nodes, depth first.
This is the root node for the entire site. site supports all the attributes supported by page.node. The following attributes, however, have a special meaning for site:
- name: The name of the site as defined by the SITE_NAME variable in settings.py
- url: The relative url of the site prefixed with the SITE_ROOT setting.
- full_url: The complete url for the site prefixed with the SITE_WWW_URL variable in settings.py
- name
- path
- exists
- last_modified
- path_without_extension
- name_without_extension
- extension: Extension prefixed with a “.”
- kind: Extension without a “.” prefix
- parent: Parent folder
- name
- path
- exists
- depth: Number of ancestors
- isEmpty
- parent: Parent folder
One way to list pages in a particular node(folder in site) is to loop through the given node and its descendants using node.walk and then iterate through the node’s pages.
Content pages are created by you. Non content pages are generated by hyde. Some examples of non-content pages:
- Listing Pages
- Atom Feed
- .htaccess file
The page.display_in_list variable can be used to determine if a given page is content or otherwise.
Site navigation can be implemented in several ways since the entire site hierarchy is available to all pages using the site template variable. The simplest approach is to use the module property in each node. A module is a direct descendant of the site root.
Every node provides access to all its parent nodes through the ancestors property. This can be used to render the breadcrumb trail for a given page.
node.walk_pages returns the node in the descending order sorted by the created attribute. created attribute is provided by a page context variable(defined at the top of the page enclosed by the {%hyde%} template tag). Every page is linked to the previous and next pages in that sort order through the prev and next attributes. Currently these attributes are local to every node. The first page in a node has no previous page and the last page in a node has no next page. These attributes can be used to create a simple Previous, Next context aware navigation.
See example for previous / next
Recent posts can be listed using the recent_posts template tag. The recent_posts template tag takes in 3 optional parameters:
-
var– The name of the context variable that holds the list of recent posts. Default: recent_posts -
count– The desired number of recent posts. Default: 5 -
node– The root node to process the recent posts from. For example, if you have a code, blog and photos as your content folders you may only want the recent posts from the blog node to be listed. This can be used in conjunction with the @NodeInjector@preprocessor. Default: site – The entire content node.
Excerpts can be provided using the {% render_excerpt %} template tag. The listing example above makes good use of this tag. The excerpt template tag takes two parameters: the page to render and number of words to display.
Sometimes its nice to provide a blurb of the most recent article on the home page. The {% render_latest_excerpt %} template tag provides exactly that. Like the excerpt tag, the latest excerpt tag also takes the number of words to display as a parameter, however instead of taking the page as input it takes the path to a folder as input. Also available is the {%latest_excerpt_url%} tag that provides the url for the last rendered latest excerpt.
See example for latest excerpt
Generating an Atom feed is not-very-surprisingly similar to generating a listing page if not simpler.
The nice thing about having a full-featured templating engine to generate a static website is the power of context variables. Apart from the standard Hyde template variables site and page and the page variables declared using the {%hyde%} tag, all the pages get any variables defined in the CONTEXT definition in settings.py. This provides a nice mechanism to have a repository of well named links in settings.py.