Coppermine Photo Gallery v1.5.x: Documentation and Manual

Editing the documentation

Target audience

This part of the documentation is not meant for end users of Coppermine, but only for developers. There is no support for this section, it comes as-is.

Edit existing documents

To edit existing documents, simply use your favorite plan text editor - it is all plain HTML plus the JavaScript navigation

Add new documents

To add new documents, follow the steps below:

just use an existing document as template to copy from. Save it within the docs folder giving it a unique, web-safe name that is meaningful.

Edit out the content of the new document after the header section, i.e. between

<body>
<script type="text/javascript">
  cpgDocHeader();
</script>
<div id="toc">
<script type="text/javascript">
  cpgDocToc();
</script>
<noscript>
<a href="toc.htm">Table of Contents</a>
</noscript>
</div>

and

<script type="text/javascript">
  cpgDocFooter();
  dateRevision(' $LastChangedDate$ ', ' $Revision$ ');
</script>

</body>
</html>

This is the section where your actual content should reside

Edit the <title>-tag to reflect your document's content
Edit script.js to add your document to the JavaScript navigation:
Find cpgDocToc and edit the section below it. The syntax is obviously just plain HTML that get's written into the document using JavaScript's document.write syntax. Don't forget to escape single quotes properly!
Edit toc.htm and add a link to the plain HTML table of contents. This is necessary to allow search engine spiders to crawl the documentation, so please do not skip this step. The structure should be pretty self-explanatory (as suggested: plain HTML).
After taking care of creating the file and displaying it in the navigation, it's time to come up with your content. Make sure to use meaningful headlines (preserving the existing <h1>, <h2>, <h3> ... structure). Preferably add anchors as well, making an icon () appear next to each headline that allows easy linking (this should be particularly helpful on the support board - you can add references to particular documentation sections in no time). Take a look at the existing documents for an example
Edit the description meta tag of the new page - come up with a short summary what the page is about. The description meta tag is taken into account by search engine spiders, especially when searching the entire site - see http://www.google.com/search?q=site%3Adocumentation.coppermine-gallery.net
Finally, save your changes and add/commit your file(s) to the subversion repository.

Moving content from one document to the other

When moving content from an existing document to the other (or into a new one), you have to make sure that the links that point to it get moved as well. To do so, search the entire documentation and the coppermine core code for the anchor name and change them to reflect your changes in the documentation.

Hidden features

To display the content of a particular page of the documentation without the page header, logo, table of contents, search form and footer, add the URL parameter hide_nav=1 to the URL. This is meant to allow displaying content within an iframe or similar. Currently, this feature is being used in the installer only.

Database structure

The documentation file dev_database.htm contains documentation about Coppermine's database structure. It's important to keep that piece of the documentation in sync with the actual database changes, i.e. if a dev changes something at database level by editing sql/basic.sql, sql/schema.sql or sql/update.sql that has an impact on the database schema, the documentation has to be updated as well, preferably with the same commit.

Header & footer blocks

Each "regular" file in the documentation needs to contain the header and footer blocks that will be replaced using JavaScript with additional chrome. If you're interessted how this is done, please review ./docs/en/script.js. The only important thing to keep in mind is that the section

<h1 id="docheader">Coppermine Photo Gallery v1.5.x: Documentation and Manual</h1>
<div id="toc">
<a href="toc.htm">Table of Contents</a>
</div>

needs to be preserved right after the <body>-tag.
In a similar manner, the footer section

<div id="doc_footer">
	<div class="doc_info_wrapper">
		<span id="doc_last_changed">$LastChangedDate: 2009-05-27 20:18:54 +0200 (Mi, 27 Mai 2009) $</span>
		<span id="doc_revision">$Revision: 6003 $</span>
	</div>
</div>

right in front of the closing </body>-tag mustn't be edited nor removed.

Documentation internationalization

To help translators come up with valid translations of the docs some extra JavaScript goodies have been added: if a file in a non-english branch of the docs (e.g. "de" -> German) get's added initially in English as a preparation for the translation, the translator or maintainer is encoraged to edit that file (e.g. ./docs/de/example.htm) and add <div id="doc_en_only">No translation available</div> into the body right after the div blocks that compose the header and menu. This block will be replaced using JavaScript/jquery with a more advanced text that explains the document's temporary stage and that translations are welcome. That text can be edited per language in ./docs/yourlanguage/script.js in the function definition for cpgDocTranslationWarning. The maintainer of that language is welcome to add a link to a corresponding thread on the support board.

To mark such documents in the localized, non-English menu, you can use the class en, e.g. like this:

<li><a href="example.htm" class="en">Foo bar</a></li>

will result in

Foo bar

To enable translators to come up with the navigation structure in advance, you can use the CSS class nolink to make a link go "blind", i.e. make it do nothing when clicked, as in this example:

<li><a href="example.htm" class="nolink">Foo bar</a></li>

will result in

Foo bar

Go ahead and click the link to see what happens then: nothing. Keep in mind that this will only work if JavaScript is enabled. If it is disabled, the link will of course lead to it's target no matter what.

If particular anchor targets haven't been finished yet, you can use the CSS class cancel to display a cancel icon like this:

<li><a href="example.htm" class="cancel">Foo bar</a></li>

will result in

Foo bar

To make sure that temporary content doesn't ruin the google page rank or clutters the search result, you should instruct the robots not to index temporary pages - this is done by adding the corresponding meta tag to the file's HTM header:

<meta name="robots" content="noindex" />

Subsequently, if a temporary document get's permanent, the meta tag should be removed.

Expandable/collapsible "detail"-blocks

As the documentation is using the jquery framwork and some little plugins for ease of use, it's possible to come up with expandable/collapsible blocks that the end user can click on to read details. This can help to maintain a clear document structure.

The used technology falls back nicely if JavaScript is disabled: the block are expanded out of the box and get collapsed on page load by JavaScript - if JavaScript is disabled, the blocks stay expanded no matter what.

To create such a block, you need to come up with two container elements that need to be one after the other (no tags between them):

<span class="detail_head_collapsed">Details</span>
<div class="detail_body border1">
	Content that is collapsed on page load and will get expanded if the visitor clicks on the "details" container above.
</div>

You can have several of those blocks on a page. To obtain a control that can manipulate all of them, you can use

<button type="button" class="button detail_expand_all" name="expandalltop" id="expandalltop" onclick="return false">
<img src="../../images/tree/plus.gif" width="9" height="9" border="0" alt="" title="Expand All" />Expand all details
</button>
<button type="button" class="button detail_collapse_all" name="collapsealltop" id="collapsealltop" style="display:none;" onclick="return false">
<img src="../../images/tree/minus.gif" width="9" height="9" border="0" alt="" title="Collapse all" />Collapse all details
</button>

You need to pay attention to anchors that you might want to use within blocks that are collapsed on page load. Let's assume you have this content on a page named example.htm:

<span class="detail_head_collapsed">Details</span>
<div class="detail_body border1">
	Some content that can be accessed using an anchor.
</div>

Such a construct will not work if accessed using a link like this: <a href="example.htm#foo">. That's why a GET parameter named "expand_all" has been added that will expand all collapsed blocks on a page if set to 1. Subsequently, the example link would have to be <a href="example.htm?expand_all=1#foo">

Help

Obviously, the content of the docs folder within coppermine is the place where the documentation is being kept. But apart from that, the docs serve as core for the help system that resides in Coppermine itself (help for the actual application, embedded into the actual application). This being said, here's how the help system currently works: from any PHP-driven file within Coppermine, the help is being populated using the function cpg_display_help that is being defined in include/functions.inc.php. This function creates the needed output and determines wether the gallery admin has enabled help or not.

The first way to display help is by refering to the available strings in the language files. With this coding, the help text would come from the language file, so this option only applies for very short help section.

To refer to an availabe language string, you have to pass the variable name to cpg_display_help

$my_help = cpg_display_help('f=empty.htm&h=lang_my_variable&t=lang_my_variable_details', 200, 100);
echo <<< EOT
{$lang_example['bla']} {$my_help}
EOT;

Of course you can also use language strings in arrays, like this

$my_help = cpg_display_help('f=empty.htm&h=lang_my_array[help_header]&t=lang_my_array[help_text]', 200, 100);
echo <<< EOT
{$lang_example['bla']} {$my_help}
EOT;

The parameter "h" will be the help header, the parameter "t" will be the actual help text body.

Note, that there are no dollar signs before the variable/array names and there mustn't be apostrophes around the array keys!

In earlier versions of Coppermine (< cpg1.5.34) it was possible to pass custom text to help.php. This feature has been dropped, as it caused security flaws several times.

The second (and recommended) way to display help is by refering to the documentation - the function cpg_display_help and the subsequent file help.php are designed for exactly that purpose. All you have to do in your function call is refering to the file name of the documentation section that you want to refer to and the anchor tags that you refer to:

$help = ' ' . cpg_display_help('f=your_file.htm&as=foo_start&ae=foo_end&top=1', '600', '300');

Would refer to the file ./docs/en/your_file.htm and inside that file to the section between

<a name="foo_start"></a>

and

<a name="foo_end"></a>

You don't have to take care of i18n in this case - if the end user's language preference is French and there is a file ./docs/fr/your_file.htm, the end user will see the content taken from that file. The english version of the docs is the default that the help function fallbacks to if there is no help available in the user's prefered language.

Start and end anchors needed

From what has been said so far it should be obvious that every section of the documentation that could be used as help section from within the Coppermine interface needs to be wrapped into a start and end anchor tag. It's not advisable to rely on the order of sections on a documentation page to be preserved - chapters might be added or removed.

Examples

Good example:

docs/en/your_file.htm <a name="food"></a>
<h1>Food</h1>
<p>Here's a list of things that you can eat.</p>
<a name="food_fruit"></a>
<h2>Fruit</h2>
<p>Apples, bananas and cherries are all fruit.</p>
<a name="food_fruit_end"></a>
<a name="food_veggies"></a>
<h2>Vegetables</h2>
<p>Cucumber, carrots and peas are vegetables.</p>
<a name="food_veggies_end"></a>
<a name="food_end"></a>

example.php $help = cpg_display_help('f=your_file.htm&as=food_fruit&ae=food_fruit_end&top=1', '600', '300');

Bad example:

docs/en/your_file.htm <a name="food"></a> <h1>Food</h1> <p>Here's a list of things that you can eat.</p> <a name="food_fruit"></a> <h2>Fruit</h2> <p>Apples, bananas and cherries are all fruit.</p> <a name="food_veggies"></a> <h2>Vegetables</h2> <p>Cucumber, carrots and peas are vegetables.</p>

example.php $help = cpg_display_help('f=your_file.htm&as=food_fruit&ae=food_veggies&top=1', '600', '300');

Adding anchors to headings

In the documentation for cpg1.5.x, nearly every heading (from <h1> to <h6>) should contain a leading anchor tag and a trailing link to that section. This way, supporters can easily spot the anchor that they need to refer to - just click on the trailing link icon in a heading and then copy the URL from the address bar and paste it into the support posting.

That's why it's advisable to add anchors to all sub-sections of the documentation that could serve as online help or that a supporter might want to refer to.

<a name="anchor"></a>
<h2>
    Heading text
    <a href="#anchor" title="Link to this section">
        <img src="images/anchor.gif" width="15" height="9" border="0" alt="" />
    </a>
</h2>

or (for space saving and easier search/replace actions) rolled into one line:

<a name="anchor"></a><h2>Heading text<a href="#anchor" title="Link to this section"><img src="images/anchor.gif" width="15" height="9" border="0" alt="" /></a></h2>

Code

There are several ways to display code snippets inside the docs:

CSS class "code"
For single words or just a few words, you can use the CSS class code, usually with a non-block tag like <tt> or <span>.
Usually, single HTML tags inside the documentation are being highlighted by wrapping them into something like <tt class="code"> and </tt> (although the HTML tag <tt> is considered as deprecated and will be replaced in future versions)
Example:
foo
HTML-tag "pre"
For smaller sections over multiple lines, use <pre>
Example:
```
foo
```
CSS class "cpg_code"
For block elements and longer passages of code, use the class cpg_code (usually in combination with the block element <div>
Example:
foo
CSS class "smallcode"
For code samples in narrow spaces (e.g. within tables), use the class smallcode
Example:
foo
HTML-tag "textarea"
For sections that users might want to copy and paste from, use <textarea>-tags
Example:
foo

Combining HTML tags and CSS classes

The CSS classes and HTML tags that make sense (e.g. <textarea> and smallcode) can and should of course be combined.

Example:

foo

No syntax highlighting

For the sake of easier i18n, you should not use syntax highlighting, as that causes too much extra work for translators!

$LastChangedDate: 2015-08-13 15:21:24 +0200 (Thu, 13 Aug 2015) $ $Revision: 8800 $

Coppermine Photo Gallery v1.5.x: Documentation and Manual

Editing the documentation

Target audience

Edit existing documents

Add new documents

Moving content from one document to the other

Hidden features

Database structure

Header & footer blocks

Documentation internationalization

Expandable/collapsible "detail"-blocks

Help

Start and end anchors needed

Examples

Adding anchors to headings

Code

CSS class "code"

HTML-tag "pre"

CSS class "cpg_code"

CSS class "smallcode"

HTML-tag "textarea"

Combining HTML tags and CSS classes

No syntax highlighting