Opposite to the AdminManual, the following pages are describing issues relevant for the diver representing his/her logbook with phpDiveLog. The following issues are covered:
- Installation: Client side installation issues
- Configuration: How to configure your phpDiveLog account
- Data Conversion: Data Conversion and Transfer
- Additional Information: Placing photos and additional descriptions
While the installation of phpDiveLog itself is the duty of the admin, the diver also has to perform some installation tasks: We need to export the data from ADL to a format usable by phpDiveLog, and thus we have to setup the conduit.
Install the Conduit
The conduit itself is not shipped with phpDiveLog, so you have to download it from the ADL website. Further this article assumes you already did so and also installed the conduit. So this is where we start here: The conduit is installed, and you have the phpDiveLog sources unpacked on your disk. All you need from the latter is the content of the
- copy the contents of the
install/adl/template/dir to ADLs
- copy the contents of the
install/adl/dir to ADLs directory
Consult the documentation of ADL concerning the basic configuration of the
divelog.ini file. For phpDiveLog we only assume you changed the following parameters here:
TablePDBFilepoints to your
DivePDBFilepoints to your
For the other parameters, please refer to the conduits documentation.
To convert (and optionally transfer) the data from ADL, phpDiveLog provides the
divelog_conduit.sh file – which is configured with the file named
config residing in the same directory. These files are intended to be used with the Bash shell available on Linux/Unix machines, and also with Cygwin on Windows hosts. Since phpDiveLog exists, there has never been a request for a Windows script – so if you need it, you may want to open a feature request ticket (and be willing to test the result, since I don't have Windows running and thus cannot test).
As usual with Shell scripts, the configuration parameters follow the syntax "name=value", and please take care to not introduce any spaces directly next to the equal sign:
||de_DE@euro||Don't mess this up with your PCs locale settings – we don't touch them. But if they differ from your Palms locale (which will certainly be the case if you run a current distribution with UTF-8 locale), special characters may get messed up or, in the worst case, the Java Conduit hangs if this is not set correctly. In most cases, the setting of
||lat1||PalmOS devices use different character sets. If you encounter display problems on your divelog web pages, such as messed-up characters (German Umlauts and the like), you may want to play with this option. If not set to an empty string, the script will use the
||log||If you did not change this in the
||bothunits||which kind of units you prefer – can be set either to "metric", "imperial" or "bothunits"|
||-noprofileupdate||Creation of the dive profile PNG graphics slows down the conversion process a lot (it takes about 2/3 of the time). Luckily, starting with conduit version 0.99_7 there is a new parameter to skip this step if the PNG already exists:
||"%Y-%m-%d %H:%M:%S"||just for the "progress display" on the screen to give you an idea how long which step took ;)|
||1||if you want to copy the files to your local webserver, set the value to "1" – otherwise to "0".|
||"/web/divelog/diver/demo"||the divers directory of your local phpDiveLog installation, i.e. where the subdirectories
||0||if you want to copy the files to a remote webserver via
||"user@machine:/path_to_PDL/diver/demo"||the divers directory of the remote phpDiveLog installation, i.e. where the subdirectories
||1||this defines which source directory should be used with
You can use local (
USELOCAL=1) and remote (
USESCP=2) transfers independantly – if you need both, you can enable both at the same time (which would even be required for
Site Account Configuration
The site account configuration takes place in two files located directly in your PDL home directory (i.e.
system.conf: contains your preferences concerning site appearance
divers.conf: contains personal information about you you want to attach to your online divelog
Optionally, each diver can override some of the systems default settings by putting a file named
system.conf in his/her "home directory" ("home directory" refers to the
diver/<nick>/ subdirectory of the phpDiveLog installation). The syntax of this file is easy: one parameter per line in the form
var=value. Empty lines and lines beginning with a "#" are ignored. Which system options are allowed to be overridden is defined by the site admin, so please ask the admin what you can use - and refer to the admins configuration for the syntax.
One additional parameter in the
personal. It defines whether the diver wants to display his/her personal data (see
diver.conf below) or not. If this parameter is missing (or commented out), noone will be able to browse them via the person.php page, even if a complete
diver.conf exists. The same applies if it is set to "0". Set
personal = 1 if you want the page to be displayed.
system.conf contains a few parameters which only can be set on a per-diver-basis: Namely, the "user defined fields" from Aqua DiveLog. There are two fields which you can set manually in its preferences, and they are exported via the conduit. So if you want them displayed along with your dive data, you should set the variables
userdef2 to the title these fields should have. If then for a dive there are data available for this field(s), they will be shown in the equipment section of the dive.
This file, if available, must reside in the same directory as the
system.conf file (see above). It is intended to provide data for the divers personal page, i.e. name and place of living as well as certifications.
diver.conf is divided into several blocks - block names are encloses in square brackets. If you do not want to provide data for a specific block at all, you may just completely remove it (or comment it out) at all.
[person] block, as the name suggests, contains the personal data. Available options in this block are
status (where status means your highest certification, e.g. AOWD, DM or Instructor). You can include a photo of yours using the
foto option also available in this block. The image used here must be stored in the
diver/*/fotos/person/ subdirectory. If you don't specify one, a "dummy" will be used instead. If you want to omit something, just delete or comment out that line. With the
buddylist option you define whether these personal data may be included in the buddy list (if enabled by the admin) by setting it to "1" - or not, by either setting it to "0", commenting it out or removing that line completely.
[certification] block, there are stronger rules to observe. Data for a certification must include the course (i.e. the certification - makes no sense without ;) and may include the date and place where it was gained. Thus we have three items that belong together, and we may have multiple of this groups. So we group them together by arrays. The consequence is you have to keep the three items together if they belong together, and you must not miss the square brackets at the end of the options name. Plus you have to include either none or all three options - if you don't want to publish e.g. the date, just leave the parameter blank. Otherwise, if you specify it for the next course, the parser will count it to the previous ;) Available options in this block are
To add more descriptive context, you can make use of other "external sources", such as a text file in your diver "home directory". See Additional Sources for details on this.
If you want your data to be accessible and findable by visitors - i.e. used in the buddylist and global site index, place an additional file next to the bot configuration files and name it
public. It's content is completely ignored (so it may be empty), but its presence will be checked at the corresponding places.
Data Conversion and Transfer
Once you've setup the conduit scripts accordingly, you simply have to change to the directory containing the
divelog_conduit.sh script and run it without any parameters – after you got the up-to-date ADL database files from your Palm. Provided your configuration was correct, the script will do all necessary steps:
- run the conduit to convert the ADL database files to
- adjust the text encoding in those
*.csvfiles if necessary
- optionally transfer all data (optionally including your images etc., depending on your configuration) to the web server
If your site admin only provided you with FTP access, you may have to do the last step manually. Also, depending on the server account setup, you now may need to invoke the
import.php script on the phpDiveLog website to get your data to the web dirs - ask your site admin whether you have to do so or not.
If you re-organized some dive data (especially renumbering the dives and/or sites), you may need to clean the
images/ directory (which contains the dive profile images) before you run the conduit script, to make sure they are re-created with the correct names. Of course, in this case you will also have to check your photos and text files and rename them accordingly (see AdditionalInfo for details on those files).
Placing additional Information
You may include additional information like pictures or external (plain text) files into your dive, site, and personal information, which can be done in two different ways:
- placing files with specific names in the right locations
- using special macros in your ADL dive/site notes
Dive and Site photos
You can advise phpDiveLog to automatically display fotos connected to your dives and/or divesites. PDL searches two special directories for these images: the
diver/<nickname>/fotos/dive/ directory for pictures related to dives, and
diver/<nickname>/fotos/site/ for divesite related images. It recognizes the Jpg, Gif and Png image types as valid. Descriptions are to be placed in
*.txt files having the same name as the image they describe (see examples in the
The naming conventions are taken from the ADL specifications: all dive images have the name
diveXXXXX-YYY.*, while the site images are to be named
siteXXXX-YYY.txt - where the
XXXXX stand for the 5-digit dive/site number (zero-padded from the left, e.g. "00025" for dive/site number 25), and
YYY for a 3-digit consecutive number of all images for the related dive/site. With the first phpDiveLog is able to connect the images with the according data records, using the latter you can define the order the images are displayed.
Things to consider:
- recommended size for these "thumbnails" is 192x144 pixel
- make the file extensions lower case (i.e. *.jpg|png|gif|txt)
- when re-numbering your dives, your fotos need to be renumbered accordingly
- if you want PDL to link the "thumbnail" to the original (larger) image, give the latter the same file name and place it into the "large" subdirectory of the directory the "thumbnail" was placed into
Additional descriptions for your Dives and Sites
The "external notes feature" is mainly intended to save you from editing larger stuff on your PDA - so you store only the core information in ADL, but expatiate upon them here (especially as the fields in the PDA are rather limited in size as well). To create an external "notes" field, simply place a plain text file named
diveXXXXX.txt (for dive notes) or
siteXXXXX.txt (for site notes) in the
notes/ subdirectory of your "diver home directory", replacing the "XXXXX" by the ID of the dive/site filled up with zeros from the left to 5 digits (e.g. a note for dive #57 would be
dive00057.txt). This file may contain HTML formatings (e.g. for
<U>nderlining) as well as all available "tags" (see below). All double-newlines will be replaced by line breaks ("
<BR>") to form paragraphs.
Make sure that all text files are using the UTF-8 character set! For Windows, e.g. the standard editor (notepad) can save files in UTF-8 if you select "Save as", and then in the dialog you find some "encodings" box where you can select "UTF-8". With *nix, if your editor does not support this, you can use the
recode command for this task (for details, see the man page with
If you like to create localized versions of your notes, you can do so for all languages that are directly supported by phpDiveLog (see the Setup page). For these, name the files as described above plus add the language code to the end of the filename, so it would be
*.txt.de for a German, or
*.txt.ru for a Russian text. In these cases you should ensure that the default file (without the language code) also exists, since the localized versions would only be displayed if the visitor has the given language selected on the Setup page. To ensure this, you can make use of symbolic links. If you e.g. have a German and an English description, you could either place the English one as
*.txt and the German one as
*.txt.de - or name the English one
*.txt.en and create an additional symbolic link using the
ln -s <name of the English file> <name of the English file without the ".en"> command.
These files will automatically be appended to the corresponding notes fields, if they exist, as if their content would have been entered in the ADL comments fields. Additionally it should be said that you shouldn't use HTML formating to extensive (e.g. by changing background colors etc.) to not mess up the general design of the site.
Additional textual information for the personal page can be created similarly - but here we consider just the
diver.txt[.<lang>] file(s) in the divers "home directory", i.e. the directory where the divers
Image files here must reside in the
diver/<nickname>/fotos/person/directory and be named
YYY is a consecutive number of their order, left-padded by zeros (e.g.
Makros in Textfiles and ADL notes
You may include additional information like pictures or external (plain text) files into your notes by using special tags which are then replaced when phpDiveLog parses your DiveLog information for display. This way you can include images and point to additional information on local and remote sites, or even include other plain text/html files stored on the machine serving your PDL files.
Embedded links are enclosed by the
[/url] tags. Embedded images are enclosed by the
[/img] (left aligned) or
[/imgr] (right aligned) tags. External (text/html) files can be included by using the
[/file] tags, nesting of tags (i.e. using the tags in a file included by the
[file] tag, and using images as anchors for URLs) is possible. The syntax of the part between the tags is as follows, where square brackets mark optional and angle brackets mandatory parts:
|Tag||Part between the opening and closing Tag||Example|
A special case is the
rootDir specification, which has the syntax
~dir is a single letter, representing …
[gps] macro first builds the URL for the configured map service out of the coordinate part and the optional name. Then the entire macro gets replaced by an
[url] macro, including the description. So from the divers point of view, this is basically handled as a special form of the
[url] macro, including possible nestings.
So giving a more complex example at the end:
[url]http://some.divesites.homepage/|[img]~s@demo/site01234-001.jpg|Great Site[/img][/url] should result in the given picture, linked to the given url and with the given text attached.
PDF Export Issues
Since with long descriptions not all of your texts may fit on one PDF page, you can define the "block" which should go here by using HTML comments:
<!-- PDF_START --> means to ignore everything before that line for PDF export, and
<!-- PDF_END --> means to ignore everything after it. As for now, you may use each of this comments only once per record. You can place them into your ADL notes field or to the "external" notes, and you can even have the starting tag in ADL and the end tag in the external notes. However, the word "record" here spans both – i.e. both notes fields together form a single one.
Resulting text will be checked against the
$pdf_chars_per_pix settings and truncated accordingly.
One more thing to keep in mind is: the TCPDF engine used to generate the PDFs is very picky when it comes to HTML. So take care to
- use either plain text - or XHTML if you need tags (PDL however tries to keep track to fix up your code to a certain degree)
- when using images, always specify HEIGHT and WIDTH – or it may be screwed up in the PDF (text length calculation may also fail then)
- hmm – some more things may be added here when we find them.