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

Table of Contents

Coding guidelines

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.

End users who wish to modify their copy of coppermine are encouraged to stick to these guidelines as well.

Scope

As Coppermine is a team effort, the team members who contribute code need to make sure that the code remains easy to read, understand and maintain. That's why there is a set of rules defined on this page that should be taken into account when working with the coppermine core code. Although this part of the documentation is aimed at dev team members, users who plan to contribute their code in any form are requested to respect the rules as well if possible (i.e. if you understand them fully).

The coding guidelines on this page are not set in stone - if you (as a dev team member) find during development that one of the guidelines needs review or change, start a thread on the dev board for discussion.


Indentation


Encoding

Encoding standard in Coppermine is UTF-8 without BOM. All non-binary files should be encoded in UTF-8 (Unicode).

General guidelines


PHP code

Formatting

Control Structures

These include if, for, while, switch.

Function Calls

Function Definitions

PHP Code Tags

Nesting of HTML in PHP

When more than one line of HTML needs to be printed, the heredoc syntax should be used instead of ending the PHP processing and starting it later.

Good:

// PHP content here
if ($foo == $bar) {
	print <<< EOT
	<h1>Hello {$bla}</h1>
EOT;
}

Bad:

// PHP content here
if ($foo == $bar) {
	?>
	<h1>Hello <?php echo $bla; ?></h1>
<?php
}

Line breaks

To echo line breaks to the HTML output, use the heredoc syntax or use the variable $LINEBREAK instead of hardcoding line breaks into the code.

Remember to make the variable $LINEBREAK global inside functions.

Good:

echo '<h1>Hello world</h1>' . $LINEBREAK;
echo '<p>foo bar</p>';
}

Bad:

echo "<h1>Hello world</h1>\n";
echo '<p>foo bar</p>';
}

Naming Conventions

For plugin authors there is a more detailed naming conventions section available that describes package names as well.

Database queries


Documentation


HTML output

Image-tags in HTML output

Links in HTML output

Form elements in HTML output

Deprecated tags

Deprecated HTML tags like <font> mustn't be introduced into Coppermine unless there is a valid, documented reason to do so.

Prefered tags

The popular tags <b> and <i> are considered to be deprecated tags as well. Because of their popularity, browsers will probably support them for a long time. However, there are better alternatives. For <b>, the replacement tag is <strong>. For <i>, the replacement tag is <em>. If possible, the replacement tags should be used both in HTML output generated by Coppermine as well as the documentation.


Credits for coding guidelines

The core rules on this page have been sketched by Dr. Tarique Sani as a subset of the PEAR coding guidelines. HTML output and database sections are based on a thread created by Unknown W. Brackets from Simplemachines.


Usability

Good coding skills are important, but it's as well important to code efficiently in terms of usability.

Forms

Less clicks are better

Dropdown lists are great if there are a lot of options to choose from, but they are bad if there are only two or three options: the user needs to click on the dropdown list to find out what options exist.
Instead of coming up with a select box like
it's more intuitive for the user to display all possible options using radio buttons:
If you just want a toggle to switch an option on or off, use the checkbox like
instead of
Display graph:
or even

Bigger target areas for clicks

It can be comparatively hard to hit a single checkbox or radio button - that's why the HTML tag <label> was invented: if you use it wisely, the text that corresponds to a particular option represented by a checkbox or radio button can be clicked on to toggle the checkbox / radio button.
Bad example Good example
Output Go to first
Remain where you are
Jump to last
Code
<input type="radio" name="option_nolabel" value="0" class="radio" checked="checked" />Go to first<br />
<input type="radio" name="option_nolabel" value="1" class="radio" />Remain where you are<br />
<input type="radio" name="option_nolabel" value="2" class="radio" />Jump to last
Output

Code
<input type="radio" name="option_label" id="option_label0" value="0" class="radio" checked="checked" />
<label for="option_label0" class="clickable_option">Go to first</label><br />
<input type="radio" name="option_label" id="option_label1" value="1" class="radio" />
<label for="option_label1" class="clickable_option">Remain where you are</label><br />
<input type="radio" name="option_label" id="option_label2" value="2" class="radio" />
<label for="option_label2" class="clickable_option">Jump to last</label>
Output Display graph
Code
<input type="checkbox" name="display_graph_nolabel" value="1" class="checkbox" />Display graph
Output
Code
<input type="checkbox" name="display_graph_label" id="display_graph_label" value="1" class="checkbox" /><label for="display_graph_label" class="clickable_option">Display graph</label>
Click on the words next to the radio buttons to see the difference!