Writing an Add-on

The Basics

My Coloring Book allows you to have up to 3 custom buttons for add-ons. When the button is pressed the program can send the colored image to a script which can then do a variety of things with it, such as posting to a gallery, posting on facebook, entering a contest, and so on.

The button can do one of 3 things...

  • Send the image as raw data (JPEG or PNG) to your script (post="data").
  • Send the image to a script that saves it as a file, and then posts the filename to your script (post="save").
  • Just calls the script without sending the image (post="none").

Before continuing, please read the Custom Buttons article, as it contains detailed information about the settings that drive the add-on.

Preloading

Perloading allows you to open a browser window that will then be used for your add-on. The preloading helps to avoid issues with pop-up blockers.  For most purposes a simple HTML page with a message is sufficient.  The url for preloading is set in the "preload" attribute of the custom button definition.

Presaving the Image

For most scripts it is easier to deal with an image as a file rather than raw JPEG data.  This service is provided by the included "saveimage.php" script.

If you cannot use PHP, you may need to write your own version of "saveimage.php" in your choice of scripting language.  Take a look at what "saveimage.php" for ideas.  Your script will need to do the following...

  1. Generate a unique file name for the file that you are going to save ("saveimage.php" uses a combination of IP address and current time).
  2. Open a file.
  3. Do a base64 decode on the "data" from your POST variables, to get the binary version of the JPEG or PNG data (the type of data is indicated by the imgType POST variable).
  4. Write the binary data to your file.
  5. Close the file.
  6. Output the name of the file. This should be the ONLY information your script outputs, as this is what is passed back to the coloring book.  The coloring book then passes that name to your add-on script.

To change the script used for presaving, edit the "saveUrl" attribute in the settings in your "config.xml" (see General Configuration for more details).

Working with raw data

If you use the post="data" option then your script will receive raw image data (JPEG or PNG) that has been base64 encoded, in the "data" field of the  POST variables.

Your script will generally need to do a base64 decode to get the raw image data that can then be saved to a file or manipulated in some other way.

Working with presaved data

If you use the post="save"option then the program calls your presave script first, and then passes the name of the save file to your main add-on script in the "name" field of the POST variables.

Other POST variables

page - The name of the coloring page which was being colored.

imgWidth - The width in pixels of the image.

imgHeight - The height in pixels of the image.

imgType- The mime-type of the image data/file. Either "image/jpeg" or "image/png".

Size of Image

Depending on what your script does you may want to scale the original image.  To reduce overheads it's best to do this on the client-side.

Scaling is controlled by the pixels attribute of your custom button.  You can leave it blank and no scaling occurs, or you can set a percentage scaling, or set a size for the longest side.  More details can be found in the Custom Buttons article.

Base64 decoding

When using raw image data the data is base64 encoded.  If you are using post="data" or writing your on version of "saveimage.php", you will usually need to decode the data to it's binary form.

In PHP this is easily done with the base64_decode function.

For ASP.NET you use System.Convert.FromBase64String.

For Perl, use MIME::Base64::decode.

ASP (classic) does not have a built in implementation, but there are many examples on how to do it on the internet.