Cross-Site Includes

by pieterh on 31 Oct 2009 14:19

On Thursday and Friday we rolled out a very important new feature, cross-site includes, or CSIs. CSIs make it possible to share code across sites. I'll explain roughly how this works, and provide some examples of where we're already using it.

First, to see it working: take any one of your sites, which has a category with pages (e.g. 'mycat'), and create a category _start page that contains just this: [[include :modules:include:8 page=mycat:_start | category=mycat | label=Mystuff]] This pulls in the Hammer Navigator, which shows a list of the pages in that category. Hammer is the pattern that organizes wiki pages as a list.

CSIs work just like normal includes except that you add ':sitename:' in front of the page name. In this example, :modules: refers to, a new site we started a few days ago to hold collections of CSIs, which we're calling 'userspace modules' (as compared to the modules Wikidot provides us).

Here is another example, the wishlist module. This lets you add a simple wish list to other pages, e.g. to documentation pages. To install, create wish:_template containing [[include :modules:include:11]] and then in your site manager, mark the wish category as autonumbered. Put this code into your primary page template where you want the wishlist to appear: [[include :modules:include:10]].

CSIs can happily act as live templates, accepting symbols from the calling page. This is how the first example I showed above works. The CSI code has things like this:

[[span style="border: 1px solid silver; font-weight:bold; padding: 7px"]][/{$category}:new-{$category}/edit/true/parentPage/{$page}/title/%20 Create a new {$label}][[/span]]

Which is a neat way of creating child pages in autonumbered categories, but that's another story.

You can see the modules I've already assembled at Feel free to try these. They are all being used, already, on this site, on the Iron Giant templates, and elsewhere.

CSIs make it very easy to pull code into your site and then never worry about maintaining it. The only downside is that you can't customize the code except by forking it and creating your own versions. When the author releases a new version of the CSI, your sites will immediately get the new version. If you want to discuss and improve an existing userspace module, head over to the projects forum.

To end with, we've made a Navigator tool (still beta, but already useful). Here's how to get the beta Navigator tool in your site in 30 seconds. First, edit the top menu to add:

 * [/system:navigator Manage pages]

And then create system:navigator with this one line of code: [[include :modules:include:12 page=system:navigator]].

Update: to use the Navigator you do need a compatible stylesheet. If you're not using a Rainbow or Minimalist theme, please see the instructions on the Navigator page.

Comments: 25

Add a New Comment