Create a Snippet

Creating your own snippet is a manual process. You create the necessary files, put them in a folder, and copy that folder into the Transtream file system (your version's Composer\_snippets folder). It will then appear in the Snippet box. This content outlines how to do this and explains the structure of snippets in Transtream. It creates a snippet that adds a Google Search Engine link to a page.

Anatomy of a Snippet

Snippets comprise of a folder containing at least three files:

• A configuration file called config.xml.
• A JavaScript file containing the snippet logic. In Transtream, the naming convention used is NameSnippet.js, for example, AddressBookSnippet.js. Most of the supplied snippets only have a single JavaScript file, but additional JavaScript files (Designer_ and Shared_) are supported to provide more possibilities. There is more on this below.
• An HTML file called template.html. If required, you can have additional HTML files.
• Optionally, a styling file called style.css.

The folder's name does not have to be the name of your snippet, but it is a good convention to follow.

The config.xml file

<?xml version="1.0" encoding="utf-8" ?>
<Snippet>
   <Icon>eye</Icon>
   <Name>SearchLink</Name>
   <DefaultWidth>150</DefaultWidth>
   <DefaultHeight>19</DefaultHeight>
   <Parameters>
      <Parameter name="text" type="string" defaultValue="Search" />
      <Parameter name="searchControlName" type="string" defaultValue="google" />
   </Parameters>
   <Intellisense>
   </Intellisense>													
</Snippet>

Key points:

• Must be called config.xml.
• Icon is a name from the Font Awesome library. This is what will appear in the Snippets box.
• Name is used as the tooltip in Designer.
• Parameters are what you want to expose through Properties in Designer.
• Intellisense lets you add optional help for parameters to be shown in Designer. Examples can be found in the supplied snippets.

The JavaScript file(s)

Holds the snippet’s functionality, and must have this format:

pb.snippets.SnippetName = function (cfg) {
pb.snippets.Snippet.call(this, “Folder", cfg);
// Snippet Logic

Key points:

• SnippetName is the name of the JavaScript file (without the extension). In Transtream, the naming convention used is NameSnippet.js. So in this example it would be SearchLinkSnippet.js.
• Folder is the folder that contains the three files.
• Snippet Logic is the JavaScript code that the snippet executes.

Example:

pb.snippets.SearchLinkSnippet = function (cfg) {
 pb.snippets.Snippet.call(this, "SearchLink", cfg);
  $("#" + cfg.name).click(function(e) {
  e.preventDefault();
  var searchValue = cfg.searchControlName,
  searchLink = 'https://www.google.co.uk/search?q=' + searchValue,
  searchLeft = (screen.width / 2) - (1100 / 2),
  searchTop = (screen.height / 2) - (710 / 2);
  window.open(searchLink, 'Search', 'directories=no, titlebar=no, toolbar=no, location=no, status=no, menubar=no, width=1100, height=710,
  top=' + searchTop + ', left=' + searchLeft + '');
  });
 };

The template.html file

This is the HTML that the snippet runs in. For example:

<div class="search-link-snippet">
<a class="search-link" href="">{{text}}</a>
</div>

This file must be called template.html. It can refer to other HTML or CSS files. But there must, at least, be template.html.

The style.css file

Defines the snippet's styles. For example, the following sets the text color:

.search-link-snippet a.search-link {
color: #428bca
}

Add your snippet to Designer

The snippet files need to be in a folder. As mentioned, the name of this folder is included in the JavaScript file. You do not have to give the folder the same name as the snippet, but it is a good convention to follow. Copy the folder to Composer\_snippets within your Transtream version’s installation folder. This folder will already contain folders for all the existing snippets. Once the folder is in place, your snippet will appear in the Snippet box.

Once on a page, in its Properties box, click to see the snippet’s parameters (as defined in config.xml).