<?php

// To convert this PHP file to html, take a look at the
// respective FAQ/Help page and add &html to the URL.

$helpArray = array(

array('_type_'=>'h1',
      'text'=>'Introduction'),
array('_type_'=>'none',
      'text'=>'This help page covers the PHPmyGallery script from a coder\'s point of view. It won\'t teach you every detail but you can find a place where to start modifying the script. Have fun coding!'),
      
array('_type_'=>'h1',
      'text'=>'Customizing'),
array('_type_'=>'none',
      'text'=>'This script is template based, which means you can change the look of the pages to what you like. It\'s easy to make PHPmyGallery match your design.<br><br>

In PHPmyGallery a template is a textfile which is read by the script into memory, then the script replaces certain content with content of PHP variables created by the script. Content that has to be replaced is marked with an open curled brace ({), a dollar sign ($), a name (with letters, numbers, minus (also called hyphen), underscores and dots) and finally a closed curled brace (}). We will call this a template variable from now on.<br>
So something like {$name} within the templates is replaced by the content of a PHP variable during the script. Templates can also be used within templates, for example {$text_content} of _conf/templates/phpmygallery.html is replaced with content that came from other templates.<br><br>

To customise the look of the script, you have to know how to read and write HTML files yourself. Please note: Using graphical editors for editing templates can be a problem since some of them insert <html><body> and </body></html> which may result in wrong output to the browser.<br>
You can implement your own layout by leaving the template variables and building your own HTML code around. You won\'t have to edit all of them to make them match your design.<br><br>

All templates are in the _conf/templates/ directory. They are organised in several subdirectories:<br>

<i>The main script:</i><br>
Template files within the _conf/templates/ directory are used throughout the script. phpmygallery.html is the main template for the gallery pages.<br>
index_view - for displaying the available groups<br>
group_view - for displaying the galleries within a group<br>
gallery_view - for displaying the thumbnails/picturelinks within a gallery<br>
picture_view - for displaying a picture of a gallery<br><br>
plugins - for templates used by PlugIns<br>

<i>The admin menu:</i><br>
adminmenu - Small templates used throughout the adminmenu. adminmenu.html is the main template for the admin menu.<br>
adminmenu/faqhelp - for displaying the help pages<br>
adminmenu/fileperms - for displaying the file permissions page<br>
adminmenu/gallery_settings - for displaying the gallery settings page. Used for main settings, too<br>
adminmenu/groups_settings - for displaying the groups settings page<br>
adminmenu/htaccess_create - for displaying the htaccess file creation pages<br>
adminmenu/index_view - for displaying the starting page of the admin menu<br>
adminmenu/login - for displaying the login page<br>
adminmenu/picture_descriptions - for displaying the picture descriptions page<br>
adminmenu/plugins - for displaying the plugins listing page<br>
adminmenu/sessionpwd_create - for displaying the password creating page<br>
adminmenu/statistics - for displaying the statistics page<br><br>

Experimenting with the templates can\'t do any harm, just read the Examples section and try fooling around. Always keep a backup of files you edit :)'),
      
array('_type_'=>'h2',
      'text'=>'Example'),
array('_type_'=>'none',
      'text'=>'Let\'s say you want to have your own website logo to display on the pages (assuming your logo is named logo.gif (300x60) and is within a directory named gfx in your home directory), edit templates/all_pageLogo.html.<br>'),
array('_type_'=>'code',
      'title'=>'It should look like this',
      'text'=>'<a href="{$link_tophpmygalleryindex}"><img src="PHPmyGallery_grey.gif" align="left" width="200" height="46" alt="" border="0"></a>'),
array('_type_'=>'code',
      'title'=>'Change it to',
      'text'=>'<a href="{$link_tophpmygalleryindex}"><img src="/gfx/logo.gif" align="left" width="300" height="60" alt="my logo" border="0"></a>'),
array('_type_'=>'none',
      'text'=>'<br>And there you go. PHPmyGallery should be displaying your own logo. Editing templates is mostly this easy. Just keep the template variables intact.<br>
PHPmyGallery uses the phpmygallery.css file for colors and font sizes etc.'),
      
array('_type_'=>'h2',
      'text'=>'Templates'),
array('_type_'=>'none',
      'text'=>'Templates are used in several ways all over the scripts. We will create a sample page rendered with the pktpl template system. At first, take a look at the templates files we create in the templates directory...<br>'),
array('_type_'=>'code',
      'title'=>'Sample.html',
      'text'=>'<html>
    <head>
        <title>{$title}</title>
    </head>
    <body>
        {$template_myTable}
    </body>
</html>'),
array('_type_'=>'code',
      'title'=>'Table.html',
      'text'=>'<table>{$template_tableRows}</table>'),
array('_type_'=>'code',
      'title'=>'TableRow.html',
      'text'=>'<tr><td>{$text_left}</td><td>{$text_right}</td></tr>'),
array('_type_'=>'none',
      'text'=>'<br>Here is the script that renders the HTML page. We will discuss what it does how afterwards.<br>
$pktpl_vars = pktpl_start(); would initialize the template variables to an empty array, we assume this already happened.<br>'),
array('_type_'=>'code',
      'title'=>'myScript.php',
      'text'=>'&nbsp;1  $arr = array(\'One\',\'Two\',\'Three\');
&nbsp;2  $pktpl_vars[\'title\'] = \'Testing pktpl\';
&nbsp;3  
&nbsp;4  $rowCount = 0;
&nbsp;5  $rows     = \'\';
&nbsp;6  foreach($arr as $v) {
&nbsp;7      $rowCount++;
&nbsp;8      $pktpl_vars[\'text_left\']  = $rowCount.\':\';
&nbsp;9      $pktpl_vars[\'text_right\'] = $v;
10      
11      $rows .= pktpl(\'TableRow.html\');
12  }
13  $pktpl_vars[\'template_tableRows\'] = $rows;
14  $pktpl_vars[\'template_myTable\']   = pktpl(\'Table.html\');
15  
16  echo( pktpl(\'Sample.html\') );'),
array('_type_'=>'none',
      'text'=>'<br>Line 1: Initializing an array which will be used to generate HTML-table rows from. The array could also have come from the database or an external include file.<br>
Line 2: Simply assigning a string to the pktpl_vars array. Notice that {$title} within our first template will be replaced by what is stored in $pktpl_vars[\'title\']. If you use the same template variable name in several templates, make sure you overwrite the old version or you will see the old value in the other template. pktpl never resets the pktpl_vars array. Also check for PHP\'s automatic type-conversion for numbers to strings.<br>
Lines 4-5: Initialisations for the foreach loop. Instead of $rows we could also have used $pktpl_vars[\'template_tableRows\'] directly.<br>
Lines 8-9: Assigning the values for {$text_left} and {$text_right} for the current iteration.<br>
Line 11: The pktpl function opens the template and replaces all template variables found with the entries from the $pktpl_vars array. If a variable is not found in $pktpl_vars, the function replaces with an empty string. Finally, the function returns the template with all variables replaced. Note that we use .= to add each table row to the previous ones.<br>
Line 13: Assign all rows at once to $pktpl_vars[\'template_tableRows\']. {$template_tableRows} is used in the Table.html template.<br>
Line 14: By calling the pktpl function here, {$template_myTable} will hold the complete table with all table rows as one string, once we call pktpl(\'Sample.html\');<br>
Line 16: The final step, one call to pktpl with Sample.html as parameter. The result is directly output to the browser.<br><br>

There we have a complete HTML page done with pktpl. Now you only have to change the templates instead of the PHP code when you want to change the design.<br>'),
      
/*array('_type_'=>'h1',
      'text'=>'How the script works'),
array('_type_'=>'none',
      'text'=>'Yeah, I\'ll get to that'),
      
array('_type_'=>'h2',
      'text'=>'Used variables'),
array('_type_'=>'none',
      'text'=>'Yeah, I\'ll get to that'),
      
array('_type_'=>'h2',
      'text'=>'Files and directories'),
array('_type_'=>'none',
      'text'=>'Yeah, I\'ll get to that'),*/
      
array('_type_'=>'h1',
      'text'=>'Coding PlugIns'),
array('_type_'=>'none',
      'text'=>'Coding PlugIns for the backend can also be done easily if you read the Templates section. You place a .php file in the plug-ins directory containing any PHP code you like. As the last line, it has to set $pktpl_vars[\'template_admin_table\'] to the HTML code you want to output.<br>'),
array('_type_'=>'code',
      'title'=>'Sample plugin (you can call it Sample.php)',
      'text'=>'$pktpl_vars[\'template_admin_table\'] = "My name is Sheltem.";'),
array('_type_'=>'none',
      'text'=>'<br>Put this in the plug-ins directory and visit the admin menu plug-ins section. There it should be listed. Click on it now to see it work.<br><br>

A plug-in can modify the whole database, use all template variables previously defined and use all templates within the templates directory.'),

array('_type_'=>'h2',
      'text'=>'Files'),
array('_type_'=>'none',
      'text'=>'Normally, a PlugIn consists of several files: A php file to execute the plugin, a language pack file, a txt file with the same filename (with a short description that is displayed in the PlugIns section of the admin menu), a ReadMe_ file and optionally several templates.<br>
For example, the GalleryConvertor PlugIn has GalleryConvertor.php, GalleryConvertor.txt, ReadMe_GalleryConvertor.txt, two language packs in lang/ and some templates in templates/plugins/GalleryConvertor/. If you want, you can use all the other templates within the templates directory if they suit the needs of the PlugIn. Your PlugIns should be organised like this, too.<br>'),
array('_type_'=>'code',
      'title'=>'pktpl should be called this way for your own PlugIn templates',
      'text'=>'$pktpl_vars[\'variablename\'] = pktpl(\'plugins/PluginName/templatefile.html\');'),
array('_type_'=>'none',
      'text'=>'<br>Substitute variablename, PluginName and templatefile with what works for you.'),

array('_type_'=>'h2',
      'text'=>'Links&Forms'),
array('_type_'=>'none',
      'text'=>'To use links and forms within your PlugIns, you have to format them a special way. Put the following in the action tag of forms or href tags of links...<br>'),
array('_type_'=>'code',
      'title'=>'Use this for your links',
      'text'=>'{$backendscript_filename}?action=plugins&plugin={$pluginLink}{$your_vars}{$GET_params}'),
array('_type_'=>'none',
      'text'=>'<br>backendscript_filename - Links back to the admin menu\'s index.php (set automatically)<br>
action=plugins - sets action to include _conf/_php-core/adminmenu/do_plugins.php<br>
pluginLink - sets selected plugin to execute your plugin script again (set from within do_plugins.php automatically)<br>
your_vars - replace this with one or more GET variables to do an action within your script. See below.<br>
GET_params - holds the session id with sessions login or nothing if htaccess login (set automatically).<br><br>

You can use variables passed by a form ($_POST) the way you are used to. Just the action tag has to look like shown above.<br>'),
array('_type_'=>'code',
      'title'=>'Implementing your_vars from the example above',
      'text'=>'$var = $_GET[\'var\'];
$pktpl_vars[\'your_vars\'] = \'&var=\'.$var;'),

array('_type_'=>'h2',
      'text'=>'Multilanguage'),
array('_type_'=>'none',
      'text'=>'A Plugin should make use of the lang directory to put language specific messages there. As for GalleryConvertor, it can use GalleryConvertor.English.php or GalleryConvertor.Deutsch.php.<br>
Within a language pack there has to be an array $l which is added to the pktpl_vars array by using the processLanguagePack function (_conf/_php-core/functions.php). Look up the function definition or take a look how GalleryConvertor makes it work.<br><br>

The processLanguagePack function looks up if a language pack for the current language exists, if not it tries to use a default language which you supply to the function. It will put out an error message if both language files could not be found.'),

array('_type_'=>'h2',
      'text'=>'Sample Plugin GalleryConvertor'),
array('_type_'=>'none',
      'text'=>'Please don\'t hesitate to use GalleryConvertor as a starting point to code your own PlugIns. It demonstrates how to load and save stuff from and to the database, and it uses several custom templates.<br>
If you have further questions coming up, just use the Contact link from the admin menu.'),
      
array('_type_'=>'h2',
      'text'=>'Submitting'),
array('_type_'=>'none',
      'text'=>'Use the contact form on PHPmyGallery\'s website (or use the Contact link in the admin menu) to inform me about your PlugIn.<br>
I will respond with an email address you can send your zip file to. I will test your PlugIn as soon as I can and then send some feedback to you about it. If I find it to be useful I will make it available for download.<br><br>

Have fun coding and do backups! :)'),

array('_type_'=>'h1',
      'text'=>'Debugging'),
array('_type_'=>'none',
      'text'=>'If you have problems coding the script, you can use the built in debugger. It receives an HTML or plain-text formatted string within the variable $debugCode and displays it within the browser. This way you can locate a problem pretty fast.<br>
This can be done from anywhere of the code. If you want to debug within a function, write global $debugCode; right after the opening brace ( { ) of the function.<br>'),
array('_type_'=>'code',
      'title'=>'Example',
      'text'=>'function myFunction() {
    global $debugText;
    
    $debugText = "Easy debugging";
}'),
array('_type_'=>'none',
      'text'=>'<br>Any text that $debugText holds will be displayed within a grey window "above" the website.<br><br>
Note: To debug an array, use the arr2php function of PHPmyGallery. It receives an array and the variable name as parameters.<br>'),
array('_type_'=>'code',
      'title'=>'Example',
      'text'=>'$arr = array(1,2,3,4,5,10);
$debugText = arr2php($arr,"arr");'),
array('_type_'=>'code',
      'title'=>'View available pktpl_vars entries',
      'text'=>'$debugText = arr2php(array_keys($pktpl_vars),"pktpl_vars");'),
array('_type_'=>'code',
      'title'=>'View available language variables',
      'text'=>'$debugText = arr2php(array_keys($l),"l");'),
);

?>
