Calling Code Sources from templates directly

Hi,
At the sprint following EuroPython we made a minor breakthrough, we  
figured out how to call Code Sources directly from templates. Took  
awhile to get it properly documented, but this will be included in the  
next release.

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 the required External  
Sources.

-- 
Kit BLAKE · Infrae · http://infrae.com/ + 31 10 243 7051
Hoevestraat 10 · 3033 GC · Rotterdam + The Netherlands