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:
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.
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:
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 of the Element. This is just for display purposes. This has no uniqueness requirement.
A short descriptive text about the element. Can ease searching or clasification. It is optional.
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:
This returns the Element as its subclassed object. This can be a object of class Photo, Text, Video, ... depending on the actual object type.
This retrieves a thumbnail for the given element.
Parameters: |
|
---|---|
Returns: | a Thumbnail object |
Developer API:
This method should be implemented by Element inheriting classes.
This creates a new thumbnail for the given element.
Parameters: |
|
---|---|
Returns: | a saved Thumbnail object |
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.
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.).
Pointer to a ThumbnailSize defining the size of the thumbnail.
A file where the thumbnail is stored in JPEG format.
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 |
---|
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.
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.
Imports bulk files.
Example:
$ ./manage.py mg_import --roll Foo --files ~/Desktop/*.jpg
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
Depending on your configuration, this will call different updaters. See at entry “updaters” in the index for more information.
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.
$
Completely rebuild metadata, deleting existing ones. Example:
manage.py mg_update --rebuild
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
In order to use these templatetags, you must use the following code in your template:
{% load mg_element %}
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.
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.
Organizational models directly containing elements must implement the following protocol in order to guarantee a simple handling from the various generic modules.
This is a basic protocol which permits to add and remove elements from a container. Stock containers are Roll and Directory.
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.
Tells whether this importer can handle this file path and type.
Parameters: |
|
---|---|
Returns: | True or False |
Handle the filename and the given fd as new element. Filename may not exist in the filesystem (it may resize in an archive).
Parameters: |
|
---|---|
Returns: | The new Element object |