Blank'N'Berg documentation
This documentation isn't up to date at all !
Some options described here no longer exist, and many new features exist,
that aren't documented here yet. A few chapters are unachieved.
Unachieved paragraphs will appear in red.
You can see examples of the application's flexibility here, here and here.
INTRODUCTION
BASIC FEATURES
- Lister Page
- Configuration Page
- Apply and Cancel Buttons
- Option Parameters
ADVANCED FEATURES
- MASTER mode
- Reserved Option Parameters
- Save Checkboxes and Radios
- Config Files
- Handling Config Files
- Parameter Priority
- LOCKED mode
REQUIREMENTS
- Running Apache
- Cookies
- Browser Compatibility
- Script's Filename
NOTES FOR DEVELOPERS
HISTORY
INTRODUCTION
BNB is a picture lister, using a web browser to display the picture content
of a directory (folder), and, through browsing, all its sub-directories (sub-
folders).
It is a PHP script, and needs to be at the root folder of your picture folders,
which needs to be known by Apache as an Apache folder, or being within an
Apache folder's tree. To learn more about all this, read the section entitled
"requirements".
It can be used home to browse your web pictures, or to create quick online
galleries. It will only display the picture types that common browsers can
display. That is: gif, jpg, png and bmp.
Why is it called Blank'N'Berg ?
Well, Blankenberg is a modest Belgian coastal town which hasn't really anything
better or worse than any other, and there's no special reason why I chose it...
If you want to see an example of it working, just visit:
http://fred.dsimprove.org/_fhpl_example/
It is a public domain tool. This means that anybody can do anything with it
without any further permission.
The original author (Fred Scalliet, Belgium) can be contacted at:
http://fred.dsimprove.org/
back to top
BASIC FEATURES
This section assumes that the script is correctly placed at the root of your
picture-folders tree, and that the conditions explained in the "requirements"
section are fullfilled.
The Lister
This script first displays a lister. The lister is divided in several sections
(some of those sections can be absent if there is nothing to display in them):
The Folder List
Click on any of the folder icon to access a sub-folder.
When in a sub-folder, click on ".." to come back to its parent folder.
The Picture List
A list of all the pictures present in the current folder,
that are displayable by the browser.
The File List
A list of all non-picture files present in the current folder,
except for a possible "bnb.txt" and the BNB script itself.
(If you're not in MASTER mode, the configuration files
aren't displayed either)
The Comment Section
If the current folder contains a text file named "bnb.txt",
the content of that file will be displayed here.
The Configuration Button
To access the configuration page.
back to top
The Configuration Page
So it is now time to talk about the configuration page. Note that the configu-
ration page can be locked, but we'll see that later...
Apply and Cancel Buttons
Note: to apply the changes you've made in the configuration and go back to
the lister, you must press on "Apply Changes" (or "Apply & Save"), and then
on "Back > Lister" !
Undo Changes : Resets the form back to as when you last entered the
configuration page.
Apply Default : Applies the developer's default value on the whole
form. If a config file (see further) exists, the parameters for which a value
had been saved in the config file will take that value instead of the
developper's default. If you want to force developer's default on all the
parameters, delete or rename the config file. (There is no config file when
you first run BNB).
Apply Changes : Apply the changes you just entered.
Apply (&Save) : Replaces Apply Changes in MASTER mode.
Back > Lister : Go back to the lister. This equivalues with a Cancel
button if you don't click on Apply Changes first.
back to top
Option Parameters
The first parameters on the configuration page are: background color, text
color, link color, ... So trivial there's no point explaining them.
Now it gets more specific:
Maximum width : That's the maximum width of a picture. Picture narrower
than that won't be resized. Pictures wider than that will be proportionally
shrinked. A [S] symbol will appear under each picture that has been shrinked.
Leave it empty if you never want to shrink any picture.
Folders Per Row : How many folders will be displayed per row, at max,
in the Folder List.
Sort Mode : Upon which criterion pictures and other files will be sorted.
Split Long Filenames... : Maximum 48 characters per text lines.
(note: you can easily find how to change that amount of characters in the
first lines of the source code)
Display All Files As Pictures : Can be useful to check if there are pictures
named with a non-picture file extension, or without file extension.
Display Extended Info : Display the date, time and MD5 of each file
(picture and non-picture). The time is always GMT. The difference between
local (or server's) and GMT time is always displayed next to the file's
time of last modification.
North American Date Foramt : Our yankee friends like to write the month
before the day: MM/DD, while we euros prefer DD/MM. Euro by default ;)
12-Hour Date Format : Displays 12-hour time with am/pm tags instead of
24-hour counting
Compare Files : This option, when checked, will display black buttons
under each picture and file. Those buttons offer you to "set (the picture) as
model" or to "compare (it) with model". First set a picture as model. Then,
each time you compare another picture to that model, an alert box will tell
you if they are identical or different. This features is meant to check if
files with different names would in fact the exact same one. For that the MD5
of the pictures are compared. When the MD5s are the same, it is extremely
likely that the files are the same (you can rely on that). When the MD5 are
different, it is absolutely certain that the files are different, by at least
one byte.
This option won't work on browsers that don't accept session cookies.
Jump Back To File After Reload : After clicking on one of the compare
buttons, the page needs to reload. If this option is checked, the picture of
which one button was clicked will be at the top of your window. Otherwise
the top of the page will, and you might have to scroll down to find the
picture back. This is a detail, really :)
Error Message Color : Error messages are displayed if you type a wrong
character in an input field, or if a problem happened while saving/loading
a config file.
back to top
ADVANCED FEATURES
There are a few changes to the behaviour of BNB that you can make by modifying
the first lines of the source (index.php). It is clearly commented there, so
I will only document the most important ones here. Among the non-documented
are: the possibility to change the expected filename of a comment file,
a config file, or the script itself, and a few other details...
back to top
Master Mode
To switch to MASTER mode, you must modify a line at the very beginning of the
source:
replace
define ('MASTER',false) ;
with
define ('MASTER',true) ;
The first thing you'll notice is some coloured-background areas on the
config page, that contain the save checkboxes and radios.
You will also also notice that there are some new option parameters, along with
the "master mode only" mention. These are the reserved option parameters.
back to top
Reserved Option Parameters (MASTER mode only)
Save Column Color : That's the background color for those areas that contain
the save checkboxes and radios.
Character Set : Useful if the names of your files and folders contain
region-specific characters (such as western- or central-european ones...).
Allow Search Engine Indexing : When checked, the search engines (such as
Google, Altavista, Yahoo, ...) are allowed to index your page and propose them
as search results. Note that it can take up to a few weeks for that to happen,
and more than that for them to "forget" your pages.
So (de)activating this option doesn't make any sense if you don't save it to
a config file.
Allow Search Engine Caching : Some search engines that propose their
visitors to view an archived copy of a page as a second option to visiting
your site won't be allowed to do so with your page(s) if you don't check this
option. Again, it makes no sense to change this one without saving it to a
config file. Doesn't make sense either to check it without checking the
previous one.
back to top
Save Checkboxes and Radios (MASTER mode only)
Normally, modifying the configuration only affects the current session.
That's why it's ok to let your visitors access the configuration page when not
in MASTER mode (although, if you want to prevent that too, you can switch to
LOCKED mode).
Now if you want to save changes that affect every session (= every visit), you
need to save them to a file. That's what this section is about.
Check the "Save Selected..." box in the top right corner of the config page
to save some parameters into a config file. The parameters that will be saved
are the parameters of which the savebox (the box next to the parameter's name
in the colour-backgrounded column) is checked. If a config file already exists,
it will be overwritten. This means that the parameters of which the savebox
is not checked will be deleted from the file if they were present.
Note that there is a difference for each parameter between being empty and
being absent from the config file: for some parameters, being empty has a
special meaning (see commentaries on the config page), while for others that
would be a bug. Being absent, on the other hand, means that the default value
will be applied. This is a simplified version of config files handling though.
For more precision, read the sections: "handling config files"
and "parameter priority".
There is then a set of two radio buttons that we haven't talk about yet. They
let you choose between "to Global config" and "to Folder Config".
It was assumed until now that you were saving to Global Config.
A Folder Config is a config valid for one folder only. You can save up to one
config per folder. It is possible to get nice results by combining global
config (for parameters that are the same for all folders) and folder config
(for parameters that have a different value for every folder, or a value
different for one folder in particular than the value saved in the global
config). For more information about folder config files, read "handling config
files" and "parameter priority".
Note that the user-friendliness of the config-saving interface directly depends
on what browser you are using. It will always work, though. To know more about
this, you should read the "browser compatibility" section. (and NO, Internet
Explorer is definitely not the most appropriate one)
It will also be a lot more user-friendly if cookies are enabled on your browser.
back to top
Config Files
To save, delete or modify a config file, you must be in MASTER mode.
Config files are still loaded in any mode, though, once they're present.
Handling config files
...saving as explained in the "save buttons and radios" section...
back to top
Parameter Priority
For each parameter, BNB seeks for a value in that order :
- If a new value was entered in this session, that value will be applied.
- Otherwise, if there is present in the (possible) Global Config file,
that one will be applied.
- Otherwise, developer's default value will be applied.
The currently applied values always display in the config page.
Note: If there is a folder-config file in a folder, ALL session parameters
will be ignored while you're viewing the content that folder.
This doesn't apply to its sub-folders.
config page locked (in handling file section > folder cfg ?)
back to top
Locked Mode
In LOCKED mode, the configuration page is not available at all, or the
ability to save, modify or delete config files. Config files already present
will still be loaded of course. Use locked mode when making your picture
collection online, if you don't want the visitors to be able to modify any-
thing to the lister's outlook, not even within their own session.
To switch to LOCKED mode, you must modify a line at the beginning of the
source:
replace
define ('LOCKED',false) ;
with
define ('LOCKED',true) ;
back to top
REQUIREMENTS
Running Apache
back to top
Cookies
The "Compare Files" option won't work if your browser doesn't accept session
cookies. No error message will appear though: it will just not work properly.
The saveboxes on the config page will be frequently resetted if your browser
doesn't accept permanent cookies, which won't prevent the system from working
but can be rather unconvenient.
In most browsers you can turn cookies on/off via its option pannel.
Depending on browser: menu> "options", "configuration", "internet options",...
Note: turning cookies off for security's sake is, imho, useless paranoia ;-).
Cookies are just character strings ! They can't perform any action on your
computer.
back to top
Browser compatibility
Blank'N'Berg was tested on these browsers (april 2004 versions):
- Mozilla FireFox for Linux, Mac OS X and Windows
- Safari for Mac OS X
- Camino for Mac OS X
- Internet Explorer for Windows
- Konqueror for Mac OS X and Linux
Everything works fine under the first four ones, except for one detail:
BNB's "remembering" of which saveboxes are checked in MASTER mode from one
page-loading to another. This is not a serious bug but its unceveniency can
lead to mistakes if you're not very attentive. Here follows a description
of this feature's behaviour under each tested browser:
Mozilla FireFox & Camino:
Everything works fine under these browsers, which by the way are the ones which
comply the most accurately to the W3C norms.
Safari:
- no remembering from one visit to the config page to another.
- no remembering of difference in saveboxes' states between global-save and
folder-save
This is due to the fact that Safari is still under development (this is april
2004) and doesn't support some javascript events yet. We can't really call
that a bug, and may assume that as soon as Safari starts supporting "onChange"
events it will work just fine.
Internet Explorer:
- no remembering of difference in saveboxes' states between global-save and
folder-save
This is due to the fact that this pathetic excuse for a browser is a real
bugbag, and handles "onChange" events like my grandmother would an MP3 encoder.
Since Microsoft is well known to follow their own undocumented rules instead
of complying to existing standards, we can expect that the problem will never
be solved. Therefore the feature has been permanently disabled in BNB under I.E.
If you're still using Internet Explorer, I suggest that you get some free
W3C-compliant browser instead, for example from http://www.mozilla.org/
Konqueror
BNB is absolutely not compatible with Konqueror. Don't insist unless you want
to attend a bug festival on almost every feature. Next version maybe ;-)
The visual design of BNB's config page has been optimized for Mozilla Firefox
under Windows. Quite unimportant though ;-)
back to top
The Script's Filename
The script always needs to know its own filename.
The filename is now "index.php".
If you rename it, you must also change a line inside it, like this:
define ('THIS_SCRIPT_FILENAME','index.php') ;
--> replace "index.php" with the new filename.
back to top
NOTES FOR DEVELOPERS
Viewing/Editing The Source
The source can be viewed without word-wrapping with, for example, the following
configuration: 1024x768, maximized editor window, font: Courrier New, size: 9.
Picture File Types
If your browser supports more types, and you're not making a public page,
you can add new supported types by modifying the $SUPPORTED_TYPES array in
the beginning of the source.
back to top
HISTORY
v0.2003-04-10
- Configuration file management debugged and improved ;-)
- 'Display all file as picture' option
- Extended Info
- File Compare
- Different Sort Modes
- Reduction of the application to only one file (embed folder.gif)
- Renaming HPL to BNB (Blank'N'Berg), because the name HPL was already
used by bastards. So much for recursivity :(
v0.2003-03-13
- Support for configuration files (beta)
- Configuration page (not idiot-proof, though)
- Renaming "HTML Picture Lister" to "HPL Picture Lister"
for the sake of recursivity !
v0.2003-03-12
- Session mode implemented
- Support for comment files
v0.2003-03-??
- First draft of HPL
|