Skip to content

Latest commit

 

History

History
130 lines (93 loc) · 4.73 KB

README.md

File metadata and controls

130 lines (93 loc) · 4.73 KB
Raw

Node Gallery

NodeJS Photo Gallery built on Express 4.
Feed it a directory of photos, get back a JSON object & a styled photo gallery ready for the web.

  • No database needed
  • Strictly no frills
  • Folders titles => Album titles
  • Image titles => Photo Titles
  • EXIF title => Description
  • Displays camera capture info (exposure, aperture, ISO..)

Installation

$ npm install --save node-gallery

Usage

Node gallery can be used standalone, or in an existing node.js application. The example code has support for the Openshift and Heroku PaaS.

In Existing Applications

Node Gallery exposes express style middleware, meaning it can be mounted to any route within your application.

/*
@param {string, required} staticFiles The directory where your album starts - can contain photos or images
@param {string, required} urlRoot The root URL which you pass into the epxress router in app.use (no way of obtaining this otherwise)
@param {string, optional} title Yup, you guessed it - the title to display on the root gallery
@param {boolean, optional} render Default to true. If explicitly set to false, rendering is left to the next function in the chain - see below. 
@param {string, optional} thumbnail.width Thumbnail image width, defaults '200'
@param {string, optional} thumbnail.height as above
@param {string, optional} image.width Large images width defaults '100%'
@param {string, optional} image.height as above
*/
app.use('/gallery', require('node-gallery')({
  staticFiles : 'resources/photos',
  urlRoot : 'gallery', 
  title : 'Example Gallery'
}));

Now, you can access the gallery by going to your application's url /gallery - in the case of our example, http://localhost:3000/gallery.

Providing Views

The middleware renders the views in the views directory by default, but you can override this behavior & provide your own view rendering by setting render to false.
When this happens, the gallery HTML is returned in req.html, the raw JSON data in req.data.

app.use('/gallery', require('node-gallery')({
  staticFiles : 'resources/photos',
  urlRoot : 'gallery', 
  title : 'Example Gallery',
  render : false
}), function(req, res, next){
  /*
   We MUST add another middleware function to the chain when render is false. 
   just return the raw HTML data - we could partial into another template here,
   pass the JSON data into a template
   */
  return res.send(req.html);
});

For a more detailed example, see examples/app.js.

Middleware Routes

There are three main routes exposed under whatever root directory you provide.

To receive JSON Responses rather than a rendered HTML page, just send an accept: application/json header.

Album Pages

/:albumName/      
/:albumName/:subalbum  
/:albumName/:subalbum/:anothersubalbum

Photo Pages

/:albumName/photo/:photoName
/:albumName/:subalbum/photo/:photoName

Image Files

/:albumName/:subAlbum/:photoname.(png|jpg|tif|jpeg|gif)

Running Standalone

Node Gallery can be run standalone for testing. Modify examples/app.js to your liking, then add your albums & images to examples/resources/photos & run using:

cd example
npm install -d 
node app.js

Examples

Node Gallery with out-of-the-box configuration is deployed to Heroku - see it here.

A basic usage example showing how to use node-gallery with Express can be found in examples/basic.js.

A more advanced example, showing how to take control of the rendering of your pages is shown in examples/app.js.

To try these examples:

cd examples
npm install -d
node app.js # or node basic.js

Photos

Photos are added to your specified staticFiles directory. Albums are created for every folder we encounter, and thumbnails are automatically generated by using the first image we come across in this album.

Tests

Tests are written in raw javascript. To run,

$ npm test

ImageMagick

Node Gallery does require ImageMagick. Installation instructions for mac can be found at: http://www.imagemagick.org/script/binary-releases.php#macosx

For windows:

  1. Select imagemagick installer for your system, e.g., http://sourceforge.net/projects/imagemagick/files/6.8.9-exes/ImageMagick-6.8.9-4-Q16-x64-dll.exe/download
  2. Install imagemagick
  3. Make sure that imagemagick tools are available on system path (e.g., you can test if you can run "convert.exe" from CMD)
  4. Restart cygwin, CMD or whatever you use to fire up node.js