User Guide - v2.0.2

Table Of Contents

  1. Introduction
  2. Basic Setup Procedures
  3. Upload image files
  4. Upload video files
  5. Administration Page
  6. Manually configure coreconfig.inc and config.inc
  7. Manually configure info.inc
  8. Manually configure .note files
  9. (Optional) If you already have all the thumbnails created
  10. (Optional) Different themeset for a specific folder
  11. (Optional) Customise filelist.inc for a specific folder
  12. (Optional) Turn off save protection
  13. (Optional) Debug
  14. (Optional) Switches
  15. Contact Information
  16. [ User Guide ] <<< you're here!
  17. [ Release Note ]
  18. [ Developer Guide ]
  19. [ Admin Page ]
  20. [ Go back to album page ]

1. Introduction

corePHPAlbum is an easy-to-use web-based photo gallery written in PHP.

The best of corePHPAlbum:

  1. Start working without any configuration files
  2. No database and no compilation required
  3. Carefree adding, deleting and moving folders
  4. Configurable title, header and footer...
  5. Modular themesets - highly configurable
  6. Support for different languages
  7. Create thumbnails automatically
  8. Allow different themeset for different folder
  9. Central administration with web interface

[ Go back to Table of Content ]

2. Basic Setup Procedures

To customise individual folder, there are 4 configuration (inc) files: coreconfig.inc, config.inc, info.inc and filelist.inc. And all are optional. coreconfig.inc is actually exactly the same as config.inc but used only when the config.inc for a specific folder not found. Without config.inc and coreconfig.inc, the corePHPAlbum system defaults will be used.

If it's the first time installation and you have a local web server in your PC, you could test before upload to you web site.

  1. Upload the corePHPAlbum sources to uppest level of your album folder in the web site - that are files: index.php, slide.php, switches.php, admin.php and login.php, and folders: _res and optionally _documentation.
  2. Create folders: _config, _thumbnails and _photos.
  3. Set the mode of folders _config, _thumbnails and _photos to make them enough for creating files/folders and searching folder, say 0755.
  4. Go to Ch 3 for details about uploading image files
  5. Go to Ch 4 for details about uploading video files
  6. Go to Ch 5 for details about configuration through the Admin Page
  7. Or, go to Ch 6 and Ch 7 for manual configuration

The privilege required for _photos is to make web interface upload possible in the future.

If you want to enhance security, you could prepare all the files required in your local web server before upload. In this case, there will be nothing to be created on-the-fly. So, you don't need to set mode in step 3 above (except the hit counters enabled), and you don't need to upload admin.php, login.php and folder _res/admin.

If you find the subdirectories/files permission not right after upload or relocation, you may try using fixpermission.php to reset the file system modes of files and directories to 0755 and 0644 respectively. Steps as follows:
  1. Copy the _res/tools/fixpermission.php to album folder, that is the same folder as index.php.
  2. Open the php file in a browser, say http://www.yoursite.com/youralbum/fixpermission.php
  3. As completed, it will show an "OK".
  4. Delete the fixpermission.php and finished.

[ Go back to Table of Content ]

3. Upload image files

As the basic configuration completed, you may now upload your image files. The current version support ONLY jpg image files.

Here are the procedures:

  1. Organise your image files into hierarchy of folders.
  2. Note that the extension of the files MUST BE "jpg" and in lower case.
  3. Upload the hierarchy under the folder _photos in your web site.

[ Go back to Table of Content ]

4. Upload image/video files

You may also upload your video files. The current version support ONLY wmv videos.

In the standard package, there is a video file (_photos/a_video.wmv) included as demontration. It shows that there must also be a image file (_photos/a_video.jpg) to be used as the thumbnail of the video.

Here are the procedures:

  1. Organise your video files into hierarchy of folders.
  2. Note that the extension of the files MUST BE "wmv" and in lower case.
  3. Each video file (say video.wmv) must be accompanied with an image file of same name (video.jpg in this example) that will be used as the thumbnail image of the video file.
  4. The extension of the thumbnail image files MUST BE "jpg" and in lower case.
  5. Upload the hierarchy under the folder _photos in your web site.

[ Go back to Table of Content ]

5. Administration Page

Admin Page is the interface that you could configure all the inc files: coreconfig.inc, and config.inc and info.inc.

Note that, if you do not plan to use Admin Page for configuration, to avoid possible security vulnerabilities, you should remove the folder _res/admin, the following files: admin.php, login.php and _config/password.php.

Start the Admin Page from your web site - admin.php.

If you start it the first time, you will be prompt for the login name and password. Should you want to change your login name or password, you could just login to your web site, say ftp, and delete the file _config/password.php.

For more advance features, you will need to manually configure the _switches.php. They are described in Chapter 10 and Chapter 11.

[ Go back to Table of Content ]

6. Manually configure coreconfig.inc and config.inc

Most settings are self explaining. Listed below is an example file.

File content of an sample files coreconfig.inc or config.inc Description and/or
Valid settings, listed in [ ], for this parameter in the offical packing
language=english [english (system default), simplified-chinese, tranditional-chinese]
template=stage [simple-750, simple-950, stage (system default)]
index_mode=blocks [banner, blocks, list, simple (system default)]
index_css=mosaic-green [bluishblack, bluishblack-left, flower, flower-left, gold, gold-left, mosaic-blue, mosaic-blue-left, mosaic-green (system default), mosaic-green-left, pinkishwhite, pinkishwhite-left]
index_buttons=green [blue, gold, green (system default), silver]
slide_mode=horizon [horizon, simple (system default)]
slide_css=mosaic-green Same as those valid for index_css.

[bluishblack, bluishblack-left, flower, flower-left, gold, gold-left, mosaic-blue, mosaic-blue-left, mosaic-green (system default), mosaic-green-left, pinkishwhite, pinkishwhite-left]
slide_buttons=green Same as those valid for index_button.

[blue, gold, green (system default), silver]
num_column=3 number of column when thumbnails are listed in a single index page. Depending on the design of the index_mode, it may ignore this setting, say 'list'.
num_total=12 total number of thumbnails are listed in a single index page. Depending on the design of the index_mode, it may ignore this setting.
sorting=1 1 - folders go first, then sorted by name
2 - folders go first, then sorted by name reverse order
3 - sorted by name for all folders and imagefiles
4 - sorted by name reverse order for all folders and imagefiles

[1 (system default), 2, 3, 4]
showfilename=no It states that filename will be displayed after the image/video title, if any.

If a image file img.jpg has a title defined in .note file as "image 001", the final display would be "image 001 [img.jpg]".
showindex=no It states that an index will be displayed before the image/video title.

If the second image of a album, which has 20 images, has a title defined in .note file as "image 001", the final display would be "2/20 image 001".
home=http://sourceforge.net/projects/corephpalbumThese are the url and title of the HOME link. If you set 'home=', the HOME link will not be shown. (system default) for both are none.

Note that the default folder_id for the uppest level folder will be 'Frontpage' if no user defined found.
home_title=corePHPAlbum at sf.net
copyright=Copyright (c) {{s_currentyear}} ideashere.net. All rights reserved. Just the copyright statement. Note that {{s_currentyear}} is a system value that will be translated into current year, say "2008". For a full list of these variables, refer to the following table.

If you don't have one, just set 'copyright='. (system default) is none.
thumbnail_width=150 These are the size of the image thumbnails to be created as needed. (system default) for both are 150.
thumbnail_height=150
thumbnail_frame=white The frame used when creating image thumbnail.

[none (system default), black, black-02, rainbow, white, white-02, white-03, tv, tv-02, tv-03, tv-04, green, blue, shadow]
folder_thumbnail_width=150 These are the size of the folder thumbnails to be created as needed. (system default) for both are 150.
folder_thumbnail_height=150
folder_thumbnail_frame=white-02 The frame used when creating folder thumbnail; Options are the same as thumbnail_frame.

[none (system default), black, black-02, rainbow, white, white-02, white-03]
video_player_width=330 These are the size of the video player. (system default) for them are 330 and 300 respectively.
video_player_height=330
video_thumbnail_width=150 These are the size of the video thumbnails to be created as needed. (system default) for both are 150.
video_thumbnail_height=150
video_thumbnail_frame=tv The frame used when creating video thumbnail.

[none, black, black-02, rainbow, white, white-02, white-03, tv (system default), tv-02, tv-03, tv-04, green, blue, shadow]

System values could be used in all the text fields, e.g. "copyright". Examples below assume current date Tuesday, 01 April, 2008, and the corePHPAlbum running is 2.0.2.

{{sv_year}}2008
{{sv_yearshort}}08
{{sv_month}}04
{{sv_monthshort}}4
{{sv_monthword}}April
{{sv_monthwordshort}}Apr
{{sv_day}}01
{{sv_dayshort}}1
{{sv_week}}Tuesday
{{sv_weekshort}}Tue
{{sv_version}}2.0.2

[ Go back to Table of Content ]

7. Manually configure info.inc

Most settings are self explaining. Listed below is an example file. Note that System values listed in Chapter 6 could also be used for text fields in this file.

File content of an sample info.inc fileDescription and/or
Valid settings, listed in [ ], for this parameter in the offical packing
folder_id=corePHPAlbum It's a name used in the route to represent this folder.
title=corePHPAlbum Demonstration Page Just the title, header and footer for this folder. However, depending on the design, they may not be used.

As an example, most offical slide_mode do not show the title and header. And, should you want more than one line, use the '>' as the line continuation mark, example as the footer below.
header=An easy-to-use web-based photo gallery
footer=Thanks for trying corePHPAlbum
>It's the second line of the footer
folder_thumbnail=image123.jpg The name of image file to be used to create the folder thumbnail as needed.
image123_jpg=The remark It's the remark for image file image123.jpg. Note that all '.' found in the filename will need to be replaced with '_'.

[ Go back to Table of Content ]

8. Manually configure .note files

Most settings are self explaining. Listed below is an example file. Note that System values listed in Chapter 6 could also be used for text fields in this file.

File content of an sample .note fileDescription and/or
Valid settings, listed in [ ], for this parameter in the offical packing
remark=an interesting It's the remark of the image/video file.
title=holiday It's the title of the image/video file.
hit_count=3 It's the current hit count of for the image/video file.
external_url=http://sourceforge.net/projects/corephpalbum This option must be nil, that is "external_url=". Otherwise, clicking on the thumbnail will not open the slide page of this image, instead it will be redirected to the url provided, for example http://sourceforge.net/projects/corephpalbum.

It's option available image, file only.
new_window=yes This option is used only if option external_url not nil.

[ Go back to Table of Content ]

9. (Optional) If you already have all the thumbnails created

Instead of using the basic thumbnails creation feature, you could create the thumbnails with your own favored tools.

If you already have ALL the image thumbnails and folder thumbnails, you could upload them to the folder _thumbnails with the same name and relative position as their correponding source, while the folder thumbnail should be named _thumbnail.jpg.

After uploaded, make sure sufficient privilege for folder and files, say 0755 and 0644 respectively.

[ Go back to Table of Content ]

10. (Optional) Different themeset for a specific folder

Upload a coreconfig.inc to the corresponding directory under _config/, rename it as config.inc then customise. Say, if there is a image folder vacation in the uppest level storing your photos from a vacation, then the file you should create is _config/vacation/config.inc.

[ Go back to Table of Content ]

11. (Optional) Customise filelist.inc for a specific folder

Create a file named filelist.inc in the corresponding directory under _config/. Say, if you want to sort in a specific way your sub-folders and image/video files in the folder vacation which is in the uppest level, then the file you should create is _config/vacation/filelist.inc.

The content of this file should only be the filenames and folder names found in that folder - one for each line and in the order that you want to arrange them. Here is an example

folder01
folder02
image01
image02
image03

[ Go back to Table of Content ]

12. (Optional) Turn off save protection

Edit switches.php for the following line:

$_switch['save_protect']='OFF';

Save protection protection feature is used to prevent users from right-click on your images and save. It's ON by default.

[ Go back to Table of Content ]

13. (Optional) Debug

For advance users or developers only.

Should you want to create your own templates, index_mode, slide_mode, adding new functions, or even customising the Admin Page, you may need want to enable the debug mode.

Edit switches.php for the following line:

$_switch['debug']='ON';

Then, use could use the following function to capture the status during the code running. The $str could be anything valid during the function is called, say it could be a variable or the return from a function call.

debug_log($str);

This function would already return TRUE. Every call to this function would just put the $str into an array. At the end of the execution, the content of the array will be printed to the page bottom.

[ Go back to Table of Content ]

14. (Optional) Switches

All switches are defined in the _switches.php. For security reason, there is no web interface provided for making changes to _switches.php, just make changes and upload with your own tools.

$_switch['save_protect'] Refer to Chapter 11. (Optional) Turn off save protection
$_switch['debug'] Refer to Chapter 12. (Optional) Debug
$_switch['hit_counter'] This switch will turn on the logging of hit count to the corresponding .note file.
$_switch['show_hit_counter'] This switch provides a control whether the hit counter should be displayed. In order display the correct hit count, you will also need to turn on the $_switch['hit_counter'].

However, it's also up to the individual index or slide mode to make use of it. Currently, it's only available in slide mode simple
$_switch['admin_demo_mode'] In this mode, no changes in Admin Page will be applied.

[ Go back to Table of Content ]

15. Contact Information

Should you have any question or suggestion, email to:

bng@users.sourceforge.net
or corephpalbum@ideashere.net

Also you can find the latest releases and information at the following locations:

http://sourceforge.net/projects/corephpalbum

A demonstration of the current (release or beta) version is at the following location:

http://corephpalbum.ideashere.net/

If you have any corePHPAlbum resource sets (buttons, index_modes, slide_modes, new language file, CSS or whatever) to share with others, any new features or enhancements to request or any bugs and issues to report, you could email to me or post to the following forum:

http://sourceforge.net/forum/?group_id=163016

Thanks for trying corePHPAlbum !!

[ Go back to Table of Content ]

END