Snippet (embed)

Use the snippet editable to embed a document snippet, for example teasers, boxes, footers, etc.

Snippets are like little documents which can be embedded in other documents. You have to create them the same way as other documents.

It is possible for users to drag snippets onto a document (like a sidebar item that is different on every page) or for the developer to place one on a fixed position in a (layout) template (like footer that is the same on every page, see code example).

Creation

To create your own snippet start with creating a PHP file in the directory website/views/scripts/snippets. This file can contain HTML and PHP code. You can add text input fields here. This file is the view that is being used for this snippet.

The file website/controllers/SnippetsController.php is the controller and contains the actions associated with all snippets. If you have named your view "footer.php" you should add a method "footerAction()" here. This method will be called every time the snippet is displayed. You can retrieve information from the database here and pass it on to the view here using $this->view and adding variables to it.

After creating the view and the action the snippet will not yet appear for the user. Before a snippet can be used you need to define it as a custom Document Type.

Configuration

Accessible Properties

Example

 // Define a place for a snippet to be dragged onto, basic usage
<?php echo $this->snippet("mySnippet") ?>

// Define a place for a snippet to be dragged onto, advanced usage
<?php echo $this->snippet("mySnippet", array("width" => 250, "height" => 100)) ?>

Display text from snippet on every page

If you have a footer text that you want to appear on every page, like for example a copyright notice that the user should be able to edit, create a snippet as follows:

 <?php echo $this->wysiwyg('footer', array('width' => 500, 'height' => 100)); ?>

Place the file in the snippets directory and name the file footer.php then add it a s a document type and create a snippet called "footer" as a document.

It is important that this snippet is never moved, renamed or deleted. To prevent this you can set the Document permissions so that certain users can't perform these actions. To remove the snippet from the website it can be unpublished by the user.

Then add the following code to your layout template (located in the "layouts" directory):

<?php
$s = Document_Snippet::getByPath('/snippets/footer');
if(is_object($s) && is_object($s->elements['footer'])) {
    echo $s->elements['footer']->frontend();
}
?>

This code loads the snippet from a specific location. It then checks if it indeed exists and continues to extract the text from the WYSIWYG-field named "footer" and echoes it on the page.

Security note: because we are using a WYSIWYG-field, HTML can be inserted by the user. If you don't want this; use another kind of input field. Don't forget to escape its contents before displaying them!