Context processors¶

Almoststatic introduces several commands to Jinja2 through a mechanism known as context processors, (in terms of Jinja and Flask). These commands can be utilized in template files and within YAML contents.

The available commands are:

enum_list¶

This command adds the Python enumerate function to templates, useful for obtaining a unique ID for each item in a list within a template.

{% for i,item in enum_list(widget.tabs) -%}
<li id="{{widget.id}}{{i}}">{{ item.text|safe }}
</li>
{% endfor -%}

len_list¶

This command adds the Python len function to templates, allowing to get the length of a list or a dictionary.

get_markdown¶

Transform a Markdown text into html, usually you don’t need to call it because is automatic called at each widget.text rendering.

{% set myvar = "# this is a title" %}
{{ get_markdown(myvar) }}

get_media¶

get_media is a very important command.

Flask by default search media files into folder ./static using the command {{ url_for('static', filename='...') }}.

Almoststatic, to encapsulate all contents within the content folder replace the url_for command with get_media and this helps to configure media destination folder when writing static pages.

replace:

<link rel="stylesheet" href="{{url_for('static', filename='css/main.css')}}">

with:

<link rel="stylesheet" href="{{get_media('css/main.css')}}">

And put files into content/media directory.

But if you really need to use url_for command, you can write a special Flask app dedicated to write static files, see samples.

But there is more. get_media is recognized even into contents on yaml files:

- type: jumbotron
  id: jumbo1
  style: '
    background-image: url({{get_media("gradient1.jpg")}});
    background-size: cover contain;
    min-width: 100%;
    height: 16em;
    color: white;
    '

in this case we add some style to the widget and within the css we call an image from media folder.

get_url¶

Internal url’s of our site, can change from Flask app to static site, for this reason we have a function that build the url according to environment. The url is composed by a prefix, the url that is the same of path and name of pages and a suffix.

Internal url’s paths by default are all relatives, so if you write a static site, it can be navigated also from filesystem. For this reason prefix usually is an empty string, but if you need, you can force a prefix for the static site.

So:

<a href="{{get_url('index')}}">Index</a>

return index on flask and can return something like /mysite/index.html on static site.

Note that url’s passed to get_url don’t have leading or trailing dashes.

Note

There is an incompatibility between markdown links and Jinja2 fields, so we can’t use single or double quote within links in markdown texts, the shortcut [Index]({{get_url('index')}}) is translated in a wrong way. For this reason we added to Almoststatic the variable quote_escape to replace quotes at runtime, and we can write [Index]({{get_url(^^index^^)}}) to get the right result. The sequence ^^ usually is not used into texts, but if you need it, you can change the default to a sequence of your choice.

embed¶

Do the same thing that can be done with Embedding and including. Can be useful to embed contents for not recognized areas of page (see Writing pages):

<aside>
  {% if page.aside %}
  {{embed(page.aside)|safe}}
  {% else %}
  {{include('include/aside.yaml')|safe}}
  {% endif %}
</aside>

In this case if page contain a list called aside, the content is rendered in the <aside></aside> section of page.

particle¶

Similar to embed recognizes widgets within a section of a page called by default particles and include them into text searching the id.

See Embedding and including.

include¶

Like embed let embedding contents at the template level, include let including files at template level (and even within page texts.)

As you can see in the previous sample, the page.aside list is included in page, but if it is not present, the file include/aside.yaml is included.

query_blog¶

This is the heart of blog capabilities of Almoststatic. It return three values. a list of found pages, the list of pages belonging to the given categories and the list of pages with given tags.

{%- set query = query_blog(categories=page.blog.categories, tags=page.blog.tags) -%}
{%- set pages = query[2] -%}
{%- if len_list(pages) -%}
  {%-for k in pages -%}
    {{ k }} ({{ len_list(pages[k]) }}) <br>
    {%- for i in pages[k] %}
      <a href="{{ get_url(i.pagename) }}">{{ i.title }}</a>
    {%- endfor -%}
    <br>
  {%- endfor -%}
{%- endif -%}

In this case we list all pages with the same tags of the current page

pages_id¶

This is an utility function that can be used with some javascript on the frontend. Almoststatic always save a file called site_meta.json on the root of media folder.

It contain all metadata info for all pages, each page contain a unique ID, so with:

{%- set query = query_blog(categories=page.blog.categories, tags=page.blog.tags) -%}
{%- set pages = pages_id(query[0]) -%}

You get the list of pages to pass to your script.

Discontinued and deprecated¶

The following processors can be easily be substituted with standard Jinja2 commands, so they can be considered deprecated.

iif¶

Inline if a shortcode for if/else into templates. Syntax is iif(condition, if_true, if_false="").

Instead to write:

{{'active' if page.pagename == item.url else ""}}
{# or #}
{{'active' if page.pagename == item.url else "not-active"}}

Simply write:

{{iif(page.pagename == item.url,'active')}}
{# or #}
{{iif(page.pagename == item.url,'active','not-active')}}

if_in¶

Shortcode to check for list inclusion. Syntax is if_in(value, iterable, if_not="").

Try:

{{if_in('carousel-caption-bg', widget.tags)}}
{# or #}
{{if_in('carousel-caption-bg', widget.tags, 'my-class')}}

This is useful to add classes on arbitrary positions into widgets.