Webshop plugins

Ontwikkel en beheer uw eigen webshop-plugins binnen SW-Retail. Deze handleiding biedt u alle tools om HTML, CSS en JavaScript te integreren, instellingen te configureren en uw plugin te publiceren.

Webshop plugins start

The plugin system allows you to include HTML / CSS / Javascript using the SW-Retail templating system in a customer's website and gives numerous options.

Create a cms block that can be used in the cms {block:plugin:myplugin}
Create a simple user interface in the SW-Retail settings for filling in parameters like an API-Key, username or to define some switches for enabling / disabling certain functionality of your plugin
Publish your plugin on the SW-Retail plugin store
Override most built in HTML / CSS generation of the webshop system
Include Javascript libraries etc.. etc..

Also we allow you to charge a one time and monthly fee to the customer. This fee is automatically paid out to you by the SW-Retail platform once you are a designated partner.

My first plugin

To create your first plugin follow these two steps:

Obtain a partner environment. You can contact the SW-Retail helpdesk for this (helpdesk@swretail.nl or use the chat). If you have a partner environment, you can use it to create a plugin.
To create a plugin go to the plugin editor, and add one. The plugin is automatically available on your partner system without having to install it or put it on active. This allows you to test your plugin on your partner environment. It will also be visible in your partner webshop.
Make sure you have filled out all the fields "Short description" / "Description of the plugin" / "Help for this plugin" and include a sample image.
When you are satisfied with the result, you can set the plugin to active. You can also then ask the SW-Retail helpdesk to approve your plugin. Once your plugin is approved it will be available on the plugin store.

Considerations for your plugin

If there are legal implications (GDPR / AVG) for your plugin you have to let the customer know in the Description of the plugin field.
Make sure you do not accidentally have cookies placed by third parties that you include software of.
Make sure all rights are waived, that there no copyright claims from 3rd parties etc... If there is we will deactivate the plugin.
Make sure when customers have questions they can reach you.
SW-Retail does not support your plugin, you have to do that yourself. Tickets opened at your helpdesk for the plugins will be closed with a reference to you.
Do not include your own tracking code for plugin usage. You can see plugin usage in the SW-Retail platform.
Make sure you prefix your variables according the scheme {partername_pluginname_variablename} This will minimize variablename collisions.

How do you get paid

SW-Retail will incurr the fee and pay it to you. Please take note that all plugins are free to try the 1st month. We will charge the one time costs at the beginning of the 2nd month and the monthly fee at the end of the month.

The plugin editor

On the plugin editor,there are a couple of places where you can have your plugin code injected. Plugin will be injected into 3 template variables and / or in blocks when defined.

For variables to work you have to activate the templater using the {$} tags or {templater_start} / {templater_stop}

Also make sure you deactivate the templater again to prevent javascript and stylesheets to be parsed as template code.

Theme requirements

The theme of the customer that wants to use your plugin must adhere to the standard plugin rules.

Basically, the theme must have the following variables in the right places in the theme.


{swretail_plugin_place_head}
{swretail_plugin_place_top}
{swretail_plugin_place_bottom}
The themes in the SW-Retail store all adhere to this.

All plugins are injected into these 3 variables. If there are multiple plugins installed, data for the variables will be concatenated. You cannot make assumptions upon which order the plugin code is injected into the theme. Therefore you must make sure your code can hande that.

For example, there is a plugin1 and a plugin2 which both have a script to be included into the swretail_plugin_place_head. The system will then take the code of plugin1 and plugin2 and concatenate these values into swretail_plugin_place_head.

As said before. In order to have template variables evaluated you have to start / stop the templater. You can do this using {$} {$} .

A basic overview of the HTML involved.


<html>
<head>
	<stuff>
	<stuff>
	{swretail_plugin_place_head}
</head>
<body>
	{swretail_plugin_place_top}
	<stuff>
	<stuff>
	{swretail_plugin_place_bottom}
</body>
</html>

Additionally, you can have extra template code being executed _before_ the SW-Retail templater engine will run. Here you can define extra variables, using {define_c:variable:value} statements.

Blocks

There is also an option to have your plugin create a block that can be used in the CMS by the customer to display content that the plugin generates. {block:plugin:__yourpluginblockname__}

Override SW-Retail defined blocks

You can override an SW-Retail defined block to alter visual appearance and behaviour of some default blocks. You can find the default blocks here:

Plugins come from the same kind of file:

Appending and prepending a block

It is also possible to append / prepend an existing block. This is usefull for even more finegrained manipulation. If you append or prepend and the block did not exist already the block will be defined.

{block_append:[blockname]:[clear]}
{block_end}

{block_prepend:[blockname]:[clear]}
{block_end}

Javascript

You can off course include your own javascript files. But sometimes you could come to a point where it is deemed neccesary to override SW-Retail javascript. We recommend not to do this. But if you do please only change the prototype you, and do not override the whole javascript file as this will cause problems in the future for sure! In general:

Changing the SW-Retail javasscript will cause you trouble for sure!

So extending OK, changing -> NOT OK

Render a userinterface

After the customer installs your plugin or theme, they probably need to configure it someway or another. It is possible to present a userinterface to the user from the Configuration -> Webshop -> Plugin tab or Uiterlijk tab. If your plugin/theme is installed, it will appear there and present the user interface you defined.

Make sure you prefix your variables according the scheme {partername_pluginname_variablename} This will minimize variablename collisions

Currently the following elements are supported:

Text field
Multitext field
Colorpicker
Checkbox
Combobox (selectbox)
Cmsselector
Image selector
Link selector

More fields will be added in the future.

Syntax

To declare a field {field:new:__name_of_parameter__} _name_of_parameter_ will be the name of the parameter in the templatingsystem.

Next you can define the attributes. You do this by using {field:attribute:value}

type - the type of field, any of: text (default), multitext, checkbox, colorpicker, image, linkselector (for selecting a link), cmsselector (for selecting a cms page), articleselector (for selecting articles)
datatype - the datatype of the field: text (default), money, integer, number
width - the width in the user interface, any number between 1 and 12, default 6
label - the label of the field, start with languagecode:text
label_extra - subtekst under the label of the field for some extra explanation about what the field does, start with languagecode:text
default - the default value of this variable (make sure it is the right datatype)
option - for a selectbox only :value:Visible value
group - can be used to put variables together in groups when you use custom fields in your theme. Valid groupnames are fonts,colors,article_overview,article_overlay,article,menu_options, z_custom_css,z_custom_defs and will group your fields onderneath the according group of settings for the theme under Instellingen -> Webshop -> Uiterlijk

When finished declaring a {field_end} must be given.

For an image, to use the variable you will have to do a before it is usable(!).

Example declaring a text field


{field:new:myplugins_api_key} 
	{field:type:text}
	{field:label:nl:Api Key of my plugin}
	{field:label_extra:nl:This is the api key needed for the plugin}
	{field:width:6}
{field_end}

Example declaring a combobox / selectbox field


{field:new:myselection}      
	{field:type:combo}
	{field:label:nl:Choose something}
	{field:label_extra:nl:Make your choice}
	{field:option:nl:value1:Option 1}
	{field:option:nl:value2:Option 2}
	{field:option:nl:value3:Option 3}
	{field:default:value1}
	{field:width:6}
{field_end}

Prefixing

Make sure you prefix your variable names with something unique to your plugin or theme to avoid variable collision with plugins / swretail variables etc.. !

Block definition

To define a block you can use the following template.

{$}      
{block_declare:the_name_of_my_block:clear}
		Your html and CSS and Javascript etc.. etc..
		{using_my_defined_variable}
		
{block_end}
{$}

OR, you can append a block (i.e. put something at the end of an already existing block)

{$}      
{block_append:the_name of the block you want to append:clear}
		Your html and CSS and Javascript etc.. etc..
		{using_my_defined_variable}
{block_end}
{$}

You can also prepend a block using {block_prepend}

Important to know, you cannot, as in PHP for example, start the templater, declare the block, deactivate the templater, put stuff in, start the templater again for closing the block. Unfortunately this means you have to escape all { and } occurences using \ within the block. If the templater is not started your block will not be recognised.

Javascript callbacks

Sometimes when developing a plugin you have to changed something in the flow of the software. For this you can use javascript callbacks. There is a callback object that you can use to register your own callback functions. By registering functions it is guaranteed that when multiple plugins are installed all callbacks are called.

To register your function you can use

swShopCallback.registerCallback("callbackname",your_plugin_function)

To find the callbacks that are available, you can lookup all member functions in the swShopCallback object. The names of the members speak for themselves (hopefully).

Example that gets run when pressing the "add to cart" button:

function my_plugin_function()
{
	console.log("Hello world!");
};

swShopCallback.registerCallback("afterCartChanged",my_plugin_function);

Or, alternatively

swShopCallback.registerCallback("afterCartChanged",function(){console.log("hello world!");});

Hosting external files

It is possible to host external files (like javascript / css etc..) on the SW-Retail cdn. For this you need to request a CDN directory, you can request this via our helpdesk. Once created, your SFTP environment will have a /cdn folder in which you can put files (and subdirectories) that will be hosted on the CDN for fast content delivery. You can hardcode in your plugin to this CDN location. The url of the content will be

https://cdn.swretail.nl/<your cloud environment name>/<everything under the cdn folder on your sftp account>

Only use this CDN for serving files for SW-Retail webshops. It is a violation of our terms and conditions if you do otherwise and we will remove files when this happens. Do not serve video and / or any other files >500kb via the cdn.