Quick Start Guide

Overview
Audience
Getting Started
Creating a Hello World plugin
Using templates in plugin
Exporting design elements
Exporting page with content
Debugging the export scripts
Using JavaScript Templating Engine
Testing and Quality Control
Artisteer template layout
Exporting sample data
Exporting thumbnails
Default content and design
JavaScript API
The structure of content.xml

Overview

This practical guide provides basic information and instructions for creating Artisteer Export plugins.

Audience

This document is intended for web and application developers with good knowledge of JavaScript and jQuery.

Getting Started

In order to create Artisteer plugins, you will need the following software installed:

The export process involves extracting various pieces of HTML code from Artisteer design page and using them to create a set of template files for a specific CMS.

Below you can find several examples of how to create simple Artisteer plugins.

Creating a Hello World plugin

Creating a Hello World plugin is easy and requires only a few steps:

  1. Start Artisteer
  2. Select File -> Develop -> New Plugin in the Main Menu
  3. Type the name of your plugin and click "OK".

create a plugin

Clicking "OK" creates a new export plugin and makes it active in Artisteer. The plugin becomes available in the New Project dialog and in the list of templates available for Export.

Windows Explorer will also open a folder containing your newly created plugin files:

plugin files

Open the export.js file in a text editor and replace the build() function code with the following:

function build() {
	'use strict';
    //create a new index.html file and fill it with HTML
    result.write('index.html', '<!DOCTYPE html>\n<html><head>' + 
        '<link rel="stylesheet" href="style.css" /></head>' + 
            '<body><h1>Hello world</h1></body></html>');
    //create a new style.css file and fill it with CSS
    result.write('style.css', 'h1 {color:red;}');
}
Note: Click here to view all methods of the "result" object.

Save the updated export.js file, go to Artisteer and click Export. If the export is successful, two files will be created:

Open index.html in a browser and you will see:

export result 1

Congratulations! You have created your first Artisteer plugin.

Note: The "result" object is the JavaScript emulation of file system. You save your export output files into the "result" object and Artisteer copies these files from the "result" object to a user-selected folder.
Using templates in plugin

This example shows how to work with files in JavaScript.

Copy the generated index.html and style.css files from the previous example to the "template" folder of your plugin

Open the export.js file in a text editor and replace the build() function code with the following:

function build() {
	'use strict';
    // read the contents of the index.html file (located in the "template" folder)
    // into an "html" variable
    var html = template.read('index.html');
    // replace a substring within the content
    html = html.replace('Hello world', 'Ave Caesar');
    // create a new index.html file and fill it with the modified HTML content
    result.write('index.html', html);
    // copy the style.css file from the "template" folder to the export result
    template.copyTo('style.css', result, 'style.css');
}

Re-export the template from Artisteer and display the index.html page in browser. You will see:

export result 2

Note: All files and subfolders located in the "template" folder are available within the script through the "template" JS object. Artisteer generated design files are available through the "design" JS object.
Note: Click here to view all methods of the "template" and "design" objects.

Unlike the previous example, this example uses predefined files for export instead of generating files on the fly. This technique significantly reduces the amount of JS code and, what is most important, allows creating template files for export. Using files from the "template" folder is one of the key features of API.

To test this further, you can try placing an image in the "template" folder and using it in the index.html file.

Exporting design elements

Below is a more complex example. This time you will transfer the header from Artisteer design page as well as replace the headline with "Hello world".

To apply Artisteer-generated styles and header background, you need to copy styles and images from the "design" object to the export result.

Delete style.css from the "template" folder and replace the contents of the index.html file with the following code:

<!DOCTYPE html>
<html>
    <head>
        <link rel="stylesheet" href="style.css" />
    </head>
    <body>
        {header}
    </body>
</html>

Note that the code contains the {header} placeholder. This placeholder will be replaced with the actual header content when exporting a template.

Open your export.js file and replace the build() function with the following code:

function build() {
	'use strict';
    // replace the original headline with "Hello world" 
    // and copy the page header’s html to the "header" variable
    $('h1').html('Hello world');
    var header = $('header').outerHTML();
	
    // read the content of the index.html file into the "html" variable
    var html = template.read('index.html');

    // replace the {header} placeholder with the header’s html from Artisteer design
    html = html.replace('{header}', header);
    result.write('index.html', html);
	
    // copy Artisteer-generated styles and images to the export result
    design.copyTo('style.css', result, 'style.css');
    design.copyTo('images', result, 'images');
}

Save your export.js file, go to Artisteer and re-export the template. Open the generated index.html in browser and you will see:

exported header

Note: Export scripts are executed in the context of the design page (debug\debug.html), thus, you can find all the necessary page elements using jQuery selectors.
Exporting page with content

Our last example describes how to create a simple, fully functional export that would export the first page of your Artisteer project with all the styles and images.

Replace the content of the index.html file located in your plugin’s "template" folder with the following code:

<!DOCTYPE html>
<html lang="en" dir="ltr">
    <head>
        {page_head}
        <style type="text/css">
            {content_styles}
        </style>
    </head>
    <body>
        {page_body}
    </body>
</html>

Open export.js and replace the build() function with this one:

function build() {
    'use strict';
    var html, fragments, contentXml, pageContent;    
    // replace the content part with the {content} placeholder    
    $('.art-postcontent').html('{content}');    
    // get fragments from Artisteer design    
    fragments = {    
        page_head: $('head').html(),    
        page_body: $('body').html()    
    };    
    // get the styles and content of the first page from the content.xml file    
    contentXml = $.parseXML(content.read('content.xml'));    
    pageContent = $('page:eq(0)', contentXml);    
    fragments.content = pageContent.children('content').text();    
    fragments.content_styles = pageContent.children('pageHead').text();    
    // get index.html and replace the placeholders    
    html = template.read('index.html');    
    var searchPattern = /\{([\w_]+)\}/g;  
    var placeholderReplacer = function (str, ph) {    
        return fragments[ph];    
    };  
    while (html.search(searchPattern) !== -1) {    
        html = html.replace(searchPattern, placeholderReplacer);    
    }     
    // write the resulting html code to the export files    
    result.write('index.html', html);    
    // copy Artisteer-generated styles and images    
    design.copyTo('/', result, '/');
    // copy content images
    if(content.exists('images')) {
        content.copyTo('images', result, '');
    }
}

exported template

Note: The content.xml file contains all the content of the project currently opened in Artisteer. Click here to view the format of content.xml.

Export your template from Artisteer. The result will be a page generated by your script as shown below.

Note: We recommend converting Artisteer design to your CMS template manually before creating plugin scripts.
Debugging the export scripts

To debug an export plugin, you can use browser debugging tools. Here are the steps to follow:

  1. Select File –> Develop -> Debug in Browser
  2. Open Developer Tools in Browser
  3. Select export.js from the list of scripts
  4. Add a breakpoint to the first line of the build() function
  5. Switch to the Console tab and enter "build()" to execute the script
  6. Built-in debugger will stop on this line
  7. Use Step into, Step over, Step out commands and Watch Expressions to debug your script.

debugging

Note: In Artisteer you can also use alert() function to debug your scripts when exporting.

If there is an error occurred during the script execution, Artisteer will display a message box with the error details. Users can choose to send crash reports to the support email specified in your plugin options.

Note: There is no need to restart Artisteer every time you want to test your code modifications: Artisteer automatically updates all export files when the Export option is selected.

Using JavaScript Templating Engine

When writing export plugins you may consider using a JavaScript templating engine.

The advantages of templating engines are:

The downsides of using a JavaScript templating engine are the need for some extra coding for layouts that differ from the base ones.

Our Moodle plugin is an example of using the JS Render templating engine. When creating custom plug-ins you can also use other templating engines. The full source code of the Moodle plugin is available at the Artisteer developers' page.

In order to use JSRender, simply copy the jsrender.js file to your plugin root folder; it will be automatically linked to the master page.

To run JSRender, add the following code to the build() function in the export.js.

template.enumerateRecursive('/').forEach(function(path) {
	if (!template.isBinary(path)) {
		var content = template.read(path);
		content = $.templates(content).render({ $: $('html'), options: options, fragments: fragments });
		result.write(path, content);
	}
});

This code calls JSRender for every text file located in the “template” folder. We may pass to JSRender an arbitrary number of parameters. All the properties will be available in the global scope. In the example above, we pass to JS Render the master page, options and fragments.

You can dynamically add a property to the fragments object:

fragments.styleSheets = "Style sheets for Sheet";

and use it in a template file (e.g. Moodle\template\config.php), which is processed during the export:

$THEME->sheets = array({{:fragments.styleSheets}});
The begin() and end() Converters

To make working with HTML easier the begin() and end() JSRender converters are defined in the export.js. They return the opening and closing HTML tags of the given DOM objects.

For example, {{begin:$.find('nav.art-nav')}} returns <nav class="art-nav clearfix"> and {{end:$.find('nav.art-nav')}} returns </nav>

Processing of the Layouts that differ from the base (default) layouts

The [If] operators can be used to process the layouts that differ from the base (default) layouts. As you probably know, sidebars in Artisteer designs may appear on the left, right or both sides of the sheet. To process all possible layouts, the current positions of sidebars are calculated in the export.js, and assigned to a property in the options object.

	options.sidebar1Position = 'before_content';

After that we can add the following code to the general.php:

	{{if (options.sidebar1Position === 'before_content' ) }}
	some code here
	{{/if}} 
Note: almost all the coding for the Moodle export is done in the: Moodle\template\layout\general.php file.
The code () Function

While adding a PHP code to the DOM model with jQuery, you may get an issue with converting your code into comment. For example, the following code:

	$('nav').html('<?php some php code ?>')
	$('nav').html()

will produce such result:

	<!--?php some php code ?-->

As a solution to this issue we have added a code () function to our API. You can safely add your PHP code to the DOM model by calling the code() function:

	$('nav').html(code('<?php some php code ?>'))

Testing and Quality Control

It is not possible to know that the code works as expected unless it is properly tested. Artisteer provides several built-in mechanisms to improve the quality of your code.

The most typical cause of export errors is failing to process uncommon cases. For example, your code may incorrectly process a template layout without header, footer or sidebars. The good news is that we have created a set of such tricky templates for you and developed a built-in tool for testing your plugins with them.

To run the tests for your export plugin, follow the steps below:

  1. Go to Artisteer and select Menu File –> Develop –> Run Tests. Artisteer will suggest that you download the test design set from our website.
  2. Click "ОК" to download the test designs.
  3. Shortly after that a web browser will be launched to run your plugin tests.

running tests

The tests perform the following actions:

  1. General Tests: Calls the build() function for all possible option combinations from the options.xml file and test designs
  2. Static Code Analysis: Checks JS scripts using JSHint utility
  3. QUnit Tests: Performs user tests from test.js file (optional)

The report page will display all detected errors and warnings.

Note: Passing the General Tests is an obligatory requirement for submitting your plugin to Artisteer market place.

Artisteer template layout

Below you can see a typical layout of Artisteer template. The layout can vary for different designs: some parts of the template can be omitted or repositioned.

template layout

You can use the following jQuery selectors to select HTML elements by specific class names:

For example:

var header = $('.art-header'). outerHTML();

Exporting sample data

A user can decide to export the content of Artisteer project (pages, posts, images, etc) by checking "Include Sample Data" option in the Export dialog. Selecting this option makes the user’s website look exactly the same as it looks within Artisteer.

When "Include Sample Data" option is selected, the options.IncludeSampleData variable takes the value "True" in JavaScript code.

If your CMS does not support importing sample data or you do not want to implement this feature in your plugin, you can remove "Include Sample Data" option from the dialog by using Enable="false" parameter in your options.xml file:

<SampleData Enable="false" Content="true" Layout="false" InlineStyles="false" />
Note: All content files will be available in the script through the "content" object. The "content" object has the following structure
    [images] 
-- content images
content.xml
Important: Be sure not to delete or override any existing website content when importing sample data from the template. An exception can only be made for sample data added by the previous import.

Exporting thumbnails

You can add a snapshot of the design to the export output.

To do this, specify the thumbnail image name and its size in options.xml. For example:

<thumbnails>
    <thumbnail width="206" height="150" path="images/template_thumbnail.png" />
  </thumbnails>

Default content and design

Artisteer allows you to set the default content for the new projects: page text, images, article, block, footer, article metadata icons. For this, create the default.artx project with the desired content and save it to your plugin’s root folder.

The default settings will be copied to all newly created projects when a "New Project" option is used and your CMS is selected in the dialog window.

JavaScript API

The following objects are available during the execution of your export.js script:

NameObject TypeDescription
optionsobjectOptions selected by a user in the Export dialog and an additional information such as Artisteer version, operation mode (full or demo), etc.
templateFileManagerUser files from the "template" folder
contentFileManagerContains the post/page images and content.xml file (with HTML code for pages, articles, blocks, footer, etc.)
designFileManagerContains Artisteer-generated design files.
resultFileManagerHolds the export result files. Initially this object is empty and is filled by the script during its execution. Artisteer saves this object into a user-specified folder.
File operation

You can create, copy, add, delete, and edit files inside the objects of FileManager type. For example:

    result.write('index.html', "<b>Hello!</b>");
    design.copyTo('style.css', result, ‘Styles/style.css');
Archive creation

You can create archives within the objects of FileManager type. The following archive formats are supported: Zip, Gz and Bz. Here is an example of creating a Zip archive:

result.createArchive("dir1/arch1.zip", "zip");
result.write("dir1/arch1.zip/readme1.txt", "Hello world!");
Binary and text files

By default Artisteer treats all files as binary sending the unique IDs instead of the actual content to the script.

If you want the script to receive the actual content of a file, specify the file type through the dataFiles attribute in the options.xml file. For example:

dataFiles="css,js,html,txt,php,xml"
FileManager reference

Each object of FileManager type emulates a file system.

Function nameDescription
append(path, content)Appends a content to the end of the file
copy(src, dest)Copies a file or directory within the current object
copyTo(src, destFileManager, dest)Copies a file or folder (recursively) to another FileManager object
createArchive(path, type)Creates an archive. Supported "type" parameter values: zip, gz, bz
createDirectory(path)Creates a directory in the specified path
enumerate(path)Returns the list of files and directories in the specified path (not recursively)
enumerateRecursive(path)Returns the list of files and directories in the specified directory and its subdirectories (recursively)
exists(path)Checks if the file exists in the specified directory
isArchive(path)Checks if the object in the specified path is an archive.
isBinary(path)Checks if the object in the specified path is a binary file.
isDirectory(path)Checks if the object in the specified path in a directory.
isFile(path)Checks if the object in the specified path is a file.
move(src, dest)Moves a file or directory.
read(path)Reads the file content into a string
remove(path)Deletes a file or directory
write(path, content)Writes text to a file

jQuery Extensions

Function nameDescription
outerHTMLReturns the serialized HTML of the element including its descendants.

The structure of content.xml

The content.xml file has the following structure:

<site>
  <pages>
    <page name="new-page" >
      <pages>
        <page name="new-page" />
        <page name="new-page-2" />
      </pages>
    </page>
    <page name="new-page-2" />
  </pages>
  <posts>
     <post name="new-post" />
     <post name="new-post-2" />
  </posts>
  <sidebars>
    <sidebar name="sidebar1">
      <blocks>
        <menuWidget name="art_vmenu-1" />
        <block name="text-1" />
      </blocks>
    </sidebar>
    <sidebar name="sidebar2" />
  </sidebars>
</site>

The pages and posts have the following structure:

<page>
  <content>some text</content>
  <layout>
    <struct>{content} {content}</struct>
    <contents>
      <content>some</content>
      <content>text</content>
    </contents>
  </layout>
  <pageHead />
</page>