====== Development ======

===== Developer Ressources =====

If you want to contribute to [[vdb:VideoDB]] you should join the [[vdb:mailinglist]].

To stay up to date you should also use the current CVS version of VideoDB to avoid writing something that maybe is already included there. You can get the current development version from the CVS Server either by browsing the [[http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/videodb/videodb/|Web-Interface]] or accessing the repository directly via anonymous CVS:

  cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/videodb login
  cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/videodb co videodb

When prompted for a password just hit enter.

Please note that the webbased access is up to 24 hours behind the real CVS Server so a real checkout is always to prefer.

Developers may be interested in the generated [[http://www.splitbrain.org/Programming/PHP/VideoDB/doc/API/index.html|API Documentation]], too.
===== Coding Guidelines =====

The VideoDB coding guidelines follow the standards set by the PEAR project (http://pear.php.net). For a full version of these documents please check the [[http://pear.php.net/manual/en/standards.php|PEAR Coding Standards]] page.

==== Indenting and Line Length ====

Use an indent of 4 spaces, with no tabs. 
It is recommended that you break lines at approximately 75-85 characters. There is no standard rule for the best way to break a line, use your judgment.

<code php>
if ((condition1) || (condition2)) {
    action1;
} elseif ((condition3) && (condition4)) {
    action2;
} else {
    defaultaction;
}
</code>

 
==== Control Structures ====

Control statements should have one space between the control keyword and opening parenthesis, to distinguish them from function calls. 
You are strongly encouraged to always use curly braces even in situations where they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added. 

For switch statements: 

<code php>
switch (condition) {
case 1:
    action1;
    break;

case 2:
    action2;
    break;

default:
    defaultaction;
    break;
}
</code>

==== Function Calls ====

Functions should be called with no spaces between the function name, the opening parenthesis, and the first parameter; spaces between commas and each parameter, and no space between the last parameter, the closing parenthesis, and the semicolon. Here's an example: 

<code php>
$var = foo($bar, $baz, $quux);
</code>


As displayed above, there should be one space on either side of an equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, more space may be inserted to promote readability: 

<code php>
$short         = foo($bar);
$long_variable = foo($baz);
</code>


==== Function Definitions ====

Function declarations follow the "one true brace" convention: 

<code php>
function fooFunction($arg1, $arg2 = '')
{
    if (condition) {
	statement;
    }
    return $val;
}
</code>

Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. 

==== Comments ====

Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found here: http://www.phpdoc.org/ 

Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works. 

C style comments (/* */) and standard C++ comments (//) are both fine. Use of Perl/shell style comments (#) is discouraged. 


===== Languages =====

VideoDB already comes with a lot of languages, but if your's isn't supported why don't you become a translator?

The first thing you should do is join the [[vdb:mailinglist]] to stay informed when new language strings are added.

To create a new language file just copy the en.php file in the language directory and translate the all the contained strings to your language. I think you'll get the system when you have a look at it ;-).

However pay attention to the ''$lang[encoding]'' field. This contains the character encoding you used in the file. You may use another encoding than ''iso-8859-1''. See the ''bg.php'' as an example.

You should adjust the the header at the top of the file to reflect your authorship, too. ;-). When updating or correcting a file of someone else just add another ''@author'' line with your name.

After translation you should send the file to the mailing list to be included in the next release.

Sometimes translations get slightly behind the english version. Missing translations will are always replaced by the english strings.

**Hint** The ''langcheck.php'' tool in the [[vdb:contrib]] section can be very helpful to see a list of missing translations.

===== Templates and Stylesheets =====

Instead of designing a whole new template you can add new stylesheets to existing templates. Just copy an exisisting stylesheet to a new name and adjust it to your match your ideas. All ''.css'' files become automatically available in the [[vdb:configuration]] screen.

If changing the stylesheet isn't enough to make VideoDB look like you want you can create a new template. Templates consist of multiple ''.tpl'' files in their own directory in the ''template'' directory. VideoDB uses the [[http://smarty.php.net|Smarty]] template engine, so you should have a look at the [[http://smarty.php.net/docs.php|Smarty Documentation]] first.

The best way to create a new template is to copy the default template and customize it. 
All files referenced to, can be found in the ''templates'' directory. Copy the template subdirectory of your choice to with a new name. This will make it easy to continue to upgrade from CVS.

1. ''compact.css'' - This file drives the look and feel of fonts, colors, tables and other eye candy, but does not change the content in any way (check CSS Stylesheet documentation on the web to learn more about it [[http://www.google.com/search?q=css|(Google)]]). I would always start here, as it is very easy and integrates videodb quickly into the look and feel of your hompage(s).

2. ''header.tpl'' - Change this file to include such things as Javascripts for all your templates.

3. ''filters.tpl'' - On the main browsing screen, one can change the look and feel and the functionality of the filters (ABC, DEF etc). Your template could, for example use dropdowns instead of radio buttons to enable the filtering.

4. ''show.tpl'' - One of the most interesting pages to change, as it defines the layout of the movie information.