Adding Snippets

Snippets are one of the most useful features of the Evo system. Snippets add functionality to your site, and make site menu updates a thing of the past.

This document discusses the use of snippets. To find out more about how to create snippets and how they work, see the Snippets documentation.

Installing Snippets

Snippets are bits of code to perform some dynamic action, such as retrieve data from a database or read from the SESSION values or a cookie. They provide the ability to separate "business logic" from the layout and presentation of your web page.

Snippet code is stored in the database, but there are sometimes auxiliary files that a particularly complex snippet needs to function. The snippet acts as the interface between Evo and the auxiliary files. The WebLogin snippet is an example of a snippet with a number of auxiliary files. These files are stored in their own folder in the /assets/snippets folder of your Evo installation, such as /assets/snippets/weblogin/. A snippet that stands alone, as most snippets do, does not get uploaded to your site's file system at all.

During your installation of Evo, a list of optional snippets to be automatically installed was offered. If you chose to install them, these snippets are already ready for you to use in your templates or documents.

To install a new snippet, log in to the admin interface and go to Manage resources and open the Snippets tab. Click on the New snippet link to open the form. Copy/paste the code from your snippet's source, usually a text file that you open in a text editor, into the textarea, give it a name and a brief description. You can name a snippet anything you like, just remember that the name you give it is how you will need to call it later in your template or document source.

When uploading any auxiliary files the snippet may have, it is usual to put them in a folder with the original name of the snippet in lower case, such as /assets/snippets/weblogin.

Using A Menu Snippet

In our template so far, we have some personalized bits of information, and some content. But that sidebar is still empty. We need to put a navigation menu there.

Now, there are two ways this can be done. We could code the menu by hand.

<a href="">Home</a>
<a href="">News</a>
<a href="">About Us</a>

There are a number of problems with this approach. First, you have to know the document ID of the pages you are linking to. Second, what if you want to use Search Engine Friendly URLs? Now you have to know the alias of every page you link to, as well as how your site was configured to handle that feature. And finally, imagine having to edit the menu every time you add a page or two...or twenty!

This is where Evo snippets come in. There are a number of menu generating snippets available to generate any kind of menu you like. Arguably the best type are those that generate simple unordered lists, since they allow the most flexibility in controlling their appearance and behavior with CSS.

Menu snippets get a list of documents from the database, starting with a folder that you specify within the snippet tags as the root of the menu. Let's add a menu to our template, and see how that works.

<div id="sidebar">
<!-- menu and other blocks goes here -->
[[MenuSnippet?id=`0` &activelink=`active`]]

A little CSS styling of the list and the links, and we have a nice, dynamic menu that you never have to worry about again!

Configuring Snippet Tags

Snippet tags can take two forms, [[SnippetName]] or [!SnippetName!].

The first form is a normal snippet call; if the page is cached, the snippet's output will also be cached. Usually this will not be a problem. Sometimes, however, it is important that the snippet's output not be cached. For example, the Login snippet needs to determine if the user has logged in, and if not, display the login form, and if so, display the logout link. If the page is cached, the snippet is not run, and the display would not change. The second form, using exclamation marks, causes the snippet to be run even if the page has been cached. For a menu, however, that probably isn't necessary.

The menu snippet we used has two arguments, "?id=`0`" and "&activelink=`active`". Most snippets will take a varying number of arguments to customize their behavior. Menu snippets always take at least the "id" argument, to determine which document to use as the "root" of the menu. Usually, this will be "0", indicating the root of the site. The first level of the menu will be generated based on the first level of documents in the document tree under that "root" document. Usually, if an "id" is not supplied in the snippet call, the current document's id will be used, which is usually not what you want. Make sure to specify a root id for menu snippets!

Most menu snippets have a number of other optional arguments. In this case, we used "activelink". This may have different names for different snippets. What it does is to set a "class='active'" attribute in the <a> HTML tag, allowing you to use CSS to style the link to the page the user is currently in. In our example, you can see that the "Home" link is blue, since the user is in the Home page.

Any time you need a snippet of interactive code on your page, such as dynamic menus, login forms, site search forms, multilanguage functionality, Evo snippets are your solution. There are dozens of snippets already created and ready for you to simply drop into your site. As the Evo community grows, the number and variety of snippets will grow as well.

Suggest an edit to this page.