ImageMARK. Developer's guide

ImageMARK Developer's guide

	Location
How to place the applet on a web page.	this document
How to save the picture and comments.	this document
The applet parameters	this document
JavaScript functions	this document
Setting your cliparts	this document
The resource file	this document
The product's home page	web

How to place the applet on a web page

The minimal HTML code to place the applet on a web page might look as follows:

<applet name="imagemark" width="700" height="570" codebase="./applet/" archive="imagemark.jar" code="Annotator.class">
  <param name="picture" value="myimage.jpg">
</applet>

The attributes width and height can be set according to your page design but should provide enough room for the applet's GUI.
It's recommended to not set width less then 700.

The attribute codebase must point to the applet's directory on the server.
NOTE: sometimes developers omit the codebase and merge its value with the attribute archive. This is wrong practice. Don't remove the atribute codebase.

The attribute name sepcifies a name that can be used to refer the applet in JavaScript.

The applet parameters are specified by the tags <param>. All the parameters are optional but to be useful the applet needs at least one parameter picture which specifies the picture on the server that should be opened at startup and commented.

The comprehensive list of the parameters can be found here

How to save the picture and comments.

How to trigger saving

To save the image to the server you have to call the applet's method submit(save_script_url) in JavaScript.

For example:

<applet name="imagemark" width="700" height="570" codebase="./applet/"
				archive="imagemark.jar" code="Annotator.class">
  <param name="picture" value="myimage.jpg">
</applet>

<form>
   <input type="button" value="Save" onclick="document.applets['imagemark'].submit('save.php')">
</form>

This code displays the applet and a regular HTML button "Save". When the user presses the button JavaScript calls the applet's method submit passing in URL of your server side script which receives the modified files on the server.

How to implement server side script

When you call submit('your_script') the applet makes a regular upload request to the server.
The request looks as if it's made by the following HTML form:

<form method="post" action="your_script" enctype="multipart/form-data" >
    <input type="file" name="picture_and_annotation">
    <input type="file" name="annotation">
    <input type="file" name="thumbnail">
    <input type="text" name="picture_width">
    <input type="text" name="picture_height">
    <input type="submit">
</form>

Actually, the number of fields in the request depends on the save options and the user's actions.
For example, by default the applet doesn't save the picture_and_annotation if the picture
has not been changed and no annotation has been put on it.

The full list of fields that can be included in the request is the following:

`picture`	JPEG image file containing the picture without comments.
`annotation_image`	PNG image file containing the comments.
`picture_and_annotation`	JPEG image file containing the picture and comments on it.
`annotation`	comments in XML format. This file can be loaded for editing annotation with the parameter annotation.
`picture_width`	width of the picture in pixels.
`picture_height`	height of the picture in pixels.
`thumbnail`	JPEG image file containing preview of the picture with comment.

Save options

You can specify what fields should be included in the save request. For that you have to specify the second optional parameter of submit method:

<script>
    var options = 'picture:yes; annotation:yes; annotation_image:yes;'+
                  'thumbnail:yes; picture_and_annotation:no;';
    document.applets['imagemark'].submit('save.php',options);
</script>

The values of fields options can be yes, no, or question sign ?. If the question sign is used and corresponding file has not been changed its field is not included in the request. For example: if you specify picture:? and the picture has not been changed it's not saved.

The response of the saving script

The script is requested from the applet and the script's response (output) is returned to the applet as well (not to the browser!). The applet doesn't understand HTML content and has no way to display it, so you mustn't output HTML in your script as usual. Instead you should output special control commands which allow you to redirect the browser to another HTML page or display a popup message. The command(s) should be sent as plain text in the following form:

#COMMAND=parameter

Output example 1:

#SHOWDOCUMENT=confirm.html

Upon receiving this command the applet opens the page confirm.html.

Output example 2:

#SHOWERROR=Can't save the image file.

Upon receiving this command the applet displays the popup message: Can't save the image file.

The following table lists all the commands that the applet can process:

Command	Applet's action
`#SHOWDOCUMENT`	The browser opens a new document. The parameter is the document's URL. The URL might be either absolute or relative to the saving script.
`#SETDOCTAG`	The parameter is the target frame for the document opened by `#SHOWDOCUMENT` command. If this command is not specified the document pointed by `#SHOWDOCUMENT` replaces the current page.
`#SHOWMESSAGE`	The command parameter may be any text which is displayed in a popup dialog.
`#SHOWERROR`	The same as `#SHOWMESSAGE` but the dialog is error decorated.
`#JAVASCRIPT`	The command `parameter` is executed with javascript function `eval` in the context of the current page. To use this command the developer should set the <applet> attribute `mayscript`. Otherwise the applet can't communicate with javascript.
`#SHOWSTATUS`	The parameter is displayed in the browser's status line.

You can output any number of the commands but keep in mind that:
- each command must be placed on a separate line (i.e. separated by CRLF or LF characters)
- the commands are processed in the order they have been output but the command #SHOWDOCUMENT which is executed at the very end.

The applet parameters

`picture`	URL of the image to be commented. The image can be in JPEG, PNG, or GIF format.
`annotation`	URL of the XML file with comments
`keep_original_image`	If this parameter is set to `true` the user may not change the picture (crop, rotate, etc.). If this parameter is set to `false` the user is allowed to change the picture. If this parameter is not specified the applet doesn't allow to change the picture if it has loaded an exiting annotation.
`maximum_image_size`	If the user can change the pictue this parameter specifies the maximum size of the picture and annotation. The picture will be fitted in the specified frame after each operation (crop, rotate). The frame is specified as `width,height`. If this parameter is not specified the image is fitted in the applet's window. If the applet keeps the original image this parameter is ignored.
`thumbnail`	Specifies bounding frame for the output picture thumbnail as `width,height`.
`resources`	Specifies URL of the resource file. The URL should be either absolute or relative to the applet's location (not the enveloping HTML page).
`bgcolor`	Specifies the background color of the applet. The value should be specified as #RRGGBB.

JavaScript functions

The applet supports several functions which can be invoked in JavaScript. To invoke a function use the following javascript statement:

document.applets['imagemark'].somefunc(params);

It's assumed here that the applet has the attribute name="imagemark".
The following functions are supported:

`loadPicture(pictureURL,annotationURL)`	Loads a new picture and annotation. The parameter `pictureURLUrl` points to the picture file on the server. The parameter `annotationURL` points to the annotation file on the server. The parameter `annotationURL` is optional and might be either `null` or empty string if no annotation should be loaded. The `urls` can be either absolute or relative to the current page.
`loadAnnotation(url)`	Loads an annotation on the existing background image. The parameter `url` points to an annotation file on the server saved earlier. The `url` can be either absolute or relative to the current page.
`submit(url,options)`	Saves the annotation to the server. The parameter `url` points to the saving script. The parameter `options` describes save options.
`addSubmitField(name,value)`	Adds a custom field to the submit request. This function should be invoked before submit. To add several fields call this function sevela times (for each custom field). After each submit all custom fields are removed.
`showProgress(message)`	Allows to display any progress message on the applet's area. To turn off the message call this function with empty message (string).

Setting your cliparts

To set up custom cliparts put them into the file cliparts.zip located in the applet's directory. Then list you clipart files in the file cliparts.txt (which is located inside cliparts.zip).

If you have opened the applet before updating cliparts.zip on the server don't forget to reload your browser by closing all it's windows.

Resource file

The resource file allows customizing the applet's labels and messages, for example translate them to another language. The example resource file resources.txt can be found in the applet's directory. To create and use your custom resource file:

Translate the messages in resources.txt
Specify your file with the applet parameter resources, for example:
<name="resources" value="resources.txt">

Note The file should be saved in Latin-1 encoding. If the language you're translating to requires encoding other then Latin-1 use Unicode characters written in the format \uXXXX.