price-banner.png
Price Free Ebook
Have a Question
Five Minute Tour

PLUG-IN EDITOR FAQ

What are Plug-Ins? Why are they needed?

Sometimes the product content in your original data source is not 100% ready for a print catalog. For example, maybe you need to separate the content of one attribute into two attributes, or modify your product names to remove sizing information. Plug-Ins provide a way to transform your data in just about any way imaginable.

Plug-Ins help you avoid managing your content in two places. If the content from your e-commerce system is already 80% ready for print catalogs, then Plug-Ins give you a way to fix the other 20%.

How does a Plug-In work?

The JavaScript contained in a Plug-In is executed for every product that was selected for that catalog. Plug-Ins run before publishing begins. From the point of view of the publishing system, it is the same as if you had modified the data in some other way.

What skills are required to make Plug-Ins? Is any additional training required?

Anyone proficient in JavaScript can easily learn to make Plug-Ins for Catalog-on-Demand. As with any new environment, they should expect to spend a day or two looking at examples, using the test page, and running experiments. We recommend this JavaScript Reference. We are happy to offer support to proficient JavaScript programmers. Sorry, but we cannot train people to become JavaScript programmers.

I am not a JavaScript programmer, but I need a Plug-In developed. What should I do?

We suggest that you use an outsourcing site such as Freelancer.com or oDesk to find a programmer to do the work for you. We are glad to help you write the project description and select an appropriate person. Remember that when hiring a programmer, you are looking for more than technical proficiency. Excellent communications skills are equally important!

Does Catalog-on-Demand provide any Plug-Ins?

Yes, we offer public Plug-Ins that provide general functionality to our customers. Also we will sometimes make a Plug-In to offer a feature that is not yet available through the regular user interface. Furthermore, we create example Plug-Ins to illustrate how they can be used for various purposes. If you need an example of something that is not shown here, please let us know.

How can I test my Plug-In during development?

We offer a test form that lets you enter sample product data. You can then easily run your script against that sample data. It shows the results of the data transformation, as well as error messages. Before using this test form, we suggest that you familiarize yourself with how your data is structured in the Catalog-on-Demand database. This can be done with the Private Data Editor (PDE), documented here.

Once a Plug-In has been developed, how is it used for publishing jobs?

You can select any combination of available Plug-Ins as part of a configuration. Every time a job is run with that configuration, it will execute the selected Plug-Ins.

If I discover that I have introduced a bug into my Plug-In, can I roll back to an earlier version?

Yes, you can save as many versions of the Plug-Ins as you want. It is simple to roll back to an earlier version. There is also a comment field for each version. We recommend that you use this field to note what you changed about each version.

I will be making a Plug-In that will generate results to be used by another Plug-In. Can I control the sequence of execution of my Plug-Ins?

Yes, you can use drag/drop to manage the order in which your Plug-Ins are executed. This is handled on a per configuration basis.

Can Plug-Ins call an external web service, use external files, or access remote data sources as part of their processing?

Yes, this is feasible and we encourage such integration if will help you meet your publishing objectives. However, we first have to check out the service or discuss it with you. We need to be certain that all security, performance, and other potential issues have been addressed. You will not be able to use the service until we have authorized it. We will normally charge one-time development fees for this review and authorization process.

Sounds good. How do I get started making a Plug-In?

Click here for documentation on how to make Plug-Ins. Please contact us if you have any questions or problems.

Do you have examples of Plug-Ins that have already been written and proven to work properly?

Yes, click here for examples. Please let us know if you need an example of functionality that is not similar to something already shown in the list.


How To Make Plug-Ins for Product Data Transformation (DRAFT)

Part I: Introduction

Plug-Ins offer a convenient way to transform your product data before publishing. 

Click here to launch Plug-In Editor. Sign in with the same user ID and password you use for Catalog-on-Demand.

Part II: Making the Plug-In

  1. To make a new Plug-In, click on the New button on the left side.
  2. Enter the name you want to give this Plug-In. You can change the name at any time. However, if you have already assigned the Plug-In to a configuration, you will need to reassign it after changing the name.
  3. Your new Plug-In will appear in a list on the left side.

Part III: Basic Info

A. Description

The description field should be used to explain the purpose of your Plug-In. It will be visible on the Miscellaneous page where users select which Plug-Ins they want to use. The description can be formatted with bold, italic, font size, bullets, etc. 

B. Image

An image can be helpful to illustrate the purpose and results of your Plug-In. You can create your image in any way you like. Use drag/drop or click on the box to upload your image.

Part IV: Javascript code

Anyone proficient in JavaScript can easily learn to make Plug-Ins for Catalog-on-Demand. As with any new environment, they should expect to spend a day or two looking at examples, using the test page, and running experiments. We recommend this JavaScript Reference. We are happy to offer support to proficient JavaScript programmers. Sorry, but we cannot train people to become JavaScript programmers.

A. Startup script

This field is for Javascript that needs to run only once per publishing job. 

B. Product script

This field is for the Javascript that will run once for each product that has been selected for the publishing job.

C. Number of times executed

This value is not editable. It shows the number of times the Plug-In has been used in publishing jobs.

D. Check syntax

The "Check syntax" button will parse and compile your Javascript. Any errors will be listed.

E. Test

The "Test" button will open a test page. You will then be able to enter sample product data and run your scripts to see the results.

Part V: Version info

For your convenience, you can easily save each version of your Javascript. This is particularly helpful if you have implemented some changes or enhancements that may or may not work as you expected in publishing. It there are problems with a newer version, you can easily roll back to a previous version.

To create a new version, click on the button at the top labeled "Save as new version". The number in parenthesis refers to the new version number. We recommend that you post comments for each version. This field is found on the tab labeled "Version info". This tab also lists all previous versions and their corresponding comments. 

Part VI: Testing

Clicking on the Test button will open a page that allows you to test your script against sample data. You will see that your scripts have been automatically copies to the corresponding fields on the test page. You click on the Execute button to cause the script to run with your sample data. Test results are shown below the Execute button. 

You can run as many tests as you need. It is usually helpful to tweak your scripts as you work your way through various samples. You can then copy your scripts back to the Plug-In page, to the tab labeled Javascript code.

In order to understand the meaning of all the product data fields listed on the test input form, we recommend that you first study your data in Private Data Editor (PDE). The same field names are used in the test input form as in PDE.

Examples of Plug-Ins

We will regularly add to this list of example Plug-Ins. Let us know if you need to see an example of a Plug-In for handling a requirement that is not listed here.

Ex. #1 — Add color to attribute values with a specific label

What it does

This script looks for an item (sku) attribute with the label of "Special Price". If found, it sets the color of that attribute to red. Note the use of the span tag to apply the color. 

Startup script

none

Product script

for(var i = 0; i < Items.length; i++ ){
  if ( Items[i].ItemAttributes['Special Price'] )
  Items[i].ItemAttributes['Special Price'] = '<span style="color: red;">' + Items[i].ItemAttributes['Special Price'] + '</span>' ;
}

Ex. #2 — Add color to attribute values where the label is in a list

What it does

This script looks for an item (sku) attribute with a label that is in the list. If found, it sets the color of that attribute value to red. 

Startup script

// Define the list of item attribute labels to colorize
var itemAttrLabelsToColorize = [
  "Special Price",
  "Something Other",
  "Something Else"
];

Product script

// colorize select item attribute values
// - provided there are items and there is a list of attribute labels
if( Items.length > 0 && itemAttrLabelsToColorize ){
  itemAttrLabelsToColorize.forEach(
    function( itemAttrLabel ){
      for( var i = 0; i < Items.length; i++ ){
        if( Items[ i ].ItemAttributes[ itemAttrLabel ] )
Items[ i ].ItemAttributes[ itemAttrLabel ] = '<span style="color: red;">' + Items[ i ].ItemAttributes[ itemAttrLabel ] + '</span>' ;
      }
   }
 );
}

Ex. #3 — Remove HTML formatting

What it does

This script removes all HTML formatting from the product description.  

Startup script

/**
* stripTags
* @param mixed input
* @parm mixed output
*/
function strip_tags( str){
return str.replace(/<\s*br\/*>/gi, "\n")
.replace(/<\s*\/*.+?>/ig, "")
.replace(/ {2,}/gi, " ")
.replace(/\n+\s*/gi, "\n\n")
.replace(/^\s+|\s+$/g,'');
}

Product script

ProductDescription = strip_tags( ProductDescription );

Ex. #4 — Round the values of a particular attribute

What it does

This script looks for item attributes labeled Weight. If found, it rounds the value to one decimal place. 

Startup script

None

Product script

if (( ProductAttributes[ "Weight" ] ) && !(Items[ 0 ].ItemAttributes [ "Weight" ])) {
Items[ 0 ].ItemAttributes [ "Weight" ] = ProductAttributes[ "Weight" ]
ProductAttributes[ "Weight" ] = ""
}

for(var i = 0; i < Items.length; i++ ){

if( isNaN( Items[ i ].ItemAttributes [ "Weight" ] ) ){
// not numeric - pass it
  } else {
    // round it to 1 decimal place; ensure proper rounding to the closest rounded
    Items[ i ].ItemAttributes [ "Weight" ] = parseFloat( Items[ i ].ItemAttributes [ "Weight" ] ).toFixed( 1 );
    }
}

Ex. #5 — Replace numerical attribute values with an image

What it does

This script replaces numerical values in the product attribute "Gebäudeanalyse" with a corresponding bar image. 

Startup script

none

Product script

switch (ProductAttributes["Gebäudeanalyse"]) {
case "1":
var url="abc"
break
case "2":
var url="def"
break
case "3":
var url="ghi"
break
case "4":
var url="http://app.catalog-on-demand.com/images/temptest/bar300x20.jpg"
break
default: url="something";
}

ProductAttributes["Gebäudeanalyse"]='<img src="' + url + '";>'

Ex. #6 — Price in European format

What it does

Uses comma (,) as decimal separator. and the dot as the thousands separator.

For example: 1.234,56 

Startup script

/*
 * Javascript E-Commerce By Cal Henderson
 * http://www.iamcal.com/publish/articles/js/ecommerce/pdf/
 *
 * price - any numeric or string which is not isNaN()
 * g_decimal - decimal separator, null or empty (default: '.')
 * g_thousand - thousand separator, may be null or empty (default: '')
 * g_currency - currency symbol, may be null or empty (default: '')
 *
 * returns formatted price of price is a numeric or a string which is not isNaN(),
 * empty string otherwise
*/
function format_price( price, g_decimal, g_thousand, g_currency ){
  if( isNaN( price ) ) return '';
  if( !g_decimal ) g_decimal = '.';
  if( !g_thousand ) g_thousand = '';
  if( !g_currency ) g_currency = '';
  var s = new String( Math.round( price * 100 ) );
  var pence = s.substr( s.length - 2 );
  var pounds = s.substr( 0, s.length - 2 );
  if( pounds.length > 3 ){
    var out = pounds.substr( pounds.length - 3 );
    pounds = pounds.substr( 0, pounds.length - 3 );
    while( pounds.length > 0 ){
      out = pounds.substr( pounds.length - 3 ) + g_thousand + out;
      if( pounds.length > 3 ){
        pounds = pounds.substr( 0, pounds.length - 3 );
      }else{
        pounds = '';
      }
     }
    pounds = out;

  }
  if( pence.length == 0 ) pence = '00';
  if( pence.length == 1 ) pence = '0' + pence;
  if( pounds.length == 0 ) pounds = '0';
  return g_currency + pounds + g_decimal + pence;
}

Product script

// go through items
for( var i = 0; i < Items.length; i++ ){
  if( !isNaN( Items[ i ].ItemPrice ) ){
    Items[ i ].ItemPrice= format_price( Items[ i ].ItemPrice, ',', '.' );
  }
}

 

Ex. #7 — Strip out embedded image, then insert that image in a new attribute

Problem

We often see situations where an image (such as a warranty image or a certification icon) is embedded in text in an attribute. This usually does not present well in a print catalog. Typically the position and size are wrong.

Solution

  1. Search for the HTML containing that image by looking in the text of each product attribute.
  2. When found: (a) remove that HTML from the attribue value where it was found; and (b) insert the image, properly sized, in a new attribute.

Startup script

// a plug-in that searches for this text in any product attribute
var searchForWarranty = "<p><img style=\"float: right;\" src=\"http://www.xyz.com/media/warranty.jpg\" alt=\"\" width=\"200\" height=\"150\" /></p>";

Product script

//Product script - looks for target and updates attrs if (and only if ) found
var pos;
for( var attrName in ProductAttributes ){
  var attrValue = ProductAttributes[ attrName ];
  if( attrValue && ( pos = attrValue.indexOf( searchForWarranty ) ) >= 0 ){
    ProductAttributes [ "Warranty" ] = "<img style=\"height: 0.5in;\" src=\"http://www.xyz.com/media/warranty.jpg\" />";
    ProductAttributes [ attrName ] = ProductAttributes [ attrName ].substring( 0, pos ) + ProductAttributes [ attrName ].substring( pos + searchForWarranty.length );
  }
}

 

 

 ###