Photodir CSV Information & Tutorial

General Infos:

The focus of the Photodir photo gallery lies in very »simple«. All used text and data are extracted from CSV files. The photos are managed on a local computer. Only a copy must be stored on the server. Photodir is only a software for displaying photos and not a photo managing tool. The displayed resized images are created on the fly by the first page visit (consider the lazy image load by thumbnails). The »simple« requires a bit of discipline.

Default plug-ins:

In the Photodir (download) are few self coded plug-ins allready included. All for the photo single page.

• CSV photo copyright info (photo-copyright).
• CSV photo GPS coordinates — a link to openstreetmap (photo-gps-coords-osm-link).
• Photo lightbox — by photo onclick (photo-lightbox).

For the deactivation of a plug-in please delete each plug-in folder.

Explanations:

• The URL-paths have included the photo file extensions to make the software simpler. (URL-paths without the file extension depends only photo filenames with one file extension.)
• The using of keywords (tags) for a search and for linking is without any database to much for a server. (Keywords can be displayed with a self coded plug-in.)

Photo resize file cache:

• For each photo file are a resized photo file is created, when the photo size is greater than the thumbnail, the single page or the lightbox photo.
• Recommended: Use only photos with the same size as the single page photo or the lightbox photo.
• The resized photo files are created by the first visit of a album page or single photo page.
• The resized photos are saved in the folder "resizes".
• For refresh a resized photo, deleted the resized photos.
• It's possible to deleted all resized photos every time, because all are newly created by the next visit of a album page or single photo page.
• It is possible to delete photo folders inside the resize directory, but not the resize directory self.
• Consider that the creating of the resize photos is server CPU heavy.
• For smaller photos only a symlink to the photo folder will be saved in the folder "resizes".

Album thumbnail and album title and description:

• Select a photo file from each photo folder and save it as a album photo file one level higher and rename it with the folder name.
• When more than one parent folders are exist, save a selected photo file in each parent folder and rename it with the each folder name.
• Write the album title and description in a CSV table with the filename of the current folder.
• The album title and description are extracted from this CSV table.
• All foldnames and filenames are case sensitive.

Consider: Inside each photo folder must be a CSV file with the folder name.
Consider: Each photo folder must have photo files with the same folder names in the folder.
Hint: Mouse hover the folders and see the associated photo file.
(case sensitive)

┬
└┬photos
 ├─autumn
 ├─spring
 ├┬summer
 │├─2000
 │├─2010
 │├┬2020
 ││├─August
 ││├┬July
 │││├July.csv	→ CSV for photos inside album "July/"
 │││├IMG0001.JPG
 │││├IMG0002.JPG
 │││└IMG0003.JPG
 ││├2020.csv	→ CSV for albums inside "2020/".
 ││├August.jpg	→ Thumbnail for album "August/".
 ││└July.jpg	→ Thumbnail for album "July/".
 │├─2000.jpg	→ Thumbnail for album "2000/".
 │├─2010.jpg	→ Thumbnail for album "2010/".
 │├─2020.jpg	→ Thumbnail for album "2020/".
 │└─summer.csv	→ CSV for albums inside "summer/".
 ├index.csv	→ CSV for startpage "/".
 ├photos.csv	→ CSV for albums inside "photos/".
 ├autumn.jpg	→ Thumbnail for album "autumn/".
 ├spring.jpg	→ Thumbnail for album "spring/".
 └summer.jpg	→ Thumbnail for album "summer/".

Consider: Each folder required a CSV file with filename of the current folder and data for the inside subfolders or files.
Consider: Each folder required a CSV file for the subfolders or files inside the inside subfolders.
Consider: Without a thumbnail for a album, a placeholder thumbnail is used.

Sort photos and albums:

• The order in the CSV tables are adopted.

Recommended restrictions:

• Foldname/Filename:
  • Foldnames/Filenames only with a-Z and 0-9 and - (Pict-12345.jpg).
  • No fold/filenames with underline "_".
  • No fold/filenames with whitespace " ".
  • No fold/filenames with umlaut or eszett (ä ö ü ß).
  • No fold/filenames with special characters.

The file extension of the photo files is not prescribed. (jpg or JPG is allowed)
The file extension of the album thumbnails must be set in the config.php

Recommended restrictions:

• CSV tables:
  • Filenames must be the same as the foldnames (case sensitive).
  • CSV table separator: ;
  • CSV table cell content in double quotes: "
  • CSV table charset: UTF-8
  • File extension: csv (case sensitive)

Installation manual & usage

Installation

1. Download the Photodir zip file.
2. Upload the Photodir zip file on the server.
3. Unzip the Photodir zip file.
4. Optional: Configurate your Photodir in the config.php file.
5. Upload your photo folders in the photos directory.
6. Recommended: Upload only photos with a hardcoded watermark.
7. Recommended: Upload only photos with the configurated maximum width and height.
8. Please be fair and make a donation.

Requirements

The Photodir requires PHP (version 8 and newer recommended) and PHP ImageMagick.

Usage

Beginners:

• Install the Photodir on a webhost/server.
• Upload your photo folders in the photos directory.
• ready!

Amateurs:

• Use album thumbnails.
• Use CSV.

Experts:

• Configurate the Photodir with the config.php.
• Modify the style.
• Customize the Photodir.

Specialists:

• Code own plug-ins.

Download Page

Modification & extensions

Modification

Custom style: The style is modifiable with CSS in the style-custom.css. This CSS will be overwrite the default CSS, except the custom code and plug-ins styles.

Own CSS files: It is possible to insert own *.css files in the HTML head via the customcode-head.php. This CSS will be overwrite the default CSS, except the plug-ins styles.

Custom code (small): The Photodir is modifiable with PHP and JavaScript in the customcode-head.php and customcode-foot.php. This is for small modifications. Read more about this directly in this files. This both files are automatically included.

Custom code (medium): For more than small custom code use the directory customcode and include the code files from that in the customcode-head.php and customcode-foot.php (PHP: include __DIR__ . "/customcode/example.php" or include __DIR__ . "/customcode/example.html"). This is for medium modifications.

Extensions (Plug-ins)

Plug-ins: The Photodir is modifiable with PHP and JavaScript via plug-ins in the directories plugins-head and plugins-foot. This is for larger modifications.

Plug-ins manual: For each plug-in create a own directory in the directory plugins-head or plugins-foot. In this own plug-in directory it is required to save a index.php (Example: plugins-foot/photo-lightbox/index.php). Via this index.php it is possible to include more files in this plug-in base file that are stored in this own plug-in directory (PHP: include __DIR__ . "/html.php") or somewhere else.

Plug-ins loading: All index.php files in all own plug-in directories in plugins-head and plugins-foot are automatically loaded.

Plug-ins sort: Sort the plug-ins by his directory names.

CSV table (possible for custom)

It is possible to expand the CSV tables with more columns.

All columns are saved with his column name as array key in this PHP variables:

• $photo_csv_array["count"][{0}][{colum name}] (content in current folder)
• $photo_csv_array["named"][{foldname or filename}][{colum name}] (content in current folder)
• $photo_csv_sub_array["count"][{0}][{colum name}] (content in sub folder)

For more infos, see in the index-core-functions.php

IPTC (possible for custom)

• Please save the IPTC data as UTF-8.
• IPTC '2#005' → "ObjectName" (Document title) is used as the album/photo title.
• IPTC '2#120' → "Caption-Abstract" (Caption / Description) is used as the album/photo description.
• ! Consider: Few software don't use the IPTC correct. Please use valid software.
• All IPTC data are saved in a PHP array variable for custom use.
• The resized thumbnails are without IPTC data.

All IPTC Data are saved in this PHP variables as array:

• $photo_image_info_array (album page, thumbnails)
• $photo_image_info (file page, photos)

EXIF (possible for custom)

• Please save the EXIF data as UTF-8.
• ! Consider: Few software don't use the EXIF correct. Please use valid software.
• All EXIF data are saved in a PHP array variable for custom use.
• The resized thumbnails are without EXIF data.

All EXIF Data are saved in this PHP variables as array:

• $photo_image_exif_array (album page, thumbnails)
• $photo_image_exif (file page, photos)

Annotation

Software license

• License: public domain
• License restriction: The use for contempt of living beings is not allowed.
• Author reference: © Photodir.de

Bugs & Issues

By problems and questions please write a email.