CarTest Software Image Uploader Installation Instructions
=========================================================
Product Description:
--------------------
The Image Uploader is a utility that permits a visitor to your web site
or message board to upload an image from their computer to your host server.
That way the image is available on the internet accessed through it's own URL
for viewing or for linking in a message board or guestbook post message. A
versatile image viewer is also provided.
To successfully install the uploader you should have some knowledge of
administrating a web site including knowledge of using an FTP (File Transfer
Protocol) program or your user control panel to upload files to your web site.
Some knowledge of HTML and creating graphic images is needed to customize the
look of the uploader. No knowledge of php is required.
Features:
---------
- User configurable through a single definition file.
- Customizable through the templates provided.
- Password protection for the uploading and viewer.
- Image thumbnails automatically generated.
- Uploaded image automatic resizing and jpeg compression control for disk
space and bandwidth reduction.
- Uploaded image file size limit.
- Can ban troublesome uploaders though their IP addresses.
- Maintains a log file of uploads.
- Displays helpful uploaded file link and message posting strings.
- Displays Instructions and operating notes.
- Image viewer presents clickable thumbnails and file information.
- Images presented in various sorted orders for convenient browsing.
Requirements:
-------------
You host server must support the PHP language. In addition, the 'GD' libraries
version 2.0.x or later must have been installed with php. Also, the
memory_limit parameter must be either not defined or set to a value high
enough to permit processing of large images, like 20MB or more. Please check
with your host provider to make sure. Alternatively, you can find out on your
own by using phpinfo.
Here is a php program, call it 'phpinfo.php'. Create this as a text file or use
the one included in the zip file and upload it to your host server with an FTP
program or by using the control panel for your domain. Place this file in a
directory one level from the root directory called 'temp', for example, then
use your browser to run it by entering it's URL in the browser's text field:
http://www.yourdomainname/temp/phpinfo.php
A comprehensive description of your hosts's php installation will be presented.
Near the top will be a listing of the modules included when php was installed.
One of those must be the 'GD' libraries. These do the image manipulation that
the Image Uploader requires. If it is not present, you can try to ask your host
provider to install it. If nothing comes up at all then there is an error in
the file or your host does not support php at all.
Zip File Contents:
------------------
The delivered file, imageuploader.zip, contains the following files:
1. This text file, installationsinstructions.txt - the installation
instructions you are reading.
The php programs:
2. imageuploader.php - the main file invoked when using the uploader.
3. image_config.php - the configuration file you must edit
(see Configuration below).
4. image_receiver.php - the php file that controls the uploading of images,
automatically invoked from the imageuploader.php file.
5. image_viewer.php - the php file that controls the viewing of the images,
automatically invoked from the imageuploader.php file.
6. phpinfo.php - see Requirements above. You can delete this afterwards as it
is not needed by the uploader.
The html files:
These are templates that you can edit as you want to customize the appearance
of the uploader and viewer. You should be familiar with basic HTML to
modify these.
7. imageuploader_header.html - header file controlling the appearance of the
uploader. There is no footer file.
8. image_receiver_header.html - header file controlling the appearance of the
'succesfully uploaded' page following uploading.
9. image_receiver_footer.html - footer file controlling the redirection button
at the bottom of the 'succesfully uploaded' page
following uploading. You can make this a blank
file if there is no need for a redirection
button.
10. image_receiver_header.html - header file controlling the appearance of the
image viewer page.
11. image_receiver_footer.html - footer file controlling the redirection button
at the bottom of the image viewer page. You
can make this a blank file if there is no
need for a redirection button.
12. index.html - A message only file that prevents users from listing the
directory. Delete this file to allow users to list your
directory.
Blank files:
13. uploads.log - the log file. Lists uploaded file name, IP address of the
uploader, and time and date uploaded.
14. bannediplist.txt - list of IP address prevented from uploading (see
Configuration below).
Sample graphics:
15. /images/imageuploaderheader.jpg - sample header image for the uploader.
16. /images/homepageicon.jpg - sample redirection icon image.
17. /images/homepageiconhighlight.jpg - sample redirection icon when cursor
hovers over image (see the _footer.html
files).
18. /images/imageuploaderbackground.jpg - sample page background image for the
uploader and viewer.
19. /images/imageuploaderbutton.jpg - sample button referred to in installation
step 3 below.
20. /images/imageuploaderbuttonhighlight.jpg - sample button (cursor hover
version) referred to in
installation step 3 below.
21. /images/index.html - A message only file that prevents users from listing
the directory. Delete this file to allow users to list
your directory.
Nearly Empty Directories:
22. /uploads/index.html - A message only file that prevents users from listing
the directory. Delete this file to allow users to list
your directory.
23. /thumbs/index.html - A message only file that prevents users from listing
the directory. Delete this file to allow users to list
your directory.
Installation Steps:
-------------------
1. Extract the imageuploader.zip file into it's /imageuploader/ directory. You
can preserve this structure when you later upload it to your host server.
2. Edit the image_config.php file (see below).
3. Make a link to the uploader from your web site or message board. You can use
the sample buttons provided, make your own, or use a simple text link. The
link should simply point to imageuploader.php in the directory where you
placed it. Here is a sample link with a few extras you may choose to use or
not as you want.
The 'target=_blank' string will cause the uploader to appear in a separate
window. Eliminate that string if you don't want a separate window.
Here is the javascript code to go with the onMouseOver and onMouseOut
directives above. This causes the highlighted version of the button to appear
when the mouse hovers over the button. Eliminate those if you don't want this
function.
4. Upload the image uploader files and directory structure.
5. Set file and directory permissions. Use the Unix CHMOD command from your FTP
program or control panel to set the following permissions
(owner group world, r=read, w=write, x=execute):
Directory with the uploader software, /imageuploader/: rwx r-x r-x or 755
Uploaded image directory, /imageuploader/uploads/: rwx rwx rwx or 777
Created thumbnails directory, /imageuploader/thumbs/: rwx rwx rwx or 777
Upload log file, uploads.log: rw- rw- rw- or 666
All other files: rw- r-- r-- or 644
6. Use the uploader.
Configuration:
--------------
You will need to edit the image_config.php file. This is actually an 'include'
file used by the uploader and viewer. It consists of names of php variables
followed by an equal sign followed by the values of those variables. The names
of the variables are each preceded by a dollar sign ,'$'. Do NOT alter the
dollar sign or those names. You will be editing the text on the right hand
side of the equal signs for each variable value that you need to change. Shown
below are the variables as supplied and used in the demo on the cartestsoftware
web site. Some you must edit to use with your web site and host, others control
image uploader options and you can set them or leave them as you want. The lines
commencing with a '//' are comment lines in the php program.
// unix path to file storage directory
$path_to_images="/home/cartes2/public_html/imageuploader/uploads/";
This information is supplied by your server host. Alternately, the phpinfo.php
program will reveal the unix path to the public part of your web site. In the
example above, All except the cartes2 is fairly typical. The cartes2 part must
be replaced with your particular information. The /imageuploader/uploads/ points
to the directory where the images will be uploaded by your users. Do not leave
off the '/' characters at the beginning and end. The quotes are only for the
configuration program to use and are required here.
// URL of image directory
$URL_prefix_images="http://www.cartestsoftware.com/imageuploader/uploads/";
// unix path to thumbnail storage directory
$path_to_thumbnails="/home/cartes2/public_html/imageuploader/thumbs/";
Same description as above. The /imageuploader/thumbs/ points to the
directory where the thumbnails will be created and stored.
// URL of thumbnail directory, if empty string (i.e. "") no thumbnails are created
$URL_prefix_thumbnails="http://www.cartestsoftware.com/imageuploader/thumbs/";
If the right hand side is replaced with an empty string, i.e. "", then the
thumbnails feature will not be used.
// uploading or viewing password (case sensitive)
$require_password_to_upload=true;
$require_password_to_view=false;
// if BOTH the above are false the next three are ignored
$password="upload";
$email_for_password="youraddress@yourdomain.com";
$password_obtain_criteria="Include your real name, user name, and please use the email address you used to register.";
You can choose to require a password to upload file (a good idea). Specify this
with a 'true' value. A 'false' value disables this. The password is specifed by
encasing it in double quotes above but your users do not use the quotes when
entering it when using the uploader. If you disseminate the password to your
users via email, enter the email address where that may be requested along with
an optional description of the criteria you require to receive it. Again, the
quotes are only for the configuration program.
// list of IP addresses (one per line in the file) not allowed to upload, if empty string (i.e. "") no file is checked
// IP addresses can be listed as xxx.xxx.xxx.xxx for a specific address or
// IP addresses can be listed as xxx.xxx.xxx or xxx.xxx or xxx for all addresses that begin that way
$banned_ip_list_file_name="bannediplist.txt";
Sometimes a particularly obnoxious person uploads objectionable images into your
uploader just to cause some mischief. In the log file (see below) a list is
maintained of image names and IP (Internet Protocol) addresses where the image
originated. To keep this person out you can specify that IP address as not
permitted to upload. This is not foolproof as IP addresses can change but it is
an effective measure. Be careful with using truncated addresses because you may
inadvertently ban a user that you do not want to ban who has an IP address that
starts with the same few numbers as someone who you do want to ban.
// keeps a log of images uploaded, source IP address, and date and time uploaded, if empty string (i.e. "") no log is maintained
$upload_log_file_name="uploads.log";
// upload file size limit in bytes, if 0 then no limit
$file_size_limit=1048576;
// automatic jpeg image resize or size checking, if either is 0 no resizing is done, no resizing or size checking of .gif images is done
$max_image_width=640;
$max_image_height=640;
This determines the maximum size in pixels of images that will be stored in the
uploader. The uploader will automatically resize images so that both the maximum
width AND maximum height specified is obeyed. If an image is smaller then both
these values then it is not altered. The original aspect ratio of the image is
always preserved.
// size of jpeg image thumbnails
$thumbnail_width=80;
$thumbnail_height=60;
This is also the size that .gif images will be displayed in the viewer. Also the
size that .jpg images will be displayed in the viewer if thumbnails are not used
(see above).
// IJG jpeg compression quality level, 0=smallest file but worst quality, 100=biggest file best quality, ignored if resizing or size checking is not done
$image_quality=50;
Jpeg images can be compressed more or less. This has nothing to do with the
pixel size width and height. Less compression results in a higher quality image
but takes up more disk space and increases bandwidth use on your web site.
// email address where to request image deletion, ignored if empty string (i.e. "")
$email_for_deletion="webmaster@yourdomain.com";
// if operating a message board
$message_board=true;
$open_image_tag="[IMG]";
$close_image_tag="[/IMG]";
$URL_open_start_string="[URL=";
$URL_open_end_string="]";
$URL_close_tag="[/URL]";
// extra notes displayed on upload page
$note1="Please do not upload copyrighted images or trademarked material. Such images will be deleted upon identification.";
$note2="";
$note3="";
$note4="";
$note5="";
// in the image viewer
$number_images_per_page=20;
Other Notes:
------------
You can start out by uploading some images into the uploads directory without
using the uploader (via FTP or your control panel). The image viewer will create
the thumbnails automatically if they are not already present.
The uploader is restricted to .jpg and .gif file types. There is no longer
support for manipulating .gif files in the php GD libraries so thumbnails are
not created for those file types. Rather, reduced versions of the full image are
depicted in the viewer.