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:
- Artisteer
- Google Chrome, Apple Safari or Mozilla FireFox with Firebug (Google Chrome is recommended)
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:
- Start Artisteer
- Select File -> Develop -> New Plugin in the Main Menu
- Type the name of your plugin and click "OK".
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:
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:
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:
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:
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, '');
}
}
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:
- Select File –> Develop -> Debug in Browser
- Open Developer Tools in Browser
- Select export.js from the list of scripts
- Add a breakpoint to the first line of the build() function
- Switch to the Console tab and enter "build()" to execute the script
- Built-in debugger will stop on this line
- Use Step into, Step over, Step out commands and Watch Expressions to debug your script.
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:
- Shorter plugin development cycle
- Less coding
- Easier development and maintenance
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:
- Go to Artisteer and select Menu File –> Develop –> Run Tests. Artisteer will suggest that you download the test design set from our website.
- Click "ОК" to download the test designs.
- Shortly after that a web browser will be launched to run your plugin tests.
The tests perform the following actions:
- General Tests: Calls the build() function for all possible option combinations from the options.xml file and test designs
- Static Code Analysis: Checks JS scripts using JSHint utility
- 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.
You can use the following jQuery selectors to select HTML elements by specific class names:
- .art-header
- .art-sidebar1
- .art-sidebar2
- .art-hmenu
- .art-vmenu
- .art-content
- .art-footer
- .art-block
- .art-vmenublock
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:
Name | Object Type | Description |
options | object | Options selected by a user in the Export dialog and an additional information such as Artisteer version, operation mode (full or demo), etc. |
template | FileManager | User files from the "template" folder |
content | FileManager | Contains the post/page images and content.xml file (with HTML code for pages, articles, blocks, footer, etc.) |
design | FileManager | Contains Artisteer-generated design files. |
result | FileManager | Holds 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 name | Description |
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 name | Description |
outerHTML | Returns 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>