2 CustomizationManual
Izzy edited this page 4 years ago

Customization Manual

Like the [wiki:AdminManual], this again addresses the site admin. It shows how to customize phpDiveLog beyond the configuration file, and covers the following areas:

Localization

phpDiveLog already ships with translations for several languages – but except for German and English, which are maintained by the developer himself, they may either be not up-to-date, or the language you are looking for is missing completely. While this may sound hard, it is not difficult to solve.

The Translation System

Translations are read from "plain text" files in CSV format, which you find in the lang/ directory of your PDL installation. To also serve incomplete/missing translations, phpdiveLog always falls back to English if it cannot find a term. Which means two things:

  • the English translation file must be the most complete one
  • if a term in your language is the same as it is in English, it can be omitted in your translation file

Editing Translations

If your language is completely missing, you best start with a copy of the lang/trans.en file. As you may already have noticed, the file extension represents the ISO language code, so name the copy appropriately. For example, if you want to start on an Italian translation file, name it trans.it. Remove all translations which will be equivalent to the English ones, and replace the remaining translations with the Italian ones.

If your language is already presented by an (incomplete) translation file, simply copy the missing lines from the English file (new terms are usually simply added to the end, so it should not be that hard to tell), and continue as in above example.

Important: Never ever remove the first line (which specifies the "column" names), or your translations won't work. The same applies to the values of the first column, since this is how phpDiveLog identifies the terms.

Adding a new Language

For this, just follow the description above – starting with the creation of a new language file. When all translation work is done, and the new file is saved to the lang/ directory, the new language with its translations is immediately available. However, it may not have a flag associated on the preferences page. For this, generate the matching flag (or download it from somewhere). Make sure the image size is about 30x20 pixels, it is a *.jpg file, and its name is lang_XX.jpg - where XX represents the corresponding language code (for the above example, this would result in lang_it.jpg). Place it into the templates/*/images directory, and you are done.

Please, don't forget to send your language file to the project, so we can include it into the next version to be used by other people as well.

Template Sets

phpDiveLog is template driven – so if you don't like the design of the created pages, you can easily adjust it to something more suitable – either by modifying an existing template set, or by creating your own.

All relevant files are to be found below the templates/ directory, where each directory represents a "template set". Template files are HTML files with some additional information like place holders for the content and block markers – so all you need is some HTML knowledge, and keeping the place holders and block markers intact.

To create you own template set, you could start with a copy of an existing template set. This ensures that you do not miss any place holders and/or block markers: If those are missing, your template will not work. Then simply edit the HTML in your copy with your favorite HTML editor, adjust the *.css file if necessary, replace some images in the images/ subdirectory, and add the files to a new sub-directory below the templates/* directory.

If it's just the colors and background images you don't like, you may want to modify the *.css files of the template set in question, or replace the images in its images/ subdirectory.

Emoticons

To spice up your descriptions, phpDiveLog offers you the possibility to use emoticons (smileys and the like). For this, you need to set the emoticon definitions file in your configuration (see configuration).

An example definition file is shipped (and configured with the default configuration). You are free to use your own replacement by pointing to a different file with the same structure, which is easy to create: it is a simple CSV file with two columns.

For the emoticons in your descriptions to be recognized, make sure they are surrounded by white-spaces (i.e. spaces, tabs, line breaks). They need to "stand alone", to make sure no other text parts are mistaken as emoticons.