Development » Snippets

Snippets

What are snippets?

Snippets are the workhorses of your site � they contain PHP code which you can use to make your site as interactive and dynamic as you wish. They bring great power to Etomite, but, to quote Peter Parker, 'With great power comes great responsibility...' Snippets give you the chance to do whatever you want in your site, but badly written snippets can break your site. My advice is to write your snippet in a staging setup, and only to promote the snippet to your production site once you're sure it works properly.

Snippets are written in the snippet editor, and can be included in your documents and templates using the snippet tags placed in the document or template; for example [ [SnippetName]], where SnippetName is the name of the snippet you are inserting into your document or template.

Snippets execute as if they are functions. This means that the snippet must return the output it creates. They may also make use of the  Etomite API, which can be used to save time when coding snippets. For example, a way of writing the MainMenu script:

if(!isset($id)) {
    $id = $etomite->documentIdentifier;
}
$children = $etomite->getActiveChildren($id);
$childrenCount = count($children);
$menu='';
if($children==false) {
    return ' ';
}

for($x=0; $x<$childrenCount; $x++) {
        $menu .= "

  • ".$children[$x]['pagetitle']."
    • ";
    }
    return $menu;

    What this does is to check if an $id variable has been passed to the snippet, and if not, it set's the current document's id as $id. Then it uses $children = $etomite->getActiveChildren($id); to retrieve all the active children of the document with ID $id. After setting up some more variables, it loops through the $children array, and for each entry it creates a link which is added to the $menu variable. The last thing it does is to return the $menu variable to the Parser, which will then paste it into the document it's currently parsing.
    You can combine snippets and chunks to great effect:

    $userdata = $etomite->userLoggedIn();
    if($userdata===false) {
        return "{ {NotLoggedIn}}";
    } else {
        return "{ {LoggedIn}}";
    }

    This will check if the current visitor on a page is also logged in, and depending on the outcome, writes the LoggedIn or the NotLoggedIn chunk into the document. Those chunks could contain new calls to other snippets (e.g. if the user is logged in, a snippet to show how many pageviews the page has had).
    Note: you can also insert chunks using the API call $etomite->putChunk(string $chunkName);, a cleaner way of doing things (and possibly slightly faster, too.)

    Writing Snippets

    Writing snippets is easy � as long as you know some PHP. If you don't know any PHP, grab a good book, and teach yourself some. While you're doing that, play around with the snippets on the Etomite site to see how they work and what they do. It may seem a little daunting at first, but PHP is suprisingly easy to learn. If you know some JavaScript (and I think most site developers will), you shouldn't have too much trouble picking some PHP up. If you're not willing to learn some PHP, they maybe you can find/ hire someone who'll help you set your site up. Once you've set your site up with the snippets you need, you'll probably not need to change them too often, if at all.

    Let's assume you know some PHP, and let's see how we write snippets. As I stated earlier, writing snippets is easy. You can use any PHP in it you want, and you can use just about every function you want. The only thing you shouldn't do in a snippet, is to echo or print stuff. Leave that to the Etomite parser, that's what it's there for. What a snippet does, is carry out some PHP functions, and then it builds some HTML which it returns to the parser. A very simple snippet:

    $html = "Hello world!";
    return $html;

    Pretty simple :)
    Notice the return statement at the end of the snippet. All snippets for Etomite 0.6 and higher MUST contain a return statement. If a snippet doesn't have a return in it, the parser will fail, and tell you there's an error in running the snippet. If you return false;, or an empty string, it will fail too. To exit a snippet silently, simply return true;.
    The snippet system lets you pass variables to snippets. For example:

    [ [MenuBuilder?id=0]]

    This will call the MenuBuilder script, and prepare a variable called $id for it, and fill the variable $id with the value 0. Watch out with this, if the variable id already exists in the current scope, it won't be populated by the new value!

    Also be very wary of register globals. If this is on, then any text put into the querystring (e.g. ?x=123) will populate the $x variable. This is a feature of PHP, not Etomite. Therefore, it is recommended you do something like this to prevent security loopholes:

    if (!empty($_REQUEST['x'])) {
        $etomite->messageQuit("Variable 'x' set in request, expecting empty variable!");
    }
    // We're still here, let's continue and use the $x parameter passed to us

    A Word About Page and Snippet Caching

    Etomite allows you to enable page caching to improve server performance and speed delivery of content. When caching is enabled, the first time a page is requested, a cache version of it is saved. Any snippets included in the page with the standard syntax:

    [ [SnippetName]]

    will be evaluated and included as plain HTML. It is sometimes desireable NOT to allow your snippets to be cached, however, because they provide dynamic data. To force a snippet to run, even on cached pages, you can use the ! syntax instead:

    [ !SnippetName! ]

    When you use a non-cached snippet, on a cached page, you need to be aware that some variables will not be available to you. Most noteably, the $etomite->documentObject family of variables. This object is not created during the cache loading process. To get around this you could create a new array of page info that simulates the pieces of documentObject.

    $docInfo = $etomite->getDocument($etomite->documentIdentifier);

     

    // So instead of using $etomite->documentObject['pagetitle'] you would use:

    $title = $docInfo['pagetitle'];

     

    // etc.