================================================================================
                            Naaya Photo Archive - Usage
================================================================================
--------------------------------------------------------------------------------
                Organize your photos in galleries and albums.
--------------------------------------------------------------------------------

Gallery
=======
  A gallery is a collection of albums. It can be created directly into a 
  Naaya Site or as a subobject of Naaya Folder.
  
    >>> self.login()
    >>> info = self.portal.info
    >>> gallery_id = info.manage_addNyPhotoGallery(id='mygallery', title='My Gallery')
    >>> gallery = info[gallery_id]
    >>> gallery.title
    u'My Gallery'

Album
=====
  An album is a collection of photos that provides a thumbnail display of photos.

    >>> album_id = gallery.addNyPhotoFolder(id='myalbum', title='My Album')
    >>> album = gallery[album_id]
    >>> album.title
    u'My Album'

  You can specify maximum photos in album, and maximum photos to display per page.

    >>> album.saveProperties(title=album.title, max_photos=5, photos_per_page=10)
    >>> album.max_photos
    5
    >>> album.photos_per_page
    10

  You can upload a single photo

    >>> photo = self.loadFile('data/test.gif')
    >>> error = album.uploadPhotoOrZip(photo)
    >>> error
    ''
    >>> album.objectIds()
    ['test.gif']

  Or multiple photos from a zip archive
  
    >>> zip = self.loadFile('data/test.zip')
    >>> error = album.uploadPhotoOrZip(zip)
    >>> error
    "You've reached the maximum number of photos allowed in this album !"
    >>> album.objectIds()
    ['test.gif', 'a.gif', 'b.gif', 'c-d.gif', 'd_and_d.gif']
  
  Albums are displayed in gallery as thumbnails and for that they need a cover image.
  By default this is the first image relative url in album. If there is no image
  in album an empty string is returned.

    >>> album.get_cover()
    'test.gif'
    >>> error = album.changeCover('xxx.jpg')
    >>> error
    'Invalid cover id xxx.jpg'
    >>> album.changeCover('c-d.gif')
    ''
    >>> album.get_cover()
    'c-d.gif'

Photo
=====
  A photo is an object that stores one photo, and PIL generated displays:
    * Album - to be used in album listing
    * Gallery - to be used in gallery listing
    * Thumbnail, XSmall, Small, Medium, Large, XLarge

    >>> photo = album['b.gif']
    >>> photo.width(), photo.height()
    (600, 374)
    >>> photo.get_displays()
    ['XSmall', 'Small', 'Medium', 'Large', 'XLarge']
    >>> small = photo._getDisplay('Small')
    >>> small.width, small.height
    (320, 199)
    >>> album_display = photo._getDisplay('Album')
    >>> album_display.width, album_display.height
    (100, 100)
    >>> pfile = self.loadFile('data/test.gif')
    >>> photo.saveUpload(file=pfile)
    >>> photo.width(), photo.height()
    (430, 330)

  Photo provides a previous - next view that allow you to easier navigate 
  in album.
  
    >>> photo.next()
    'http://nohost/portal/info/mygallery/myalbum/c-d.gif'
    >>> photo.previous()
    'http://nohost/portal/info/mygallery/myalbum/a.gif'
