picy Gallery - Manual
Updated information might be available at the official picy homepage:
http://picy.infinitesimal.org/
0. Contents:
- About
- Basic Setup
- picy Gallery
- picy Configurator
- Advanced Setup
- Settings
- Themes
- Credits / License
1. About
picy is a PHP folder gallery. If one wants to create a web gallery to exhibit some pictures the
manual task of doing so is quite time consuming and if changes have to be made to the gallery,
many individual pages have to be edited. PHP is a server-side scripting language that can
greatly facilitate this task. picy is a script written in PHP that takes on this task. Because
it does not create the individual pages once but each time the gallery is viewed, changes can be
done easily and quickly. As soon as a picture is uploaded to the folder picy is used, it will be
shown in the gallery. Folders containing pictures can also be uploaded and will be shown as
sub-galleries in picy. picy will automatically reduce the image size to create thumbnails that
help giving an oversight when browsing the gallery and reduce loading time drastically opposed to
loading the full-sized images.
Beyond this basic functionality, picy also provides some more features. The whole script and
everything thats needed to run it (images, themes) are included in one single file. This makes
uploading and using the gallery easier and tidier. picy is fully themeable, the HTML code that
defines to look of the gallery is separated from the remaining PHP code and is thus much easier
to edit. picy supports using multiple looks at the same time, all contained inside the picy
script file or as external files. picy comes with a dedicated configurator script, that helps
editing the script file and changing the behaviour of the script. It helps to import, export
and edit themes, add or remove images embedded in the script file and helps tuning the picy
settings. picy also provides a hotlink protection to secure the images of the gallery from
bandwidth abuse. The are four different methods to do this to suit the possibilities of every
environment.
[top]
2. Basic Setup
2.1. picy Gallery
picy Gallery come already pre-configured and if you're fine with the standard settings, there's
nothing for you to do. Simply upload the
picy.php file to your web host. You can rename
it co
index.php if you want you're gallery to be accessed when browsing to the containing
folder (i.e. the gallery will be shown for "gallery/" and not "gallery/picy.php").
The fist time you open the script in your browser, picy will take all JPG, GIF and PNG images
into the gallery and create thumbnails for them. There's nothing more for you to do than enjoying
the gallery. If you want to set-up sub-galleries, you have to create folders in the same folder
the picy script is located and fill them with the images you want to put in the sub-gallery. Then
give each folder that is supposed to be a sub-gallery the extension ".pc0" (i.e. "myfolder" will
become "myfolder.pc0") and it will appear in the gallery.
2.2. picy Configurator
Note: The picy configurator is a potential security risk. It edits PHP scripts and this
can be exploited to modify other pages on the server or as a starting point to hack the server.
Don't upload the
picy_conf.php script to the webserver if you don't need it. And if you
upload it, install it immediately and provide a secure password.
The picy configurator can be used to edit, install, export and remove themes, embed and remove
pictures in the picy script file and to change the picy settings. First simply upload the
picy_conf.php script to your webhost. It doesn't have to be in the same folder as the picy
script file. Make sure that the folder that contains the picy_conf.php and the picy script file
are writable (probably CHMOD 0666). After finishing the installation, you can revert the changes
to the folder but the picy script file needs to be writable as long as you want to use the
configurator to do changes. If the configurator can't write to a location it should be able to
it will either report this beforehand or fail with an appropriate error.
The first time you run the picy configurator script, it will start the installation procedure.
Firstly and most importantly it will ask for a password to ensure that no one can use the
configurator who shouldn't be using it. The password will be saved SHA-1 encrypted. This way the
password will still be verifiable but the original password can't be guessed from the encrypted
SHA-1 password hash. Next you have to enter the path to the picy script file. If the configurator
script is in the same folder as the script file, "picy.php" or respectively "index.php" should
suffice. If this is not the case, you have to provide either a full or relative path.
The output and backup options are best used in one of two ways:
- Let the configurator overwrite the actual picy script file. This is most convenient since
changes are immediately seen in the gallery. The downside is, that if a change produces bad
code or some settings are faulty, the gallery might get unusable. It's possible to
instruct the configurator to create a backup of the script file each time it writes to it
so that bad changes can be reverted. Although only one backup is created and thus the picy
script should be checked after each change.
- The configurator is also able to write the changes to another file. The actual gallery
will not be touched and thus is safe from bad changes. The changed script file then can be
tested individually and if working, the original script exchanged with the new one.
For I. set both script file and output file to the same path/file and optionally activate
the backup. For II. set the output and script paths to different locations and deactivate
the backup. For II. the output folder needs to writable and for the backup option, the
picy script folder needs to be writable.
After installation is finished, the configurator will create a
picy_conf.set.php in
the same folder as it resides. This file hosts all the settings. If it's deleted, the
configurator will have to be installed again.
The picy configurator can also be installed manually. All settings are also located inside
the
picy_conf.php script file. First set 'sext' to false and then no installation is
needed and the settings inside the script file will be used.
[top]
3. Advanced Setup
The picy script file consists of the settings at the top, the actual code in the middle and
the embedded pictures and themes at the end. When using the picy configurator, it reads the
picy script file, makes changes to it and writes it back. All changes done by the picy
configurator can also be done by hand. Though, some PHP knowledge might be needed.
The picy configurator minimizes this need of knowledge and saves browsing through code
which can be quite tiresome. Some parts of the picy Configurator merely display PHP code
bit more nicely formatted and makes editing the picy script from any computer more easy.
3.1. Settings
Settings can be changed in two flavours inside the picy configurator. First there are the
formatted settings that should be the first stop if you want to change anything. Secondly,
there are the raw settings. This is basically the PHP code displayed in a more comfortable
layout. While not all settings are accessible in the regular settings, the raw settings
will always display all of them. The downside of the raw settings is that the values entered
need to be PHP-parseable. Strings need to be enclosed in apostrophes, some settings are stored
in arrays and some are booleans (true/false). If you look at them I think it's possible to make
out how they should be entered and some trial & error will do also.
All Settings are also commented so I will not go into them here again.
3.2. Themes
Themes can be stored inside the picy script but also in external files. There's actually not
much difference. The embedded themes merely reside in the picy script, they are not automatically
usable in the gallery when they are embedded in the script. The point of intersection between
the gallery and the internal and external themes is an array that can be found in the raw picy
settings or using the theme setup option of the picy configurator.
Themes are referred in the gallery by the index of this array. In the theme setup, the index
(number) is displayed left of each row. The standard theme can be defined setting the settings
value 'cthm' ('Standard' in the theme setup) to the index number of the theme. The folder
extension .pcx can be used to override the standard theme. For example, .pc3 would result in
a sub-gallery with the theme that has te index 3 in the theme array. The same goes for the URL switch,
adding &thm=3 at the end of the url would have the same result (if activated).
For internal themes, the short name has to be supplied to referr to the theme, for external
themes a relative path will do.
[top]
4. Credits / License
picy was written entirely by Adrian Stutz with the help of of various PHP web resources but
mainly with the great help of the official PHP documentation.
This script is distributed under a creative commons license that allows the change and
redistribution of this script for non-commercial purposes and under the same creative commons
license only. Note that you have to give the original author (me) credit. If you create your
own theme / alter the standard ones I ask you to always include a link to the creative commons
license and a link to the picy homepage.
[top]
