The mg.core.element application

This application is the core of the Media Gallery. It contains the central models of the library. It also provides the core Management Commands.

Element is the core of the gallery, it contains all the core data to build the gallery index:

• a name,
• a thumbnail,
• a timestamp,
• some arbitrary descriptive text.

This is the canonical dataset implementing glue between actual media and organization of the gallery. This ensures organization is abstract from the media, and media is abstract from the organization.

Thumbnail objects are attached to Element objects, and each Element implementation is responsible for providing the relevant thumbnails. Again, this ensures most template modeling of the gallery is abstract from the contained media.

The mg_element templatetag library also provides some generic helpers to build generic templates, and an extensible gallery.

Django models

The Element model

class mg.core.element.models.Element

Element is the base class for all media elements present in the galleries. Element objects can be subclassed as photos, videos, text, ...

There are few generic data attached with each element. All fields are defined here:

timestamp

Time the Element was created at. That can be the date the photo was taken at, for instance. This is the timestamp that will be used for sorting the elements by date, and for creating date-sorted views (by year, month, day).

name

Name of the Element. This is just for display purposes. This has no uniqueness requirement.

description

A short descriptive text about the element. Can ease searching or clasification. It is optional.

owner

A pointer to the owner of the Element. This is only useful if you intend to implement ACLs.

In addition to the attributes attached to base Element objects, there are some methods for usual tasks. We’ll cover some of them here:

actual_element()

This returns the Element as its subclassed object. This can be a object of class Photo, Text, Video, ... depending on the actual object type.

thumbnail_get(thumb_size = None)

This retrieves a thumbnail for the given element.

Parameters:

• thumb_size – a ThumbnailSize object. If omitted, the smallest available thumbnail is returned.

Returns:

a Thumbnail object

Developer API:

thumbnail_new(thumb_size)

This method should be implemented by Element inheriting classes.

This creates a new thumbnail for the given element.

Parameters:

• thumb_size – a ThumbnailSize defining the thumbnail size

Returns:

a saved Thumbnail object

type

This field is for internal use only and must not be changed by user.

Type of the element. Element types must be registered with the register_type() class method.

The ThumbnailSize model

class mg.core.element.models.ThumbnailSize

A size for a class of thumbnails.

width

Width of the thumbnail.

height

Height of the thumbnail.

wh

A 2-tuple of (width, height) matching size of thumbnail

The Thumbnail model

class mg.core.element.models.Thumbnail

A thumbnail is attached to an Element and a ThumbnailSize. It has a maximal size and may be a lossy subset of the original element. (i.e. a photo may be cut in its center, a text may be blit on a papersheet image, etc.).

size

Pointer to a ThumbnailSize defining the size of the thumbnail.

element

Pointer to an Element for which it is the thumbnail.

file

A file where the thumbnail is stored in JPEG format.

filename_gen()

Creates a name matching the referenced element and size. This can be used as base path for saving the thumbnail file.

Returns:A relative path string

Management Commands

As the element application is the code of the gallery, most of its management commands can handle presence of other applications, like The mg.media.photo application, or The mg.orga.roll application, and add features.

Importing Elements

manage.py mg_import

--roll <roll>

Use the roll named <roll> (or create it), and attached all imported element to it.

This option is only available if "mg.orga.roll" is in your INSTALLED_APPS.

--files ...

Imports bulk files.

Example:

$ ./manage.py mg_import --roll Foo --files ~/Desktop/*.jpg

--archive <archive_file>

Imports all files contained in the given archive files, as if they were bulk files. This is done in-place and ensures bad archives dont tamper with the file system. Supported archive types are: Zip, Tar/Gzip, Tar/Bzip2.

Example:

$ ./manage.py mg_import --archive ~/Desktop/foo.zip
$ ./manage.py mg_import --roll "From tarbz2" --archive ~/Desktop/foo.tar.bz2

Updating Metadata

manage.py mg_update

Depending on your configuration, this will call different updaters. See at entry “updaters” in the index for more information.

--list

List the currently available updaters. This depends on your settings. Example in a projet without metadata applications:

$ ./manage.py mg_update --list
CreateResizedPhoto
    Updates of all resized photos in database.

CreateThumbnail
    Updates of all element's thumbnails in database.

$

--rebuild

Completely rebuild metadata, deleting existing ones. Example:

manage.py mg_update --rebuild

--only=<updater,updater>

Selects only a subset of the available updaters for updating or rebuilding. Examples:

# Rebuild all thumbnails
./manage.py mg_update --rebuild --only=CreateThumbnail

# Rebuild metadata from exif where absent
./manage.py mg_update --only=ExifOrientation,ExifPhotoInfo,ExifCameraInfo

Updaters

CreateThumbnail

Rehash the thumbnail.

Templatetags

The mg_element templatetag library

In order to use these templatetags, you must use the following code in your template:

{% load mg_element %}

elem_preview

This inclusion tag retrieves the HTML code to display a thumbnail for a given element, whatever its actual model:

{% elem_preview element %}

It actually uses the template named <app_label>/<model_name>_preview.html. All media models provide sane default implementation of this template.

elem_view

This inclusion tag generates the right HTML code to display the given element, whatever its actual model:

{% elem_view element %}

It actually uses the template named <app_label>/<model_name>_view.html. All media models provide sane default implementation of this template.

Protocols

The ElementContainer Protocol

Organizational models directly containing elements must implement the following protocol in order to guarantee a simple handling from the various generic modules.

class mg.core.element.utils.protocols.ElementContainer

This is a basic protocol which permits to add and remove elements from a container. Stock containers are Roll and Directory.

append(elem)

Appends an element to the current container

Parameters:

• elem – Element to add to this container

remove(elem)

Removes an element form the current container

Parameters:

• elem – Element to remove from this container

The Importer Protocol

class mg.core.element.utils.protocols.Importer

Each media application that may import files can provide a class implementing this protocol as <app>.management.utils.importer.Importer (i.e. a app/management/utils.importer.py file containing:

from mg.core.element.utils import protocols

class Importer(protocols.Importer):
    ...

This class will be instanciated exactly once, and will be used through the two following methods for each imported file.

See Tutorial: Adding a new Media Type for an example of such code.

can_handle(path, type)

Tells whether this importer can handle this file path and type.

Parameters:

• path – Relative path to a file, with full base name. File is not required to exist (it may reside inside an archive)
• type – Type of path, may be in [‘F’, ‘D’].

Returns:

True or False

do_import(filename, datafile)

Handle the filename and the given fd as new element. Filename may not exist in the filesystem (it may resize in an archive).

Parameters:

• filename – New filename, may contain a path component
• datatile – Path to temporary file containing the data

Returns:

The new Element object