search

tOOlmaRR / web-slideshow

a web application to display custom slideshows in a browser for locally-stored photos
0 stars 0 forks source link

readme

Web Slideshow

Summary

This is a web application that can display custom slideshows in a browser for locally-stored photos. There are 3 pages in total: one for the file system slideshow, a second for the data-driven slideshows, and a third folder scanner admin page to import photos into the database for the data-driven slideshows. Each page's features are listed below.

File-Based Slideshow

This is available on the /slideshow.php page. This slideshow has no dependency on a database, so it is the easiest to set up and get running; however, many features going forward will not be developed for this page. The following features are available on this page:

  1. Photo Resizing - automatically resizes photos and slides based on the client's current viewport height. This is accomplished by a redirect and via query string paramaters.
  2. Manual Controls - at any time you can move forward or backward in the current slideshow. This does not halt the slideshow in progress, but it does restart the timer.
  3. Slideshow Speed - a slider control in the UI controls how long each slide will be displayed for. Changes take effect after transitioning to the next slide.
  4. Randomize Option - allows you to randomize the slides in the current slideshow. Changes take effect immediately.
  5. Halt - allows you to stop the slidehow on the current slide and pick up where you left off afterwards.
  6. Slideshow Selection - if multiple slideshows have been configured, you can choose which slideshow to watch via a dropdown selection.
  7. Private Slideshows - via slideshow configuration, you can limit access to selected slideshows. These slideshows only appear in the dropdown if you include a special query string parameter and value in your web request. Private slideshows appear in a red font, whereas public slideshows appear in green.
  8. Multiple Folders - via slideshow configuration, you can specify either a single folder or mutliple folders to include in a slideshow. In each case, the assumption is that there are only valid images in those folders
  9. Recursive Folders - via slideshow configuration, you can also choose to include all subfolders of each folder configured for a slideshow.

Configuration

All configuration elements are defined in the /mainConfig.php file. There is an overlying $configuration array which is designed to contain all configuration elements, and then within, there are separate arrays that contain all slideshow configurations as well as the root physical and virtual folders to use for both private and public slideshows.

This file also contains some logic to determine the default slideshow to run if there are multiple slideshows defined and available, and determines the currently chosen slideshow - either the desired default or the chosen one from the dropdown and subsequent form submission.

A sample is included in the repo, but here's a couple of slideshow configuration elements:

  1. Single Folder Private Slideshow

    $allSlideshows["Honeymoon"] = [
    "name" => "Honeymoon",
    "public" => false,
    "physicalPath" => "Honeymoon\\",
];

  2. Multiple Folder Public Slideshow

    $allSlideshows["WeddingAll"] = [
    "name" => "Wedding - ALL",
    "public" => true,
    "physicalPaths" => [
        "Wedding\\Disc1\\",
        "Wedding\\Disc2\\"
    ],
    "includeSubfolders" => true
];

Each slideshow configuration element is documented below (keep in mind that the keys are case-sensitive):

Also, here's an example of how to define the virtual and private roots to use:

$virtualRoots = array();
$virtualRoots["public"] = "/myphotos/";
$virtualRoots["private"] = "/myphotos/private/";
$configuration["virtualRoots"] = $virtualRoots;

$physicalRoots = array();
$physicalRoots["public"] = "E:\\MyPhotos\\";
$physicalRoots["private"] = "E:\\MyPhotos\\Private\\";
$configuration["physicalRoots"] = $physicalRoots;

Folder Scanner

This is available on the /scan.php page. This page allows you to scan the images within a folder into the database. You can also choose to scan all sub-folders as well. Data retrieved and added includes:

Data-Driven Slideshows

This is found on the /slideshow-db.php page. This page has similar features to the file-based slideshow page, except that it is driven off of a database rather than physical folders of images in the file system. The UI has also been redesigned. Most features being built going forward will be built for this page. This page has the following features:

Static Slideshows

This feature is still in BETA. These slideshows are pre-defined in the database. The slides are displayed in a specific order. These slideshows have the following features:

Tag-Based Slideshows

This feature is mature. These slideshows are based off of tags, and thus, are dynamic in nature. These slideshows include the following features:

Currently Known Bugs and Limitations

Root Folders and Virtual Paths are Hardcoded

This web application supports separate root folders and virtual paths for public and private slideshows. These values are defined in the config files, and out-of-the-box are set to:

You will need to bind these virtual folders to their associated physical paths in your web server configuration. For example, in Apache (httpd.conf):

    #-E-drive folders for the TEST Web-Slideshow Web App
    Alias "/myphotos" "E:\MyPhotos"
    <Directory "E:\Photos">
        Require all granted
    </Directory>

    Alias "/private_photos" "E:\MyPhotos\Private"
    <Directory "E:\MyPhotos">
        Require all granted
    </Directory>

Memory Consumption Issues for Large Slideshows in File-Based Slideshow

A block of HTML is added to the webpage for every single file within each of the configured folders for a slideshow. This means that the page source can grow uncontrollably if your slideshow simply contains too many images. In addition, all images are loaded in at load time, compounding the issue. In addition, length and width of images aren't specificed in the HTML, so all images are loaded in their original form.

So how many images are too many you ask? A test run containing 470 lower resolution images (most were under 1MB) loaded in 23 seconds and loaded 141 MB. Another test run with 693 higher quality images (averaging about 5 MB per photo) from multiple folders was not so fun, loading 1614 MB in just under 5 minutes, and only about half of the images were loaded in memory at this point. So it's safe to say that size matters!

Note: This no longer applies to the DB-Driven Slideshow (slideshow-db.php)! This page will only render one slide at a time, along with it's metadata, using AJAX calls to server-side services.

No Exclusion Option

In the case that you've configured a slideshow to include subfolders, you cannot exclude certain folders from the resulting directory tree.

Technical Notes

Running Unit Tests

In the terminal / command window, navigate to the root folder and type the following command to run all unit tests:

vendor/bin/phpunit tests --configuration ./tests --coverage-clover ./tests/results/coverage.xml --debug --log-junit ./tests/results/testResults.xml --verbose

You can also run a single test, without generating a coverage report, using the following command:

vendor/bin/phpunit tests --filter buildSlidesHtml_singleValidPhoto ./tests

Setting up Apache Web Server to Allow Requests from LAN

  1. Set the "ServerName" value in the Apache httpd.conf file to your IP (if you connect to the LAN using DHCP, this will change from time to time) on port 80. 
    ServerName 192.168.0.29:80
  2. Set the "Listen" value to all IP addresses on 80: 
    Listen *:80
  3. Find your "DocumentRoot" setting and it's accompanying Directory node and set up "Require" statements for each IP address or IP range you want to serve content to: 
        Require host localhost
    Require ip 127.0.0.1
    Require ip 192.168
  4. Open up your firewall to allow internal incoming requests on port 80 for Apache
    • In Windows 10, you will likely need to navigate to Update & Security > Windows Security > Firewall & Network Protection, and click on the Advanced Settings link near the bottom.
    • You then need to go to the Inbound rules, find Apache Web Server, and either change an existing rule or set up a new rule to allow local port 80 and local IP addresses of your choosing (potentially, 192.168.0.0 to 192.168.0.255). You may need to set this for one profile or another (public or private - I needed public apparently).
  5. Consider setting up a static IP on your internet connection. You can do this in Windows by:
    • opening your Network & Internet Settings
    • clicking on Properties to view your current connection details
    • finding the IP Settings section and clicking on Edit
    • editing your IP settings (likely IP v4) to manually specify your IP address. You'll likely want your subnet prefix length to be set to 32.

Note: Be careful when setting your static IP address. Log into your router and ensure that the address is not in the range that your router will use will assigning local IP addresses. If you don't, you may run into weird network issues in cases when the DHCP server assigns your IP address to another device on the network.

History

v5.2.0

v5.1.1

v5.1

v5.0.1

v5.0

v4.2

v4.1

v4.0

v3.2

v3.1

v3.0

v2.1

v2.0

v1.2

v1.1

v1.0

v0.5

v0.4

v0.3

v0.2

v0.1