Net Imaging. Developer's guide.

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 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 might be set according to your page design but you should provide enough room for the applet controls. The attribute codebase should point to the applet's directory specified either as it's absolute URL or relative to the current HTML page, for example: codebase="../applet/"

The applet parameters are specified by the tags <param>. All the parameters are optional but to be useful the applet needs at least the two:

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 request looks as if it's made by a regular HTML upload form like the following:

<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! )

#COMMAND=parameter

Output example 1:

#SETDOCTAG=_blank
#SHOWDOCUMENT=confirm.html

Upon receiving this command sequence the applet opens the page confirm.html page in a new window.

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:

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 the order they have been output.

See the example scripts: save.asp, save.aspx, save.php, save.jsp in the directories ASP, ASP.NET , PHP, JSP respectively.

How to accept images having a predefined size

Say you wish all the uploaded images to have a predefined size, for example 80x60. In that case specify the 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 at final scaling.

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

How to create the image's thumbnail

The applet can produce the image's thumbnail and upload it along with the 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. It's 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 issued 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>

How to delete image files automatically

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:

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

How to process large images.

Net Imaging can't process very big image files because applets are not provided with enough memory resources. Typical image size maximum is about 3M pixels (for example 2048 x 1536). However Net Imaging can scale down big images to a reasonable size while opening them. To allow Net Imaging to scale down big images specify the parameter prescale. The parameter value is the maximum size that is allowed to be opened without scaling. If an image exceeds this size it is scaled down to the specified value. The value should be specified in pixels (or in MEGA pixel with the suffix 'M' after the value).

    <param name="prescale" value="3M">

• Though 3M pixels images do not usually raise memory problems, it is reasonable to reduce image size to a lower value, for example 2M pixels. That improves the applet perfromance considerably.
• If a big image is downloaded from the server it is reasonable to down scale it on the server size to reduce download traffic.

How to print from the applet.

The applet allows to print the displayed image. The print button is hidden by default. Use the parameter visible_buttons to specify the print button explicitly.
Example:

<param name="visible_buttons" value="print,save,crop,undo,redo">

Note: The printing functionality is available with Java Plug-in only. Microsoft's Java (the native engine of IE) doesn't allow applets to print.

Customizing the UI and localization

Colors, fonts and buttons

Using the applet parameters you can specify color and font for the labels and messages and the applet's background color. You can also specify what buttons are visible. Please read subsection Applet appearance in the section The list of parameters for details.

Text messages and labels

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

You can create several resource files and point the appropriate one depending on the current language context.
Several national resource files have been prepared by Net Imaging users: chinese.txt, dutch.txt, french.txt, german.txt, norwegian.txt, russian.txt, spanish.txt.

Custom icons for the buttons

The button icons are kept in the applet's archive imaging.jar. To replace the icons with your own do the following:

1. Unpack imaging.jar with any ZIP utility (imaging.jar is a regular ZIP archive).
2. Replace the image files in the subdirectory 'images' with your own.
3. Pack all the applet files bak to imaging.jar keeping the orginal directory structure.

• You may use icons of different sizes.
• After updating imaging.jar on the server reload your browser to see the changes.
• If you worry about compatibility with Netscape 4.x then also copy your icons to the subdirectory "images" under the applet's directory on the server.

The list of parameters

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

Compatibility notes

Net Imaging was tested with the following browsers: IE4.x, IE5.x, IE6, Netscape 4.7, 6.2, 7.2, Mozilla 1.6, Firefox 1.0. The tests were made for both native browser's JVM:s (if such exist) and the Sun's Java Plug-in (JRE 1.3, 1.4, 1.5). The following issues have been found:

• In some rarely and unknown circumstances the tool buttons on the top panel look black. This can be resolved by removing the transparent color from the button icons (which are implemented as GIF files). For replacing the icons with their custom versions the section Custom icons.
   
  
• The applet distorts the image colors in Netscape 4.x for Windows if Windows is working in 24 or 32-bit color mode. This problem can not be resolved because of some bug in the native Netscape 4.x Java engine.
   
  

An issue after a Windows XP security update

After the Windows XP security update published at the April, 2006 the browsers IE6 and IE7 ask users to click twice on any active content on web pages (applets, Active-X objects, etc..) before allowing to interact with them. To resolve the issue please read this article: http://izhuk.com/docs/ie7fix.html

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

Copyright 2003 - 2008. Igor Zhukovsky www.izhuk.com