Calling Code Sources from templates

Code Sources were originally invented as a means of inserting special content in Silva documents. For example an Author might want to embed a video in a page. By using a Code Source the Author only needs to input a few values in a form (as opposed to knowing all the html that’s required). Code Sources make the process  much Author-friendlier. The Author can concentrate on content, leaving the technical stuff to a Manager/developer. By the way, the inventor of Code Sources was Benno Luthiger from ETH Zürich.

It’s also possible to use Code Sources in templates. For instance embedding a Google Map in a contact page is useful. But one may also want the map, in a smaller format, always visible in a flanking column. That requires template work.

To use a Code Source in a template you must first define the parameters with their values, then pass them through to the Code Source. When called in this way the Code Source will use its render_to_html method and return formatted html and content.

Let’s use the example from the Code Source HowTo and call the Network Image CS from a template. Say we want the image to appear in the footer on every page.

First we define the parameters as configured in the Code Source. Required parameters must be defined, while the others are – just like in a document – optional. Here’s sample code:

<div style="float:right"
  tal:define="
    image_location string:http://opensource.org/trademarks/osi-certified/web/osi-certified-120x100.png;
    image_width string:120;
    image_height string:100;
    alt_text string:OSI Certified;
    link_url string:http://opensource.org/;
    link_tooltip string:Read a definition of open source software;
">
  <img tal:replace="structure python:context.cs_network_image.netimage(
    image_location=image_location,
    image_width=image_width,
    image_height=image_height,
    alt_text=alt_text,
    link_url=link_url,
    link_tooltip=link_tooltip,
  )" />
</div> 

Since the enclosing div has alignment we’ve skipped the alignment_selector parameter, but all the others are defined, including the required image_location, image_width and image_height.

Then we call the Code Source and pass the parameters through. In fact we call the renderer within the Code Source, which may be a script or page template, like so:

structure python:context.cs_network_image.netimage()

Since we’re getting html back, we need structure. The call will find the Code Source higher in the content tree using acquisition. The renderer is named ‘netimage’.

Within the parentheses we pass the parameters, using the same names to keep things straight (listing each one on its own line following our coding guidelines for TAL). You can skip a parameter that’s defined above, but don’t pass a parameter that isn’t defined. If the Code Source has no parameters you can just use a TAL path expression.

When everything is correctly defined and passed, the network image will show up in our page, complete with a link and tooltip.

This should work with any version of Silva and External Sources.