Location: PHPKode > projects > CorePHPAlbum > cpa-2.0.2/_documentation/user-guide.html
<!-- ========================================================
     =                                                      =
     = corePHPAlbum - web-based photo gallery               =
     =                                                      =
     = User Guide                                           =
     = file release 2.0.2                                   =
     =                                                      =
     = http://sourceforge.net/projects/corephpalbum         =
     =                                                      =
     ======================================================== -->

<link rel="stylesheet" href="style.css" type="text/css">


<h1><span class="keyword">User Guide - v2.0.2</span></h1>

<!-- TOC -->
<a name="toc">
<h1>Table Of Contents</h1>

<ol>
	<li><a href="#ch01">Introduction</a></li>
	<li><a href="#ch02">Basic Setup Procedures</a></li>
	<li><a href="#ch03">Upload image files</a></li>
	<li><a href="#ch04">Upload video files</a></li>
	<li><a href="#ch05">Administration Page</a></li>
	<li><a href="#ch06">Manually configure coreconfig.inc and config.inc</a></li>
	<li><a href="#ch07">Manually configure info.inc</a></li>
	<li><a href="#ch08">Manually configure .note files</a></li>
	<li><a href="#ch09">(Optional) If you already have all the thumbnails created</a></li>
	<li><a href="#ch10">(Optional) Different themeset for a specific folder</a></li>
	<li><a href="#ch11">(Optional) Customise filelist.inc for a specific folder</a></li>
	<li><a href="#ch12">(Optional) Turn off save protection</a></li>
	<li><a href="#ch13">(Optional) Debug</a></li>
	<li><a href="#ch14">(Optional) Switches</a></li>
	<li><a href="#ch15">Contact Information</a></li>

	<li><a href="user-guide.html"><span class="keyword">[ User Guide ] <<< you're here!</span></a></li>
	<li><a href="release-note.html"><span class="keyword">[ Release Note ]</span></a></li>
	<li><a href="developer-guide.html"><span class="keyword">[ Developer Guide ]</span></a></li>
	<li><a href="../admin.php"><span class="keyword">[ Admin Page ]</span></a></li>
	<li><a href="../index.php"><span class="keyword">[ Go back to album page ]</span></a></li>
</ol>


<!-- Chapter 1 -->
<h1><a name="ch01"></a>1. Introduction</h1>

<p>corePHPAlbum is an easy-to-use web-based photo gallery written in PHP.</p>
<p>The best of corePHPAlbum:</p>
<ol>
	<li>Start working without any configuration files</li>
	<li>No database and no compilation required</li>
  <li>Carefree adding, deleting and moving folders</li>
  <li>Configurable title, header and footer...</li>
  <li>Modular themesets - highly configurable</li>
  <li>Support for different languages</li>
  <li>Create thumbnails automatically</li>
  <li>Allow different themeset for different folder</li>
  <li>Central administration with web interface</li>
</ol>

<p><a href="#toc"><span class="keyword">[ Go back to Table of Content ]</span></a></p>


<!-- Chapter 2 -->
<h1><a name="ch02"></a>2. Basic Setup Procedures</h1>

<p>To customise individual folder, there are 4 configuration (inc) files: <span class="keyword">coreconfig.inc</span>, <span class="keyword">config.inc</span>, <span class="keyword">info.inc</span> and <span class="keyword">filelist.inc</span>. And all are optional. <span class="keyword">coreconfig.inc</span> is actually exactly the same as <span class="keyword">config.inc</span> 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.</p>
<p>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.</p>
<ol>
	<li>Upload the corePHPAlbum sources to uppest level of your album folder in the web site - that are files: <span class="keyword">index.php</span>, <span class="keyword">slide.php</span>, <span class="keyword">switches.php</span>, <span class="keyword">admin.php</span> and <span class="keyword">login.php</span>, and folders: <span class="keyword">_res</span> and optionally <span class="keyword">_documentation</span>.
	<li>Create folders: <span class="keyword">_config</span>, <span class="keyword">_thumbnails</span> and <span class="keyword">_photos</span>.</li>
	<li>Set the mode of folders <span class="keyword">_config</span>, <span class="keyword">_thumbnails</span> and <span class="keyword">_photos</span> to make them enough for creating files/folders and searching folder, say 0755.</li>
	<li>Go to <a href="#ch03">Ch 3</a> for details about uploading image files</li>
	<li>Go to <a href="#ch04">Ch 4</a> for details about uploading video files</li>
	<li>Go to <a href="#ch05">Ch 5</a> for details about configuration through the Admin Page</li>
	<li><span class="keyword">Or</span>, go to <a href="#ch06">Ch 6</a> and <a href="#ch07">Ch 7</a> for manual configuration</li>
</ol>

<p>The privilege required for <span class="keyword">_photos</span> is to make web interface upload possible in the future.</p>
<p>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 <span class="keyword">admin.php</span>, <span class="keyword">login.php</span> and folder <span class="keyword">_res/admin</span>.</p>

<a name="ch02a"></a>If you find the subdirectories/files permission not right after upload or relocation, you may try using <span class="keyword">fixpermission.php</span> to reset the file system modes of files and directories to 0755 and 0644 respectively. Steps as follows:

<ol>
	<li>Copy the <span class="keyword">_res/tools/fixpermission.php</span> to album folder, that is the same folder as index.php.</li>
	<li>Open the php file in a browser, say http://www.yoursite.com/youralbum/fixpermission.php</li>
	<li>As completed, it will show an "OK".</li>
	<li>Delete the fixpermission.php and finished.</li>
</ol>

<p><a href="#toc"><span class="keyword">[ Go back to Table of Content ]</span></a></p>


<!-- Chapter 3 -->
<h1><a name="ch03"></a>3. Upload image files</h1>

<p>As the basic configuration completed, you may now upload your image files. The current version support <span class="keyword">ONLY jpg image files</span>.</p>

<p>Here are the procedures:</p>

<ol>
	<li>Organise your image files into hierarchy of folders.</li>
	<li>Note that the extension of the files MUST BE "jpg" and in lower case.</li>
	<li>Upload the hierarchy under the folder <span class="keyword">_photos</span> in your web site.</li>
</ol>

<p><a href="#toc"><span class="keyword">[ Go back to Table of Content ]</span></a></p>


<!-- Chapter 4 -->
<h1><a name="ch04"></a>4. Upload image/video files</h1>

<p>You may also upload your video files. The current version support <span class="keyword">ONLY wmv videos</span>.</p>
<p>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.</p>

<p>Here are the procedures:</p>

<ol>
	<li>Organise your video files into hierarchy of folders.</li>
	<li>Note that the extension of the files MUST BE "wmv" and in lower case.</li>
	<li>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.</li>
	<li>The extension of the thumbnail image files MUST BE "jpg" and in lower case.</li>
	<li>Upload the hierarchy under the folder <span class="keyword">_photos</span> in your web site.</li>
</ol>

<p><a href="#toc"><span class="keyword">[ Go back to Table of Content ]</span></a></p>


<!-- Chapter 5 -->
<h1><a name="ch05"></a>5. Administration Page</h1>

<p>Admin Page is the interface that you could configure all the inc files: <span class="keyword">coreconfig.inc</span>, and <span class="keyword">config.inc</span> and <span class="keyword">info.inc</span>.</p>
<p><span class="important">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.</span></p>
<p>Start the Admin Page from your web site - admin.php.</p>
<p>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 <span class="keyword">_config/password.php</span>.</p>
<p>For more advance features, you will need to manually configure the _switches.php. They are described in <a href="#ch10">Chapter 10</a> and <a href="#ch11">Chapter 11</a>.</p>

<p><a href="#toc"><span class="keyword">[ Go back to Table of Content ]</span></a></p>


<!-- Chapter 6 -->
<h1><a name="ch06"></a>6. Manually configure coreconfig.inc and config.inc</h1>

<p>Most settings are self explaining. Listed below is an example file.</p>
<table>
	<tr><td><b>File content of an sample files <span class="keyword">coreconfig.inc</span> or <span class="keyword">config.inc</span></b></td>
			<td><b>Description and/or<br/>Valid settings, listed in [ ], for this parameter in the offical packing</b></td></tr>

	<tr><td>language=english</td>
			<td>[english <span class="keyword">(system default)</span>, simplified-chinese, tranditional-chinese]</td></tr>

	<tr><td>template=stage</td>
			<td>[simple-750, simple-950, stage <span class="keyword">(system default)</span>]</td></tr>

	<tr><td>index_mode=blocks</td>
			<td>[banner, blocks, list, simple <span class="keyword">(system default)</span>]</td></tr>

	<tr><td>index_css=mosaic-green</td>
			<td>[bluishblack, bluishblack-left, flower, flower-left, gold, gold-left, mosaic-blue, mosaic-blue-left, mosaic-green <span class="keyword">(system default)</span>, mosaic-green-left, pinkishwhite, pinkishwhite-left]</td></tr>

	<tr><td>index_buttons=green</td>
			<td>[blue, gold, green <span class="keyword">(system default)</span>, silver]</td></tr>

	<tr><td>slide_mode=horizon</td>
			<td>[horizon, simple <span class="keyword">(system default)</span>]</td></tr>

	<tr><td>slide_css=mosaic-green</td>
			<td>Same as those valid for index_css.<br/><br/>[bluishblack, bluishblack-left, flower, flower-left, gold, gold-left, mosaic-blue, mosaic-blue-left, mosaic-green <span class="keyword">(system default)</span>, mosaic-green-left, pinkishwhite, pinkishwhite-left]</td></tr>

	<tr><td>slide_buttons=green</td>
			<td>Same as those valid for index_button.<br/><br/>[blue, gold, green <span class="keyword">(system default)</span>, silver]</td></tr>

	<tr><td>num_column=3</td>
			<td>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'.</td></tr>

	<tr><td>num_total=12</td>
			<td>total number of thumbnails are listed in a single index page. Depending on the design of the index_mode, it may ignore this setting.</td></tr>

	<tr><td>sorting=1</td>
			<td>1 - folders go first, then sorted by name<br/>
					2 - folders go first, then sorted by name reverse order<br/>
					3 - sorted by name for all folders and imagefiles<br/>
					4 - sorted by name reverse order for all folders and imagefiles<br/><br/>
					[1 <span class="keyword">(system default)</span>, 2, 3, 4]</td></tr>

	<tr><td>showfilename=no</td>
			<td>It states that filename will be displayed after the image/video title, if any.<br/><br/>If a image file img.jpg has a title defined in <span class="keyword">.note</span> file as "image 001", the final display would be "image 001 [img.jpg]".</td></tr>

	<tr><td>showindex=no</td>
			<td>It states that an index will be displayed before the image/video title.<br/><br/>If the second image of a album, which has 20 images, has a title defined in <span class="keyword">.note</span> file as "image 001", the final display would be "2/20 image 001".</td></tr>

	<tr><td>home=http://sourceforge.net/projects/corephpalbum</td><td rowspan="2">These are the url and title of the HOME link. If you set 'home=', the HOME link will not be shown. <span class="keyword">(system default)</span> for both are none.<br/><br/><span class="keyword">Note that the default folder_id for the uppest level folder will be 'Frontpage' if no user defined found.</span></td></tr>
	<tr><td>home_title=corePHPAlbum at sf.net</td>

	<tr><td>copyright=Copyright (c) {{s_currentyear}} ideashere.net. All rights reserved.</td>
			<td>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.<br/><br/>If you don't have one, just set 'copyright='. <span class="keyword">(system default)</span> is none.</td></tr>

	<tr><td>thumbnail_width=150</td>
		<td rowspan="2">These are the size of the image thumbnails to be created as needed. <span class="keyword">(system default)</span> for both are 150.</td></tr>
	<tr><td>thumbnail_height=150</td>
	<tr><td>thumbnail_frame=white</td>
			<td>The frame used when creating image thumbnail.<br/><br/>[none <span class="keyword">(system default)</span>, black, black-02, rainbow, white, white-02, white-03, tv, tv-02, tv-03, tv-04, green, blue, shadow]</td></tr>

	<tr><td>folder_thumbnail_width=150</td>
			<td rowspan="2">These are the size of the folder thumbnails to be created as needed. <span class="keyword">(system default)</span> for both are 150.</td></tr>
	<tr><td>folder_thumbnail_height=150</td>
	<tr><td>folder_thumbnail_frame=white-02</td>
			<td>The frame used when creating folder thumbnail; Options are the same as thumbnail_frame.<br/><br/>[none <span class="keyword">(system default)</span>, black, black-02, rainbow, white, white-02, white-03]</td></tr>

	<tr><td>video_player_width=330</td>
		<td rowspan="2">These are the size of the video player. <span class="keyword">(system default)</span> for them are 330 and 300 respectively.</td></tr>
	<tr><td>video_player_height=330</td>

	<tr><td>video_thumbnail_width=150</td>
		<td rowspan="2">These are the size of the video thumbnails to be created as needed. <span class="keyword">(system default)</span> for both are 150.</td></tr>
	<tr><td>video_thumbnail_height=150</td>
	<tr><td>video_thumbnail_frame=tv</td>
			<td>The frame used when creating video thumbnail.<br/><br/>[none, black, black-02, rainbow, white, white-02, white-03, tv <span class="keyword">(system default)</span>, tv-02, tv-03, tv-04, green, blue, shadow]</td></tr>
</table>

<p><a name="ch06sv"></a><span class="keyword">System values</span> 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.</p>
<table>
	<tr><td>{{sv_year}}</td><td>2008</td></tr>
	<tr><td>{{sv_yearshort}}</td><td>08</td></tr>
	<tr><td>{{sv_month}}</td><td>04</td></tr>
	<tr><td>{{sv_monthshort}}</td><td>4</td></tr>
	<tr><td>{{sv_monthword}}</td><td>April</td></tr>
	<tr><td>{{sv_monthwordshort}}</td><td>Apr</td></tr>
	<tr><td>{{sv_day}}</td><td>01</td></tr>
	<tr><td>{{sv_dayshort}}</td><td>1</td></tr>
	<tr><td>{{sv_week}}</td><td>Tuesday</td></tr>
	<tr><td>{{sv_weekshort}}</td><td>Tue</td></tr>
	<tr><td>{{sv_version}}</td><td>2.0.2</td></tr>
</table>

<p><a href="#toc"><span class="keyword">[ Go back to Table of Content ]</span></a></p>


<!-- Chapter 7 -->
<h1><a name="ch07"></a>7. Manually configure info.inc</h1>

<p>Most settings are self explaining. Listed below is an example file. Note that <span class="keyword">System values</span> listed in <a href="#ch06sv">Chapter 6</a> could also be used for text fields in this file.</p>

<table>
	<tr><td><b>File content of an sample info.inc file</b></td><td><b>Description and/or<br/>Valid settings, listed in [ ], for this parameter in the offical packing</b></td></tr>
	<tr><td>folder_id=corePHPAlbum</td>
			<td>It's a name used in the route to represent this folder.</td></tr>

	<tr><td>title=corePHPAlbum Demonstration Page</td>
			<td rowspan="3">Just the title, header and footer for this folder. However, depending on the design, they may not be used.<br/><br/>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.</td></tr>

	<tr><td>header=An easy-to-use web-based photo gallery</td>

	<tr><td>footer=Thanks for trying corePHPAlbum<br/>>It's the second line of the footer</td>

	<tr><td>folder_thumbnail=image123.jpg</td>
			<td>The name of image file to be used to create the folder thumbnail as needed.</td></tr>

	<tr><td>image123_jpg=The remark</td>
			<td>It's the remark for image file image123.jpg. Note that all '.' found in the filename will need to be replaced with '_'.</td></tr>
</table>

<p><a href="#toc"><span class="keyword">[ Go back to Table of Content ]</span></a></p>


<!-- Chapter 8 -->
<h1><a name="ch08"></a>8. Manually configure .note files</h1>

<p>Most settings are self explaining. Listed below is an example file. Note that <span class="keyword">System values</span> listed in <a href="#ch06sv">Chapter 6</a> could also be used for text fields in this file.</p></p>

<table>
	<tr><td><b>File content of an sample .note file</b></td><td><b>Description and/or<br/>Valid settings, listed in [ ], for this parameter in the offical packing</b></td></tr>
	<tr><td>remark=an interesting</td>
			<td>It's the remark of the image/video file.</td></tr>
	<tr><td>title=holiday</td>
			<td>It's the title of the image/video file.</td></tr>
	<tr><td>hit_count=3</td>
			<td>It's the current hit count of for the image/video file.</td></tr>

	<tr><td>external_url=http://sourceforge.net/projects/corephpalbum</td>
			<td>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.<br/><br/>It's option available image, file only.</td></tr>
	<tr><td>new_window=yes</td>
			<td>This option is used only if option <span class="keyword">external_url</span> not nil.</td></tr>
</table>

<p><a href="#toc"><span class="keyword">[ Go back to Table of Content ]</span></a></p>


<!-- Chapter 9 -->
<h1><a name="ch09"></a>9. (Optional) If you already have all the thumbnails created</h1>

<p>Instead of using the basic thumbnails creation feature, you could create the thumbnails with your own favored tools.</p>
<p>If you already have ALL the image thumbnails and folder thumbnails, you could upload them to the folder <span class="keyword">_thumbnails</span> with the same name and relative position as their correponding source, while the folder thumbnail should be named <span class="keyword">_thumbnail.jpg</span>.</p>
<p>After uploaded, make sure sufficient privilege for folder and files, say 0755 and 0644 respectively.</p>

<p><a href="#toc"><span class="keyword">[ Go back to Table of Content ]</span></a></p>


<!-- Chapter 10 -->
<h1><a name="ch10"></a>10. (Optional) Different themeset for a specific folder</h1>

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

<p><a href="#toc"><span class="keyword">[ Go back to Table of Content ]</span></a></p>


<!-- Chapter 11 -->
<h1><a name="ch11"></a>11. (Optional) Customise filelist.inc for a specific folder</h1>

<p>Create a file named <span class="keyword">filelist.inc</span> in the corresponding directory under <span class="keyword">_config/</span>. Say, if you want to sort in a specific way your sub-folders and image/video files in the folder <span class="keyword">vacation</span> which is in the uppest level, then the file you should create is <span class="keyword">_config/vacation/filelist.inc</span>.</p>
<p>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</p>
<p class="p1">folder01<br/>
						 folder02<br/>
						 image01<br/>
						 image02<br/>
						 image03<br/>
</p>

<p><a href="#toc"><span class="keyword">[ Go back to Table of Content ]</span></a></p>


<!-- Chapter 12 -->
<h1><a name="ch12"></a>12. (Optional) Turn off save protection</h1>

<p>Edit switches.php for the following line:<p>
<p class="p1"><span class="keyword">$_switch['save_protect']='OFF';</span></p>
<p>Save protection protection feature is used to prevent users from right-click on your images and save. It's ON by default.</p>

<p><a href="#toc"><span class="keyword">[ Go back to Table of Content ]</span></a></p>


<!-- Chapter 13 -->
<h1><a name="ch13"></a>13. (Optional) Debug</h1>

<p>For advance users or developers only.</p>
<p>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.</p>
<p>Edit switches.php for the following line:</p>
<p class="p1"><span class="keyword">$_switch['debug']='ON';</span></p>
<p>Then, use could use the following function to capture the status during the code running. The <span class="keyword">$str</span> could be anything valid during the function is called, say it could be a variable or the return from a function call.</p>
<p class="p1"><span class="keyword">debug_log($str);</span></p>
<p>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.</p>

<p><a href="#toc"><span class="keyword">[ Go back to Table of Content ]</span></a></p>


<!-- Chapter 14 -->
<h1><a name="ch14"></a>14. (Optional) Switches</h1>

<p>All switches are defined in the <span class="keyword">_switches.php</span>. For security reason, there is no web interface provided for making changes to <span class="keyword">_switches.php</span>, just make changes and upload with your own tools.</p>
<table>
	<tr><td>$_switch['save_protect']</td>
			<td>Refer to <a href="#ch11">Chapter 11. (Optional) Turn off save protection</a></td></tr>

	<tr><td>$_switch['debug']</td>
			<td>Refer to <a href="#ch12">Chapter 12. (Optional) Debug</a></td></tr>

	<tr><td>$_switch['hit_counter']</td>
			<td>This switch will turn on the logging of hit count to the corresponding <span class="keyword">.note</span> file.</td></tr>

	<tr><td>$_switch['show_hit_counter']</td>
			<td>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 <span class="keyword">$_switch['hit_counter']</span>.<br/><br/>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 <span class="keyword">simple</span></td></tr>

	<tr><td>$_switch['admin_demo_mode']</td>
			<td>In this mode, no changes in Admin Page will be applied.</td></tr>
</table>

<p><a href="#toc"><span class="keyword">[ Go back to Table of Content ]</span></a></p>


<!-- Chapter 15 -->
<h1><a name="ch15"></a>15. Contact Information</h1>

<p>Should you have any question or suggestion, email to:</p>
<p class="p1">	<a href="mailto:hide@address.com">hide@address.com</a><br/>
				<span class="keyword">or</span> <a href="mailto:hide@address.com">hide@address.com</a></p>

<p>Also you can find the latest releases and information at the following locations:</p>

<p class="p1"><a href="http://sourceforge.net/projects/corephpalbum">http://sourceforge.net/projects/corephpalbum</a></p>

<p>A demonstration of the current (release or beta) version is at the following location:</p>
<p class="p1"><a href="http://corephpalbum.ideashere.net/">http://corephpalbum.ideashere.net/</a></p>

<p>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:
<p class="p1"><a href="http://sourceforge.net/forum/?group_id=163016">http://sourceforge.net/forum/?group_id=163016</a></p>

<p>Thanks for trying corePHPAlbum !!</p>

<p><a href="#toc"><span class="keyword">[ Go back to Table of Content ]</span></a></p>

<h1><span class="keyword">END</span></h1>
Return current item: CorePHPAlbum