Hello from a VirtualNode.

See the Handlers page for more details.

This is a special message for RSS readers only.

Soju is an extension mechanism that lets you call custom Python code from substition parameters.

To run user-defined Python code and have its output appear on a page, you need to do two things:

• Define a Soju function
• Reference a Soju function

This page will show you how to do both.

Define a Soju Function

To define a Soju function, you need to add your own user-defined Python code into the lib/soju.py file within your project.

This is what the lib/soju.py file looks like when Uriel first creates a new project:

##############################################################################
# soju.py                                                                    #
##############################################################################

# The following symbols are imported using magic:
#
# import uriel
# from uriel import SojuError
# from uriel import log
# from uriel import escape

# The following variables are available to pass to functions:
#
# page
# node
# project_root
# use_canonical_url

# {{soju:node_title(node)}}
def node_title(node):
    return escape(node.get_title())

You can add your own functions to this file, and reference them in nodes and templates, so the output of these functions shows up in pages on your web site.

The uriel program itself is imported into lib/soju.py as a module, along with the log() and escape() functions and the SojuError exception. See the Uriel API reference for details.

Four variables are present when your functions are called. You can write your functions to accept and make use of these variables:

We won't discuss page further here. See the Uriel source code if you're curious.

The node variable is extremely useful. This gives you access to dozens of methods that can provide information about the current node, find other nodes on the site and get their Node instances, etc.

The project_root variable contains the filesystem path to your project directory.

The use_canonical_url variable is a boolean that indicates the mode that is being used to render the page when your function is called. Normal HTML pages are rendered with use_canonical_url set to False. But if you are generating an RSS feed, then your function can be called with use_canonical_url set to True during that rendering step. If you are generating your own links to other nodes inside of your Soju function, you'll want to accept this as a function argument, and conditionalize your code to work in both conditions.

Reference a Soju Function

To reference your custom Soju function, you will need to call it from a substition parameter in a node or a template.

For example, the default lib/soju.py that Uriel generates when it creates a new project contains the following function:

# {{soju:node_title(node)}}
def node_title(node):
    return escape(node.get_title())

We can reference that function by including the {{soju:node_title(node)}} substitution parameter on the node that creates this page. When we do that, here is the result of that Soju function call to the node_title(node) function:

Soju

The function evaluated to the HTML escaped title of the current node, and the string was included in the rendered page.

Example Soju Function

Let's take a look at a non-trivial example function. Here is the source code for the example() function in the lib/soju.py file for this documentation site:

# {{soju:example(page, node, project_root, use_canonical_url)}}
def example(page, node, project_root, use_canonical_url):
    """
    Example Soju function, demonstrating several things in one place.

    Accepts a page, node, project_root, and use_canonical_url.

    Returns an example string to use in the Soju documentation.

    """

    # log a message when the site builds
    log("the example() function is running now")

    # create a list of strings that we will combine and return
    lines = []

    # show the uriel version (which is referenced from the uriel module,
    # along with the string values of each argument passed to this function
    lines.append("Hello from the <b>example()</b> function!")
    lines.append("")
    lines.append("Generated by uriel version " + escape(uriel.VERSION))
    lines.append("")
    lines.append("page:              " + escape(str(page)))
    lines.append("node:              " + escape(str(node)))
    lines.append("project_root:      " + escape(project_root))
    lines.append("use_canonical_url: " + escape(str(use_canonical_url)))
    lines.append("")

    # find the node for the Uriel API documentation index
    # (the nodes/uriel/index file)
    uriel_api_doc_index_node = node.find_node_by_path("uriel/index")

    # show a link to the node
    lines.append(uriel_api_doc_index_node.get_link())

    # go through each child node under the Uriel API documentation index,
    # sorted by (title + node path). Title is not always guaranteed to
    # be unique, so the unique node path will act as a tie breaker in.
    # case any nodes have the same title.
    for child_node in sorted(uriel_api_doc_index_node.get_children(),
                             key=lambda n: n.get_title() + n.get_path()):

        lines.append("  " + child_node.get_link())

    # if you uncomment this line, it will cause an error when the site builds
    #raise SojuError("oops")

    # combine and return the lines as a string
    return "\n".join(lines)

When we call this function, by including it a node or template, using the
{{soju:example(page, node, project_root, use_canonical_url)}}
substitution parameter, this is the output of the function that ends up on the rendered page:

Hello from the example() function!

Generated by uriel version 1.4.1

page:              soju [null]
node:              soju
project_root:      .
use_canonical_url: True

Uriel API
  Constants
  Exceptions
  Functions
  Node Classes

You can see the output of the log() function when the site builds:

copying 'static' to 'public', overwriting previous contents
initializing soju
initializing handlers
reading node files
rendering node content
soju: the example() function is running now
creating pages in 'public' from nodes and templates

... lots of output omitted for brevity ...

created 110 pages (95 file, 15 virtual)
creating 'public/rss.xml'
soju: the example() function is running now
creating 'public/sitemap.xml'
creating 'public/robots.txt'
copying 'static' to 'public'

Notice that the log() message shows up twice? This is because the example() function is called twice. Once when the HTML page is generated, and again when the RSS feed is generated.

The example() function basically collects a variety of values from various parts of the Uriel API, and then returns a string that can be displayed in place of the substitution parameter on the generated page.

The escape() function performs HTML escaping. As a general rule, it should be wrapped around any dynamic values that are returned.

However, any Node methods that return HTML fragments should not be escaped (e.g. get_link()).

You should always be aware of HTML escaping when writing custom Soju functions.

Error Handling

All Soju functions must return a Python str value.

If your function returns a value with a type other than str, has a syntax error, or if it raises an exception when it is called, Uriel will show an error when the site builds. This error includes detailed information about which node and templates were involved, which Soju function was called, and what the error was, including a Python traceback. This makes it easy to find what caused the build to fail, and where to start your debugging efforts.

If you want to avoid the Python traceback portion of the error, you can raise a SojuError when you need to raise an expected error. This will still result in detailed information about where the error originated, but it will skip the Python traceback portion.

If you uncomment the SojuError line from the example() function, it will cause the web site build to fail, with a brief error message.

Example SojuError build error message:

copying 'static' to 'public', overwriting previous contents
initializing soju
initializing handlers
reading node files
rendering node content
soju: the example() function is running now
parameter error:
  nodes/soju
    templates/default.html
      nodes/soju
        '{{soju:example(page, node, project_root, use_canonical_url)}}'
          'oops'
soju: error in function call to 'soju.example(page, node, project_root, use_canonical_url)': 'oops'

The {{node-url:foo/bar}} parameter evaluates to the URL for the node specified in the rvalue portion of the parameter. Nodes are specified as paths starting from the nodes directory.

For example, on this documentation site, we have another node with the path parameters/some-other-node.

If we reference it using parameters/some-other-node as the rvalue, then {{node-url:parameters/some-other-node}} evaluates to:

https://documentation.uriel.foo/parameters/some-other-node/

Compare this with {{node:url}}, which lets you get the URL of the current node.

URL Representation in HTML vs. RSS

In generated HTML pages, the URL will include the full path to the URL from the root of the web site, but will not include the domain name. Like this:

/parameters/some-other-node/

In the generated RSS feed, the URL will include the Canonical-URL. Like this:

https://documentation.uriel.foo/parameters/some-other-node/

The actual value of {{node-url:parameters/some-other-node}} in the current context evaluates to:

https://documentation.uriel.foo/parameters/some-other-node/

View this in both the web page and the RSS feed, and compare the results.

The {{node:url}} parameter evaluates to the URL for the current node.

Typical Usage

Use this when you need to get the URL for the current page.

For example: https://documentation.uriel.foo/parameters/node-url/

Compare this with {{node-url:foo/bar}}, which lets you get the URL of another node on the web site.

URL Representation in HTML vs. RSS

In generated HTML pages, the URL will include the full path to the URL from the root of the web site, but will not include the domain name. Like this:

/parameters/node-url/

In the generated RSS feed, the URL will include the Canonical-URL. Like this:

https://documentation.uriel.foo/parameters/node-url/

The actual value of {{node:url}} in the current context evaluates to:

https://documentation.uriel.foo/parameters/node-url/

View this in both the web page and the RSS feed, and compare the results.

The RSS-Include header controls whether a node is eligible for inclusion in the generated RSS feed.

There are two possible values:

• true
• false

The default value is false.

The node that generated this page has the RSS-Include value set to true. As a result, it is included in the generated RSS feed (https://documentation.uriel.foo/rss.xml).

The usual node header inheritance rules apply.

Here are two example pages highlighting the difference:

RSS-Include: true

RSS-Include: false

Controls whether a title header element is added to the body content of nodes included in a generated RSS feed.

There are two possible values:

• true
• false

The default value is true.

When Uriel generates an RSS feed, it only uses the node contents, and completely ignores the template settings that are used to render the HTML pages on the main web site.

However, in most site layouts, the node title is likely to be displayed on the page in a template using a {{node:title}} substitution parameter, and not from within the node body contents themselves.

Therefore, when RSS-Add-Node-Title-Header is set to true (or left to its default setting), Uriel will add an HTML <h1> header tag containing the node title to the top of its RSS entry.

If you want to override this behavior, simply set the RSS-Add-Node-Title-Header to false.

All of the normal node header inheritance rules apply.

Compare how the following nodes differ in their representation within the generated RSS feed (https://documentation.uriel.foo/rss.xml).

• RSS-Add-Node-Title-Header: true
• RSS-Add-Node-Title-Header: false

As a result, Uriel has not added an additional <h1> title header to the top of its RSS <description> field in the generated RSS feed (https://documentation.uriel.foo/rss.xml)

Compare this with RSS-Add-Node-Title-Header: true

This node has the RSS-Add-Node-Title-Header header set to true.

As a result, Uriel has added the following HTML code to the top of its RSS <description> field in the generated RSS feed (https://documentation.uriel.foo/rss.xml):

<h1>RSS-Add-Node-Title-Header: true</h1>

Compare this with RSS-Add-Node-Title-Header: false

This node does not have an RSS-Include header defined directly. However, it inherited a true value for this header from its parent node.

As a result, it is eligible for inclusion in the generated RSS feed (https://documentation.uriel.foo/rss.xml).

Compare this with RSS-Include: false