ABOUT IM_Manipulation.html (IM_ManipulationSB.html for Sandbox users)

The IMFunctions.inc file contains functions for both primary and sandbox users. However, there are two different html files depending on which applies to you.

You may wish to maintain an uploads directory separately from your final image directory. This way you can keep your originals in a separate place and retain the same filenames for the final images. In the example file, the upload directory remains untouched except for the ability to rename files. You will want to do this to correct for illegal characters, or to otherwise rename files after uploading. (Be smart though... a filename with the following characters: & \ / : will cause a little breakage when uploading.) Manipulated files end up in the images directory where they can be deleted using WebDNA. (It is an immediate delete; there is no "are you sure?" confirmation.) This way, you can experiment with the various ImageMagick functions to refine your own defaults, particularly the defaults for text imprinting.  If you want to to be able to delete from the uploads directory, the code is in there; you just have to uncomment it. 

The example file (needs the two directories images and uploads) was developed for testing IM variables to decide what works best for your particular needs. Or you may wish to use it in whole to handle all of your image manipulation. Or you may wish to take bits and pieces from it, to build your own upload process with more defaults and fewer form elements. Or just use it to understand the process so you can do all of your image manipulation in one click, chaining the functions after you upload the file. 

================
Uploading files: 
Notice that the upload form uses enctype="multipart/form-data" in the <form> tag. This is necessary when uploading files. However, on the resulting page, the formvariable names do not pass through as we usually expect them, so we have to extract the names, then set text variables so that this name/value pair:

Content-Disposition: form-data; name="upload" = t

becomes this:
   upload = t

...which allows us to continue parsing the page using any variables we sent in with the upload form.

The form variable for the file itself is a little different in that it uses "filename" instead of "name", and the value of "filename" is the actual name of the file uploaded (whereas for the example above, the value of "name" is the name of the variable); then the value of that whole thing in turn is the data of the file itself. (Hence the "multipart" in "multipart/form-data".) It's all very confusing, and this element is handled separately, and not turned into a text variable. Refer to the sample page to see how the file is written to the server using [writefile]. 

This is how the file variable is passed:

Content-Disposition: form-data; filename="youruploadedfile.jpg" = <the binary data of the file itself>

Some systems will include the entire path on your HD with the filename. In the IM_Manipulation.html upload code, you can see how we deal with that.

=================
ImageMagick notes

ImageMagick can handle just about every image format. When defining the fileOut name, merely changing the extension will tell IM to change the file format. This all the ChangeFileType does, but it does it in a user friendly way. 

Note that the image dimensions shown in IM_Manipulation.html will only display for .jpg and .gif files.

Fonts: for text imprinting, choose a font on the server. If what you choose isn't there, IM will default to a generic sans-serif type. Experiment by using IM_Manipulation.html to figure out what works on your server. Offset spacing will likely need to be experimented with as well.

=========
FUNCTIONS

Basically, functions condense a lot of code into one command so you don't have to repeat yourself over and over. The way they differ from setting a text variable is that a function can contain variables. These IM functions are waiting for your input to tell IM what to do with your image.

Functions are typically in an include file, and go at the top of whatever template needs them. For heavily used functions, you can put them in your Globals/FunctionDefs folder and by turning on your preparse script, they will automatically be available on all of your pages. For our IM functions, you most likely won't be using them on all your pages, so it's prudent to just put the include file on the templates that deal with image manipulation.

===================
SANDBOX ENVIRONMENT

External programs like IM are called via [shell], but for security reasons, [shell] is handled differently in Sandbox environments. In a sandbox, you will need to ask your administrator to set up a script for you to use. Once this script is configured in the SandboxScripts.db, then you can use IM to do a wide range of manipulations. 

To use the Sandbox functions in IM_Functions.inc, you will need to request a sandbox script with the following values (your hosting admin will know what to do with this):

id = ImageMagick_convert
source = /usr/bin/convert [imInput]

Note: /usr/bin/convert is the path to ImageMagick's convert program. This may need to be adjusted for your server, but your admin will know how to do that.

The shell script is formatted differently and the variables are fed in differently when using a Sandbox script. To rotate an image, this is the format of a sandbox shell context vs. a straight shell context:

Sandbox (variables fed to a text variable for the command string, imInput, which is in turn interpreted invisibly by the script. That is correct; nothing goes between the [shell][/shell] tags.):
[text]imInput=[FileIn] -rotate [rotation] [FileOut][/text]
[shell scriptid=ImageMagick_convert][/shell]

No Sandbox (variables fed in directly to the command string):
[shell]/usr/bin/convert [FileIn] -rotate [rotation] [FileOut][/shell]

=========================================
FIY for the curious:
=========================================
SHELL in a FUNCTION in Sandbox

Now to take these shell scripts, put them into a function, then feed them variables works like this:

[function name=imRotateSB]
[text]imInput=[FileIn] -rotate [rotation] [FileOut][/text]
[shell scriptid=ImageMagick_convert][/shell]
[/function]

and on our page with the function included near the top:

Either set text variables on the page somewhere before calling the function, or pass in from a form: FileIn, FileOut, and rotation

[imRotateSB] <--Later on the page, this will interpret using the three variables above.

==================================
SHELL in a FUNCTION NOT in Sandbox

On a regular WebDNA server, the function itself is simpler, but calling the function is a little more complex (just a little though):

[function name=imRotate]
[shell]/usr/bin/convert [FileIn] -rotate [rotation] [FileOut][/shell]
[/function]

and on our page with the function included near the top:

Either set text variables or pass in from a form: FileIn, FileOut, and rotation

[imRotate FileIn=[FileIn]&FileOut=[FileOut]&rotation=[rotation]]