lb_Gallery - a CMSimple Lightbox-Gallery Plugin

Version: 1.1, 2010-09-16
©2008-2010 by Holger Irmler http://CMSimple.HolgerIrmler.de
based on Michael Svarrers Gallery-Plugin v0.9

@doku_version: 2010-09-16

Warning:
This plugin is not compatible with the original version from Michael Svarrer or any other, at the moment available, clones of it.
It's not possible to run the original plugin, or another modificated version, together with this plugin on the same CMSimple installation!
To indicate that, the function call is changed to "lb_gallery()". Comments or extra informations, created with another version, will be left
untouched but they're unsupported in this plugin!


Contents




I. Changes to Svarrers latest v0.9 ...

II. Setting up ...

  1. Make a backup of your files!
    It's always nice to have a backup before you mess around with the system

  2. Install the plugin loader, if not already done!
    More informations about the plugin loader can be found here http://www.cmsimplewiki.com/doku.php/pluginloader/start

  3. Download the Lightbox-Gallery plugin, unzip and keep the folder structure
    New versions should be available from
    http://CMSimple.HolgerIrmler.de .

    The folder structure will look like this:
    +-GALLERY
    | index.php
    | admin.php
    | |
    | +-CONFIG
    | | config.php
    | |
    | +-CSS
    | | stylesheet.css
    | |
    | +-FONTS
    | | font.ttf
    | |
    | +-HELP
    | | help.htm
    | |
    | +-IMAGES
    | | some_images.img
    | |
    | +-LANGUAGES
    | | en.php
    | | xx.php
    | | yy.php
    | |
    | +-LIBS
    | | |
    | | +-SOME SUBFOLDERS
    | |
    | +-SECURIMAGE
    | | some_scripts.php
    | | |
    | | +-SOME SUBFOLDERS

  4. Upload the folder gallery and it's content to the folder called PLUGINS (the plugin loader)
    After the upload to the plugin folder your structure should look like below:

    The folder structure will look like this:
    +-PLUGINS
    | index.php
    | |
    | +-GALLERY
    | | index.php
    | | admin.php
    | |
    | | +-CONFIG
    | | | config.php
    | |
    | | +-CSS
    | | | stylesheet.css
    | |
    | | +-FONTS
    | | | font.ttf
    | |
    | | +-HELP
    | | | help.htm
    | |
    | | +-IMAGES
    | | | some_images.img
    | |
    | | +-LANGUAGES
    | | | en.php
    | | | xx.php
    | | | yy.php
    | |
    | | +-LIBS
    | | | |
    | | | +-SOME SUBFOLDERS
    | |
    | | +-SECURIMAGE
    | | | some_scripts.php
    | | | |
    | | | +-SOME SUBFOLDERS

    Create a folder with an unique name, e.g. "gallery", by ftp in the root of your CMSimple installation.
    Give this folder write permission to the script (depending on your server, up to 0777).
    Create all your galleries as sub folders of this folder "gallery".

  5. Login to CMSimple to edit/create pages.

  6. Create a gallery page

    A code like below:

    <h1>Demo Gallery</h1>
    #CMSimple $output.=lb_gallery('gallery/test/');#

    will create a page, called Demo Gallery, in CMSimple and on the webserver it will create
    a subfolder called test inside the folder gallery.


    If you, after saving the page, go to 'NORMAL MODE' you should see a page like below:

    #########


    Now your gallery is ready to use.


    If you want to include or create this gallery in a 2lang-page, use a code like below:

    #CMSimple $output.=lb_gallery('../gallery/test/');#

  7. Putting pictures to the gallery
    You can upload pictures to the gallery by the following 2 methods:

    1. FTP upload via your favorite FTP program,
      this method is preferred if you have to upload a lot of pictures.
      You must put your *.jpg pictures in the folder "gallery/test/", created by the script in step 6.

    2. Upload via the gallery admin part, login to the CMSimple,
      select the gallery from the available plugins dropdown box and upload your pictures via the upload form at the bottom of the page.

  8. Generating the files
    If you access your gallery page Demo Gallery, created in step 6, the gallery plugin should generate the thumbnails,
    the files for comments and other stuff and the additional html-files.

  9. Change the settings
    In the gallery plugin configuration different settings for the gallery can be changed.

    #########

  10. Trouble shooting
    If you run into problems please go to http://CMSimple.HolgerIrmler.de and look for advice or try to get help
    from the community at http://www.CMSimpleForum.com.



III. Advanced usage ...

  1. Use a Lightbox-script to show your pictures:
    There are two ways to replace the PopUp with a lightbox-script:

  2. Multiple configurations and / or css-files on your site:

    You can define different css and / or config - settings to every CMSimple-page that contains a gallery on your site.
    Just call your gallery with a additional parameter:

    #CMSimple $output.= lb_gallery('gallery/test/','MyOtherConfig');#


    and make sure that 'MyOtherConfig' refers to a copy of config.php and / or stylesheet.css with
    the different settings you prefer for this gallery-page.

    Note: You have to enter the string for 'MyOtherConfig' without an extension, but you have to create files like 'MyOtherConfig.php'
    and / or 'MyOtherConfig.css' in the config- or stylesheet-folder.
    Unfortunaly you can't create or edit this additional configuration-files inside the plugins admin-area until now.
    Please use your local editor and ftp these files to your web space.

  3. If you need more detailed or formated descriptions for your pictures:



  4. If you need no additional descriptions and want to show the big picture direct from the thumbs-page:

    Follow this steps, to skip the details-page:

  5. Mail Notification on new comments

    If you set "comment notification mail address"  to a valid emailaddress, you'll receive a short notification on every new comment at your galleries
    (if comments with "show comments"  = "true" are enabled).
    There are some more options on this function:
    Beside this, you'll receive a link to the picture with the new comment in the notification mail.


IV. Configuration settings:

Setting Possible Values Description
addcomment redir to thumbview: true/false Set to "true" to redirect to thumb-page after a comment is added
adv popup: true/false Set to "true" to replace the PopUp by a fixed sized version with the dimensions below.
This PopUp can show the title below the image
adv popup height: xxx PopUp-height in px
adv popup width: xxx PopUp-width in px
check for gd true/false If set to "true" the gallery checks for a installed GD-Lib and show the version
comment charset charset Defines the character set used in conversion of the comments.
The default character set is ISO-8859-1. If you have weired characters in your commets
try to set the correct value according to your CMSimple setup.
(For more details see the table of supported charsets below)
comment notification mail address: Your email If set to a valid email, you'll get a notification on new comments
comment notification mail from: empty /
xxx@domain.tld
You can enter here the (fake)sender of the notification mail. The string must be in a format
like a mailaddress e.g.: gallery@yourdomain.tld. If empty, a default value will be used.
delimiter: § The field separator within the comment files.
DO NOT CHANGE IF YOU NOT KNOW WHAT YOU'RE DOING!
grafnav true/false "true" to enable a graphical navigation which uses prev-, next-, thumbs- images defined below.
The images must be stored in the folder ./gallery/images
("title" and "alt" is taken from the prev-, next-, return to thumbs - setting in the language file)
grafnav next img your_image.ext Filename of an image for the "next" - link eg.: nav_grayline_arrows_next.gif
grafnav prev img your_image.ext Filename of an image for the "prev" - link eg.: nav_grayline_arrows_prev.gif
grafnav thumbs img your_image.ext Filename of an image for the "return to thumbs" - link eg.: nav_grayline_arrows_thumbs.gif
include external editor: includefile.php Set the name of the include-file for an external editor which controls the external html-file
include external htmlfile: true/false Set to "true" to enable the output of the external html-file in the frontend
main max size xxx Max. size of the picture on main(details)-page in px
memory limit xxM The memory limit for uploads in Mb accepted by the gallery
(maybe your server accept another value)
multilanguage comments true/false Set to "true" to create multilanguage comment files,
"false" to use the same comment files in every language
multilanguage html-file: true/false Set to "true" to create multilanguage html files, "false" to use the same file in every language
nav position details top/bottom/both Position of navigation on the main(details)-pages
nav position thumb top/bottom/both Position of navigation on the thumb-pages
number of thumbs xx The number of thumbs per thumbnail page
on the fly images true/false Set "true" to enable watermarking of your pictures
resize max xxx Size in px, (width or height) the pictures get resized to on upload, if enabled
resize on upload true/false "True" to auto-resize pictures on upload by the backend. The new size is defined in 'resize_max' setting.
resize quality xxx Qualitiy of the jpeg-compression: 100 = best quality (but big files)
show bigpic direct from thumb true/false Set to "true" to skip the details-page and get a PopUp or Lightbox direct from thumb-page
show comments true/false Set to "true" to show the comments and the comment-form
show comments thumb: true/false "True" to show the number of comments on the thumbnail page, "false" to hide this message
show extrainfo true/false Set to "true" to show the extrainfo-fields
show extrainfo add br true/false "True" returns an additional empty line between each extrainfofield in the output
show extrainfotext in new line true/false "True" to show the text of the extrainfo below the field title
show hr between comments true/false "True" adds a horizontal line between the comments
show latest comment first true/false "True" returns the latest comment as the first in the output
show nbr of pics true/false Set to "true" to show the headline "xx Pictures in this folder"
show search true/false Set to "true" to show the search-form
show title true/false Set to "true" to show the picture-title, "false" will hide the titles at all
show title thumb true/false If titles are enabled, "false"  will hide the titles on the thumb page
thumb crop true/false "True" or "quadrate" will create thumbs with width = height, "height": all thumbs will created with the same height, "width": all thumbs will created with the same width, set to "false": to get thumbs in portrait- or landscape-format.
thumb quality xx The quality of the thumbs created by the plugin (75)
thumb size xxx The size (width in px) of the thumbs created by the plugin
title placement top/bottom The placement of the title
use anchor on detailspage true/false "True" to integrate an anchor above the navigation on the details-page
to avoid scrolling down on pages with large headers above the content.
use dropshadow js true/false True integrates a javascript which adds a shadow and a border to your images
use external lib xxxxxxxxx External JS-library to load by the plugin (refers to a subfolder-name of "/libs/"
use lightbox true/false Set to "true" to replace the PopUp by a Lightbox-script
use rel attrib xxxxxxxxx The string of the "rel=..." attribute, according to your Lightbox-script
watermark color xxxxxx The hex-color of the watermark text without the leading '#'
watermark font arial.ttf / X The name of a TTF-Font for the watermark in the /fonts-directory or a Number of a GD-Font
Check out the Fonts_HowTo.txt in ther folder /gallery/fonts to find more informations 
watermark font size xx Font-Size of the watermark
watermark h align left/center/right The horizontal alignment of the watermark
watermark margin x The size of a margin around the watermark in px (0)
watermark text Your text Enter the text for your watermark here
watermark v align top/center/bottom The vertical alignment of the watermark

Following character sets are supported in PHP 4.3.0 and later:

Supported charsets
Charset Aliases Description
ISO-8859-1 ISO8859-1 Western European, Latin-1
ISO-8859-15 ISO8859-15 Western European, Latin-9. Adds the Euro sign,
French and Finnish letters missing in Latin-1(ISO-8859-1).
UTF-8   ASCII compatible multi-byte 8-bit Unicode.
cp866 ibm866, 866 DOS-specific Cyrillic charset. This charset is supported in 4.3.2.
cp1251 Windows-1251, win-1251, 1251 Windows-specific Cyrillic charset. This charset is supported in 4.3.2.
cp1252 Windows-1252, 1252 Windows specific charset for Western European.
KOI8-R koi8-ru, koi8r Russian. This charset is supported in 4.3.2.
BIG5 950 Traditional Chinese, mainly used in Taiwan.
GB2312 936 Simplified Chinese, national standard character set.
BIG5-HKSCS   Big5 with Hong Kong extensions, Traditional Chinese.
Shift_JIS SJIS, 932 Japanese
EUC-JP EUCJP Japanese

Note: Any other character sets are not recognized and ISO-8859-1 will be used instead.


V. License & Acknowledgment

This plugin based on Gallery 0.9, developed by Michael Svarrer.
The initial code had been highly changed, some bugfixes and a lot of new features had been included.
I have the written permission of the author for using  his code
and to release ´this new work under a license of my choice.
A big "Thank you" goes to Gert Ebersbach for sharing his time, ideas and code/css proposals.

Some of the bundled libraries come with their own license.
Please check the files in the subfolder "/libs/" !

It was a lot of work building this plugin.
So please be fair and accept this simple license:


Terms of use:

This plugin is free to use only on private websites.
The link "made with lb_Gallery .." to http://cmsimple.holgerirmler.de must
stay visible and clear readable in the output.

On private websites, it is possible to remove the back-link if you buy a Remove Link License.
Please visit http://cmsimple.holgerirmler.de to find out how to get a license.

You must buy a Commercial License if you want to use this work on a commercial page.
A website with paid advertisements is a commercial page.
Of course you're allowed to remove the back-link with a payed license.
Please visit http://cmsimple.holgerirmler.de to find out how to get a license.

Without my permission
- it is not allowed to redistribute this plugin
- it is not allowed to build and/or distribute modificated versions based on this plugin


Anyway, if you're allowed to use this plugin for free,
consider donating a few bucks to me via PayPal.

THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.