PiXfr Photo Module 1.1.1 Documentation

• Official PiXfr Photo Module project homepage    [ http://pixfr.com/ ]
• PiXfr Photo Module download page    [ http://pixfr.com/download.php ]
• Local documents:
  • Version history: credits
  • General notes: readme
  • License: license

Requirements

• PHP3 or PHP4.
• GD library for thumbnails generation. Not mandatory since there is many other ways to generate thumbnails. GD version must be 1.6.2 or above to deal with JPEG. Version 2 of GD (still in beta stage) has very improved functions for image resizing that are fully supported by PPM.
• No database.

Introduction

PiXfr Photo Module (PPM) can generate massive photo galleries with the corresponding thumbnails when used in conjunction with GD library. PPM can be used as as a standalone application or as a module for PostNuke > 0.62 or PHP-Nuke 5 or above.
Currently PiXfr Photo Module can:

• generate main page with many layout options
• generate category pages with links to the corresponding galleries
• generate gallery pages with links to the corresponding pictures
• communicate in 6 different languages
• generate thumbnails of the pictures if used with GD library
• enhance the distribution of the thumbnails on a page

Installation

Quick Install as a PostNuke / PHP-Nuke module:

1. Unzip the distribution INTO the modules directory of your site and be sure to unzip the subdirectories: this will add PPM files in a new module called ppm.
2. You can delete the ppm/standalone directory and all its content.
3. Open the file modules/ppm/config.php in your favourite editor and change the values for $ppm_photo_dir with the directory that will contain categories and galeries (relative to the modules/ppm/ directory, default is my_photos). Have a look at Configuration section for an explanation of all values.
4. Open http://mysite.com/modules.php?op=modload&name=ppm&file=index in your browser. PPM should now display its main page. If some settings are wrong you should correct them acording to the messages shown.
5. Rename the ppm directory as you want (ie photo) so your photo collection will be accessible at bottom of PHP-Nuke Main Menu. You can call PPM with : http://mysite.com/modules.php?op=modload&name=photo&file=index

   PostNuke users are ready to go.

   PHP-Nuke users must edit config.php and set $ppm_nuke_type = 'PHP-Nuke';

Quick Install as a standalone application:

1. Unzip the distribution in the base directory of your site and be sure to unzip the subdirectories: this will add PPM files in a new directory called ppm.
2. Move or copy the content of ppm/standalone into ppm. The file index.php present in ppm will be replaced by the one coming from ppm/standalone, it's OK.
3. You can now delete the ppm/standalone directory.
4. Open the file ppm/config.php in your favourite editor and change the values for $ppm_photo_dir with the directory that will contain categories and galeries (relative to the ppm directory, default is my_photos). Have a look at Configuration section for an explanation of all values.
5. Open http://mysite.com/ppm in your browser. PPM should now display a welcome screen. If some settings are wrong you should correct them acording to the messages shown.
6. Rename the ppm directory as you want (ie photo) so your photo collection will be accessible via http://mysite.com/photo

Upgrading from an older version:

• Dont delete or modify your last PPM install.
• Follow the steps of the quick install but unzip the distribution in an other directory than the one of the older version.
• Edit the config.php file to make $ppmPhotoDir linking to your existant galleries.
• Tune your PPM by editing the config.php file. Now you can decide to delete the older PPM version.
• Note that older PPM ML texts files of versions < 1.1.1 RC2 must be a litle modified to work with PPM 1.1.1.

Configuration

If your ISP use PHP 3 and doesn't parse .php files:

• ALL .php files must be renamed as .php3
• Edit the first line of index.php to have: define('PPM_EXT','.php3');

All configurable data is placed in config.php.

Since config.php is used both by PPM standalone and Nuke module, some entries affects only one of these two usage.
  SA means that this variable is only used when PPM is installed as a standalone application.
  Nuke points a variable used only by PPM as a module for PostNuke or PHP-Nuke.

$ppmPhotoDir string

Sets the relative url (relative to PPM install dir) to your galleries location.
my_photos : default value for included demo galleries.
../../your_photos links to /your_photos at the root of a Nuke site.
../your_photos links to /your_photos at the root of a standalone site if you installed PPM as in the Quick Install Section.

$ppmNukeType string Nuke

Sets the flavour of your Nuke. Must be PostNuke or PHP-Nuke.

$ppmLanguage string

Force a default language file to be used if one asked is missing or wrong.
You must use a language iso code of an existing PPM langage file: eng or fra or spa...

$ppmMaxCols integer

Sets the maximum number of columns displayed in a thumbnails table for a category or a gallery.

$ppmMaxWidth integer

Sets the maximum width a thumbnails line can have. This value is the sum of the width of the thumbnails of this line in pixels.
This apply to Galleries and Pictures TN pages. Note that this value is stronger than $ppmMaxCols: if $ppmMaxCols = 6 and $ppmMaxWidth = 500, we would never have a line of 6 TN if each of them has a 100 pixels width.

$ppmText boolean

Use multilingual "ppm_text.php" files for custom text (1 for yes).

$ppmPanic boolean

Prints a 'panic' link to a serious DataShit page (1 for yes).

$ppmAdminMail string

  SA

Email adress of the site administrator. Printed in PPM error messages.

$ppmColor array

PPM can incorporate different styles of icons, located in images/ppm .

key ['back'] string
    Must be feeled with the background type of your site: light or dark .

key ['color'] string
    Must be feeled with the icon color you want: red, green, blue ...

$ppmCopy array

Concerns Copyright informations displayed at the foot of PPM pages.

key ['active'] boolean
    Prints the Copyright line (1 for yes).

key ['name'] string
    Copyright's owner name.

key ['year'] string
    Copyright's year.

$ppmMain array

Controls the PPM main page layout.

key ['info'] boolean
    Prints a title line with number of categories in PPM main page (1 for yes).

key ['thumb'] boolean
    Show a random TN present in the root of a category (1 for yes).
    To show always the same TN, just put one. Value 0 for classic display, good if you have a lot of categories.

key ['cat_text'] boolean
    Prints multilingual text found in each category.
    This file must be placed in each category and named 'ppm_main_text.php' (1 for yes).

key ['cat_cols'] integer
    The categories are displayed on 1 column by default.
    If you have a lot of categories you can increase that number (in that case, the above keys cat_text and thumb should be set to 0).

key ['cat_align'] string
    Alignment of a category element in its row. Must be left, right or center.

key ['table_width'] string
    Width of the table containing the categories. Can be set in pixels or relative like 60%.

key ['disposition'] string
    Disposition of the image on the category line. Can be left, right or mix (alternate left to right).

key ['gal_count'] boolean
    Display the number of galleries within each category (1 for yes).

key ['refresh'] boolean
    Prints a refresh icon on PPM main page (1 for yes).
    It means you put more than one thumbnail in the root of your categories AND $ppmCat['random_thumb'] = 1.

$ppmCat array

Controls the PPM category page layout.

key ['info'] boolean
    Prints a title line current category infos - name and number of galleries - (1 for yes).

key ['gal_img_count'] boolean
    Show number of pictures in each gallery (1 for yes).

key ['refresh'] boolean
    Prints a refresh icon on PPM category page (1 for yes).
    Nonsense if $ppmCat['random_thumb'] is not set to 1.

key ['random_thumb'] boolean
    Print a random thumbnail taken in each gallery (1 for yes).
    Set it to 0 to take the first TN in alphabetical order. To chose the TN to be displayed for a gal, name the picture with a '_' or '0' as fist character

key ['thumb_layout'] string
    Position of the name of a galery: at the top or the bottom of a TN or alternativly. Must be top, bottom or mix.

$ppmGal array

Controls the PPM gallery page layout.

key ['info'] boolean
    Prints a title line with number of pictures in the gallery (1 for yes).

key ['img_number'] boolean
    Prints image number under each thumbnail (1 for yes).

key ['img_name'] boolean
    Prints image name under each thumbnail (1 for yes).

key ['img_size'] boolean
    Prints image size in K under each thumbnail (1 for yes).

key ['img_resolution'] boolean
    Prints image resolution in pixels under each thumbnail (1 for yes).

key ['img_newline'] boolean
    Prints image resolution on a new line and enable spliting of long names (1 for yes).

key ['msg_tn_missing'] boolean
    Prints error messages when thumbnails are missing (1 for yes).

key ['gal_links'] boolean
    Prints the links to the others galleries under the displayed one (1 for yes).

$ppmPic array

Controls the PPM picture page layout.

key ['gal_links'] boolean
    Prints the links to the others galleries under the displayed picture (1 for yes).

key ['text_at_top'] boolean
    Prints the description text of picture_name.jpg.php included in the file picture_name.jpg.php (1 to print it above the picture and 0 under).

$ppmGd array

Configure thumbnail generation by GD library.
Infos about GD can be found at http://www.boutell.com/gd/

key ['generate'] boolean
    Enable Automatic TN generation (1 for yes).

key ['tnheight'] integer
    Height in pixels of the generated TN.

key ['jpegcomp'] integer
    JPEG compression factor of the generated TN.
    Can be set from 1 (small size but bad quality) to 100 (high quality but bigger files).

key ['version2'] boolean
    GD version. The default is 0 for GD version 1.x.
    If you use GD version 2.0 or up, set it to 1 in order to use the High quality functions introduced in GD 2.0.

$ppmDirOut string

Patern of directories or files you want to exclude. To exclude more than one dir use the | like _vti_|test|private.
To take all dirs, the value must be ' ' (space).

$ppmJpg boolean

Set it to 1 to process .jpg files.

$ppmJpeg boolean

Set it to 1 to process .jpeg files.

$ppmPng boolean

Set it to 1 to process .png files.

$ppmGif boolean

Set it to 1 to process .gif files.

Multiligual texts are located in ppm_text.php files in each category and gallery to add custom text to categories and galleries.
A ppm_main_text.php file can also be added in each category that you want to discribe on the main page.

Structure of a 'ppm_text.php' or 'ppm_main_text.php' file:

<?php
  $ppmt_eng = 'This is an english text...';
  $ppmt_fra = 'Ceci est un texte français...';
?>

FAQ - Frequently Asked Questions

I can't see any links to my pictures.
It's a problem concerning the name given to your pictures.
You have to follow this rules:

• Using accents and spaces is a bad idea on unix filesystems.
• Using ? and & is buggy since these characters are used to get CGI variables.
• Bad Names: my dog.jpg you&me.jpg
• Good Names: my_dog.jpg you_and_me.jpg (note that PPM replaces the undescore by a space for display)

These rules are for files AND directories.

I have the error message: main picture directory not found
It occurs when the variable $ppmPhotoDir doesn't link to a correct directory on your server.

• You tried 'galleries' and it fails. Are you in the good level? Try '../galleries' or '../../galleries'.
• Remember the rules concerning the previous question of the FAQ: no accents, spaces, & or ? in a directory name

The PHP config of my ISP has been compiled without GD. How do I generate the thumbnails?
The best way is to use your PHP config, I mean on your local développement machine.

I have found a bug. What can I do?
Please discuss your bug with other users:
http://pixfr.com/ (and choose Forums)

Developers Information

Pixfr Photo Module is Open Source, so you're invited to contribute to it.
No CVS for the moment. If you are some asking for it I'll go for it.
To share your code and ideas you can:

• Use the forums on http://pixfr.com/
• Send a mail to me
• Post an article on http://pixfr.com/