Net Imaging. Developer's guide.

Contents

	Location
How to place the applet on a web page.	this file
How to implement the saving script	this file
How to accept images with a predefined size	this file
How to create the image's thumbnail	this file
How to automatically delete image files	this file

Customization and localization	this file
Additional applet's parameters	this file
Compatibility notes	this file

The product's website	web

How to place the applet on a web page.

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

<applet width="640" height="480" codebase="./applet/" archive="imaging.jar" code="Main.class">
  <param name="load" value="myimage.jpg">
  <param name="save" value="save.php">
</applet>

The attributes width and height can be set according to your page design but must define enough area to include all the applet controls. The attribute codebase should point the applet's location (the file "imaging.jar") and can be both absolute URL or relative to the current HTML page, for example: codebase="../applet/imaging.jar"

All the applet parameters specified by tags <param > are optional but to be useful the applet needs at list two of them:

load - specifies URL of any JPEG or GIF image at your server. The image is loaded when the page is opened. If the parameter is not specified the applet loads nothing.
save - specifies URL of a server side script which can process file uploads. When the user presses the button the applet requests this script to upload the resulting image to the server. You can implement such script in any server-side language like: PHP, ASP, JPS, Perl, etc. If the parameter "save" is not specified the "save" button is disabled.

The section Additional applet's parameters describes others parameters which allow to control the user's interface, apply some image constraints, etc.

How to implement the saving script

The applet request

When the user presses button, the applet uploads the image to the server requesting the script specified by the paramater "save".
The script request looks as if it's made by the following HTML form:

<form method="post" action="save.php" enctype="multipart/form-data" >
    <input type="file" name="image">
    <input type="text" name="width">
    <input type="text" name="height">
    <input type="submit">
</form>

The image is passed as the value the field image. Along with the image itself the applet posts the image's width and height.

Response of the saving script ( Please read it carefully! )

Since the save script is requested by the applet, 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. But you may output special control commands which allow you to redirect the browser to another HTML page or display a message dialog. The command(s) should be sent as plain text in the following form:

#COMMAND=parameter

Output example 1:

#SETDOCTAG=_blank
#SHOWDOCUMENT=confirm.html

After accepting such command sequence the applet opens the page confirm.html page in a new window.

Output example 2:

#SHOWERROR=Can't save the image file.

After accepting this command the applet displays the message dialog: "Can't save the image file."

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

Command	Applet's action
#SHOWDOCUMENT	The browser opens a new document. The parameter is the document's URL. The URL must be either absolute or relative to the saving script.
#SETDOCTAG	The parameter is a target frame for the document to be opened by #SHOWDOCUMENT command. This command must be sent before #SHOWDOCUMENT to have an effect. If no target frame is specified the newly loaded document replaces the applet's page.
#SHOWMESSAGE	The command parameter is displayed as a message dialog.
#SHOWERROR	The same as #SHOWMESSAGE but the message dialog is error decorated.
#SHOWSTATUS	The parameter is displayed in the browser's status line.

You may 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 those order they have been output.

See the example scripts: save.asp, save.php, save.jsp in corresponding directories.

How to accept images with a predefined size

If you need to accept the user's images with a predefined size, for example 80x60, specify the following applet parameters:

    <param name="scaleto" value="80,60">
    <param name="proportion" value="8,6">

The parameter scaleto asks the applet to scale the image to the specified size. The scaling is performed just before the upload, invisibly for the user, and regardless of the current image size.

The parameter proportion constraints the image proportion during the processing. If it's specified the crop box keeps the specified proportion and the user can't upload images if their side ratio differ from the specified one. This constraint allows to avoid proportion distortions while final scaling.

It's also recommended to specify a minimal image size to avoid rough image pixalization while scaling. See the section Additional applet's parameters for more details about the constraint parameters.

How to create the image's thumbnail

The applet is able to produce the image's thumbnail which is uploaded along with it's master image. To obtain the thumbnail you have to specify a frame the thumbnail should be fitted in. For example:

    <param name="thumbnail" value="40,30">

In that case the applet creates the image's thumbnail which width is less then or equal to 40 and height is less then or equal to 30. The upload request to the saving script looks as if it is made by the following form:

<form method="post" action="save.php" enctype="multipart/form-data" >
    <!-- master image fields -->
    <input type="file" name="image">
    <input type="text" name="width">
    <input type="text" name="height">

    <!-- thumbnail image fields -->
    <input type="file" name="thumbnail">
    <input type="text" name="thumbnail_width">
    <input type="text" name="thumbnail_height">

    <input type="submit">
</form>

That is the thumbnail is uploaded along with the main image via the field "thumbnail"; and the actual thumbnail size is passed via the fields "thumbnail_width" and "thumbnail_height".

How to automatically delete image files

Let's say you need to use an image file only once, for example to load the original use's file to the applet. After that those file is not required. In that case you may do the following:

Create a server side script which reads the image file, outputs the read data it as the response, and erases the file.
Point this script as the value of the applet's parameter "load" instead of the image's URL.

Customization and localization

Visible buttons

You can specify what buttons are available for the user. Use the parameter visible_buttons for this purpose.

Button icons

You can replace the button icons with your own. For that create a directory and put your icons into it, then name your icon files according to the names of the standard applet icons. You can find them in the directory "applet/images". Then open the resource description file "resources.txt" and set the parameter "imagedir" so it point to the directory with your icons (relative to "imaging.jar").

Text messages and labels

The applet includes some text resources: labels, messages, hints. You may customize these text strings; for example translate them to another language. To perform such customization you have to:

Make a copy of the file resources.txt located in the applet directory.
Rewrite messages in this copy. Attention! Each non ASCII character must be performed as \uXXXX, where XXXX is the character's unicode.
Point the new file as the value of the parameter "resources". For example: <param name="resources" value="german.txt">

You can create several resource files and point an appropriate one depending on the current language context.

Additional applet's parameters

In addition to the parameters save and load the applet supports the following parameters:

parameter name	parameter values and their meaning	default
User's interface control parameters
visible_buttons	Allows to specify what buttons at the top panel are visible. The parameter may contain the following words (delimited by comma) save,resize,crop,cclockw,clockw,fliph,flipv,vars,undo,redo,zoom for example: <param name="visible_buttons" value="save,resize,crop,undo,redo,zoom">	all the buttons are visible
bgcolor	Backgound color of the applet. Must be specified as #RRGGBB	#C0C0C0
resources	URL of the resource file. See Customization and localization for details.	resources.txt
zoom	Allows to set the initial zoom value. You can set any value from the listed in the Zoom combo box. To specify zoom "Fit in Window" set the parameter 0.	Fit in Window
select	Allows to display the selection rectangle at startup. The parameter's permits three value formats: x,y,width,height. For example: <param name="select" value="10,15,150,200"> width,height. For example: <param name="select" value="150,200"> In that case the selection box is placed at the image center. You may also use the keyword "best" as the parameter's value. In that case the applet displays the selection box with size and postion the most appropriate to the image size and constraints (if they are defined). Example: <param name="select" value="best"> Note: if the specified size exceeds the current image size, the selection box is not displayed.	-
Upload control parameters
scaleto	Asks the applet to scale the resulting image to a specific size. Example: <param name="scaleto" value="90,120"> The scaling is performed just before the upload and is invisible for the user. It's recommended to use the parameter in conjunction with the parameter "proportion" which acts at the processing time and allows to avoid proportion distortions at final scaling.	-
thumbnail	Asks the applet to create image thumbnail and upload it along with the image itself. The parameter's value must be width and height of the frame the thumbnail should fitted in. Example: <param name="thumbnail" value="50,50"> Along with the thumbnail the applet posts two values "thumbnail_width" and "thumbnail_height" which describe the actual size of the created the thumbnail.	-
jpeg_quality	Specifies quality of the resulting JPEG file. It's value can be any integer from 1 to 100. If this parameter is specified, the JPEG quality dialog doesn't appear. Thus the user is not able to control the JPEG quality while saving.	defined by the user
scale_method	Allows to specify a scaling method which is used for resize operations and thumbnail production. The value can be one of the following: "default", "smooth", "averaging", "replicate". Example: <param name="scale_method" value="smooth">	the default (usually fastest)
blockunchanged	If the parameter is set the editor prevents the user from saving an unchanged image. The parameter's value can be any text which is displayed while the user tries to save an unchaged image.	any image can be saved
Image constraints parameters If at list one of the constraint parameters is defined the applet displays a special indicator which shows the user if the current image is proper; and if the user tries to upload an improper image the appropriate error message is displayed and the upload action is blocked.
minsize	Defines minimum size of the resulting image. The value must contain width and height separated my comma, for example: <param name="minsize" value="60,80">	-
maxsize	Defines maximum size of the resulting image. The value must contain width and height separated my comma, for example: <param name="maxsize" value="300,400">	-
proportion	Defines width:height proportion of the resulting image. The parameter's value must be two comma separated integers which specify width:height ratio, for example: <param name="proportion" value="3,4"> Caution: Because of integer-valued rounding it's very difficult (and sometimes impossible) to keep the proportion strictly, so the applet maintains this constraint approximately. To control degree of this approximation you can optionally specify the required proportion precision. For example: <param name="proportion" value=" 3,4, 0.03 "> The example specifies that the proprotion 3:4 must be kept no worse then 3%. If no precision is specifyed the default value 0.02 is used.	-

Compatibility notes

Net Imaging was successfully tested with the following browsers: IE4.x, IE5.x, IE6, Netscape 4.x, 6.2 on Windows and Mac platforms.
The tests were performed both for native browser's JVM:s (if such exist) and the Sun's Java Plug-ins (JRE 1.3, 1.4).
Some unavoidable problem with Netscape 4.x was found:

The applet distorts colors while processing and saving in Netscape Navigator 4.x for Windows if it works in 24 or 32-bit color mode.

Regardless of the successful tests the Author is not responsible for correct applet operation with any particular hardware, software platform, and their configurations.