Introduction¶

The easiest way to install Photologue is with pip:

pip install django-photologue

You can also install the development version which is on Github:

git clone git://github.com/jdriscoll/django-photologue.git
cd django-photologue
python setup.py install

This code should work ok - like Django itself, we try to keep the master branch bug-free.

Dependencies¶

• Django.
• Pillow.
• South.

These 3 apps will be installed automatically if they are not already there.

Photologue also uses the Django admin app, so enable it if you have not already done so.

Configure Your Django Settings¶

1. Add ‘photologue’ to your INSTALLED_APPS setting:

   INSTALLED_APPS = (
        # ...other installed applications,
        'photologue',
        'south',
   )
   

2. Confirm that your MEDIA_ROOT and MEDIA_URL settings are correct (Photologue will store uploaded files in a folder called ‘photologue’ under your MEDIA_ROOT).

Add the urls¶

Add photologue to your projects urls.py file:

urlpatterns += patterns('',
    ...
    (r'^photologue/', include('photologue.urls')),
)

Sync Your Database¶

Use South to setup the new tables:

python manage.py migrate photologue

If you are installing Photologue for the first time, this will set up some default PhotoSizes to get you started - you are free to change them of course!

Instant Photo Gallery¶

Photologue comes with basic templates for galleries and photos. You can of course override them, or completely replace them. Note that all Photologue templates inherit from photologue/root.html, which itself just inherits from a site-wide base.html - you can change this to use a different base template.

Sitemap¶

Photologue can be used in your site’s sitemap.xml to generate a list of all the Gallery and Photo pages.

To use, add the following to the sitemap definition section of your project’s urls.py:

...
from photologue.sitemaps import GallerySitemap, PhotoSitemap

sitemaps = {...
            'photologue_galleries': GallerySitemap,
            'photologue_photos': PhotoSitemap,
            ...
            }
etc...

Extending templates¶

Photologue comes with a set of basic templates to get you started quickly - you can of course replace them with your own. That said, it is possible to extend the basic templates in your own project and override various blocks, for example to add css classes. Often this will be enough.

The trick to extending the templates is not special to Photologue, it’s used in other projects such as Oscar.

First, set up your template configuration as so:

TEMPLATE_LOADERS = (
    'django.template.loaders.filesystem.Loader',
    'django.template.loaders.app_directories.Loader',
)

from photologue import PHOTOLOGUE_APP_DIR
TEMPLATE_DIRS = (
    ...other template folders...,
    PHOTOLOGUE_APP_DIR
)

The PHOTOLOGUE_APP_DIR points to the directory above Photologue’s normal templates directory. This means that path/to/photologue/template.html can also be reached via templates/path/to/photologue/template.html.

For example, to customise photologue/gallery_list.html, you can have an implementation like:

# Create your own photologue/gallery_list.html
{% extends "templates/photologue/gallery_list.html" %}

... we are now extending the built-in gallery_list.html and we can override
the content blocks that we want to customise ...

Settings¶

Photologue has several settings to customise behaviour; at present this part of the documentation is unfortunately incomplete.

# myapp/utils.py:

import os

def get_image_path(instance, filename):
    return os.path.join('path', 'to', 'my', 'files', filename)

# settings.py:

from utils import get_image_path

PHOTOLOGUE_PATH = get_image_path

# settings.py:

PHOTOLOGUE_PATH = 'myapp.utils.get_image_path'

Third-party contributions¶

Photologue has a ‘contrib’ folder that includes some useful tweaks to the base project. At the moment, we have just one contribution:

from photologue import PHOTOLOGUE_APP_DIR
TEMPLATE_DIRS = (
    ...
    os.path.join(PHOTOLOGUE_APP_DIR, 'contrib/bootstrap/templates'),
    ... other folders containing Photologue templates should come after...
)

Example project¶

Photologue includes an example project to get you quickly ready for contributing to the project - do not hesitate to use it!

Workflow¶

Photologue is hosted on Github, so if you have not already done so, read the excellent Github help pages. We try to keep the workflow as simple as possible; most pull requests are merged straight into the master branch.

Features that will take a while to develop might warrant a separate branch in the project; at present only the ImageKit integration project is run on a separate branch.

Coding style¶

No surprises here - just try to follow the conventions used by Django itself.

Unit tests¶

Including unit tests with your contributions will earn you bonus points, maybe even a beer. So write plenty of tests.

Documentation¶

Keeping the documentation up-to-date is very important - so if your code changes how Photologue works, or adds a new feature, please check that the documentation is still accurate, and update it if required.

We use Sphinx to prepare the documentation; please refer to the excellent docs on that site for help.

Translations¶

Photologue manages string translations with Transifex. Contributions are very welcome, either by editing the translations directly on the Transifex site, or by submitting pull requests with updated .po files.

New features¶

In the wiki there is a wishlist of new features already planned for Photologue - you are welcome to suggest other useful improvements.

If you’re interested in developing a new feature, it is recommended that you first discuss it on the mailing list or open a new ticket in Github, in order to avoid working on a feature that will not get accepted as it is judged to not fit in with the goals of Photologue.

And finally...¶

Please remember that the maintainer looks after Photologue in his spare time - so it might be a few weeks before your pull request gets looked at... and the pull requests that are nicely formatted, with code, tests and docs included, will always get reviewed first ;-)