Gallery3:Developer Handbook:Application Concepts - Gallery Codex
Personal tools

Gallery3:Developer Handbook:Application Concepts

From Gallery Codex

Revision as of 15:07, 13 June 2011 by Ckdake (Talk | contribs) (File Storage)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Application Concepts

Albums, Photos and Movies

At the highest level, Gallery 3 is a single album that can contain other albums, photos and movies. Each contained album has its own separate title, description and other metadata and is controlled by a set of permissions. There is one single album at the top of the entire hierarchy, which is called the root album. Photos, movies and albums can be moved around inside the hierarchy.

File Storage

Gallery 3 stores its data files in the gallery3/var/albums directory. Photos and movies have an associated data file while albums are associated with a directory. The gallery3/var/albums directory is maintained so that it always represents the same structure that is visible via the web interface. This makes it easy to understand the data structure and allows other applications to inter-operate with the data you store in Gallery 3.

Thumbnails and Resizes

Every album, photo and movie has a thumbnail which is a small, automatically generated graphical representation of that item. In the case of photos and movies, this is usually a scaled down version of the photo or the first frame of the movie. However album thumbnails are derived from the album cover which is a photo, movie or album chosen to represent the album.

Since photos are typically very large, they have a resize which is an intermediary version of the image that is more detailed than the thumbnail but still viewable in the web browser. There is a single resize version for each photo. Movies and albums do not have a resize.

For more information on the metadata that’s associated with an individual album, photo or movie see the Models section below.

Users and Groups

In Gallery 3 a user is a representation of a real world person. Individual users can log in to Gallery 3 with a password and be granted special permissions. Visitors who do not log in as a specific user are automatically assigned as the guest user. Users have an associated username, email address and an optional full name and URL.

There are three types of users in the system:

  • admin - These are users with privileges to access the admin interface. The first user created by the Gallery 3 installer is an admin (and has the username "admin"). Admin users can perform administrative tasks in Gallery 3 including turning other users into admin users. There must be at least one admin user, but there is no upper limit on the number of admin users.
  • guest - This is the special user assigned to visitors to Gallery 3 who do not have a regular account. There can only be one guest account.
  • regular - These are users who are not admins and not guests. There can be any number of regular accounts.

Groups are collections of users which allow Gallery 3 administrators to treat many users in a similar fashion easily. Each group has an associated name, and Gallery 3 administrators can create, delete and rename groups to their liking. By default there are two special groups in Gallery 3 that cannot be deleted (though they can be renamed):

  • Everybody - This group refers to every user including guests.
  • Registered Users - This group refers to logged in users excluding guests


Each album in Gallery 3 has an associated set of permissions that govern what groups of users can do with the album and its contents. Permissions operate at the intersection of albums and groups - this means that administrators can allow a group to take a specific action with an album. You can not assign a permission specifically to a photo or a movie, and you can not assign a permission to a single user. In both cases, you must wrap the photo or movie in an album or wrap the single user in a group before assigning permissions. Imposing this limitation has had significant positive impact on performance, code comprehension and code size. However note that there are several proposals to broaden the permission model in the upcoming 3.1 release.