Using a different database¶

The easy installer using a simple SQLite database for storing content, however for large scale production servers with multiple concurrent users this may not be appropriate. Django supports a wide range of database server which can be used instead of SQLite. However to the very specific nature of the options required to connect to a database, to use an alternate database with the easy installer a few additional steps are required.

1. Let the installer run to completion, without the --dry option, and selecting yes when asked Ready to install requirements? (y/n):.

2. Edit your settings.py file and add a variable DATABASES set to connect to your database as described in the Django documentation.

3. Remove the pos.db3 file that will have been created during the installation. This file is the name of the default SQLite database and can be safely deleted without any issues.

4. Call the Django migrate command again using the updated settings:

   ./manage.py migrate
   

5. Start (or restart) the development server and visit its address. In the case of a local development server this will likely be 127.0.0.1.

Disabling the DEBUG options¶

Because of the The easy installer using a simple SQLite database for storing content, however for large scale production servers with multiple concurrent users this may not be appropriate. Django supports a wide range of database servers which can be used instead of SQLite. However to the very specific nature of the options required to connect to a a database, to use an alternate database with the easy installer a few additional steps are required.

1. Let the installer run to completion, without the --dry option, and selecting yes when asked Ready to install requirements? (y/n):.

2. Edit your settings.py file and set the DEBUG to False::

   DEBUG=False

3. Remove the pos.db3 file that will have been created during the installation. This file is the name of the default SQLite database and will have a number of example objects and users created within it as the migrate step when DEBUG is set to True.

4. Call the Django migrate command again using the updated settings:

   ./manage.py migrate
   

5. Start (or restart) the development server and visit its address. In the case of a local development server this will likely be 127.0.0.1. To access the administators sections of the site you will need to create a super user.

Creating a superuser for the registry¶

Creating a superuser is covered in more depth in the Django documentation, however a quick guide is given here. These steps assume a valid database exists and has been appropriately set up with the Django migrate command.

To create a super user, browse to the project folder and run the command:

$ django-admin createsuperuser

This will prompt you for a username, email and password.

A username and email can be applied with the --username and --email switches respectively. For example:

$ django-admin createsuperuser  --username=my_registry_admin --email=admin@registry.example.gov

Environment variables¶

The default django settings file for Aristotle-MDR looks for a number of enviromnet variables for storing files or configuring your webapp. These are all prefixed with aristotlemdr:.

BASE_DIR

Defaults to the path of where Aristotle is installed. Its highly adviced this is changed.

SECRET_KEY

Defaults to a very insecure value - you MUST change this before going into production. From Django settings documentation:

A secret key for a particular Django installation. This is used to provide cryptographic signing, and should be set to a unique, unpredictable value.

STATIC_ROOT

Defaults to the value of BASE_DIR + "/static" From Django settings documentation:

A secret key for a particular Django installation. This is used to provide cryptographic signing, and should be set to a unique, unpredictable value.

MEDIA_ROOT

Defaults to the value of BASE_DIR + "/media" From Django settings documentation:

Absolute filesystem path to the directory that will hold user-uploaded files.

ARISTOTLE_SETTINGS¶

The following are required within a dictionary in the settings for the configured Django project.

CONTENT_EXTENSIONS

A list of the namespaces used to add additional content types, these are used when discovering the available extensions for about pages - required format a list of strings.

BULK_ACTIONS

A dictionary of bulk action names and the associated fully-ualified python path to the form that completes the action. More information on configuring bulk actions is available here.

PDF_PAGE_SIZE

The default page size to deliver PDF downloads if a page size is not specified in the URL

SEPARATORS

A key:value set that describes the separators to be used for name suggestions in the admin interface. These are set by specifying the key as the django model name for a given model, and the value as the separator. When a value for a model isn’t stated in this field it defaults to a hyphen -. The default settings in required_settings.py set additional defaults and specify the separator for “DataElements” as a comma with a single space , `` and the separator for "DataElementConcepts" as an em-dash ``–.

SITE_NAME

The main title for the site - required format string or unicode.

SITE_BRAND

A URL to the logo to use for the site, this can be relative or absolute.

SITE_INTRO

The introductory text use on the home page as a prompt for users - required format string or unicode.

WORKGROUP_CHANGES

An array that specified which classes of user can move items between workgroups. Possible options include 'admin', 'manager' or 'submitter'.

ARISTOTLE_DOWNLOADS¶

This is a list of tuples that define the different download options that will be made available to users. This tuple defines in order:

• filetype used in the URL to catch this download type - must match the regex [a-zA-Z0-9\-\.]+.
• the name presented on the download menu
• The Font-Awesome icon used in the download menu
• the python module that includes the downloader.py file for handling this filetype

For example:

('pdf',"PDF","fa-file-pdf-o","aristotle_mdr")

Menu options are only given if a template for that download file type exists for a given object. The first (filetype) setting is used when catching URLs for downloads, so that when resolving URLs the filetype is used in the URL in the following way:

/download/<download-file-type>/<item-id>

This file type is also passed to the download manager for this filetype, so that multiple file types can be handled by the same extension.

For example, if an object class had a PDF template, based on the above configuration the menu below would be accessible:

And clicking this would access the following relative URL:

/download/pdf/<object_class_id>

For more information on creating additional download extensions consult the guide on Adding new download formats.

Sample settings¶

Below is the ARISTOTLE_SETTINGS and ARISTOTLE_DOWNLOADS used on the hosted Aristotle example:

ARISTOTLE_SETTINGS = {
   # 'The main title for the site.'
    'SITE_NAME': 'Aristotle Metadata Registry',
   # URL for the Site-wide logo
    'SITE_BRAND': '/static/aristotle_mdr/images/aristotle_small.png',
   # 'Intro text use on the home page as a prompt for users.'
    'SITE_INTRO': 'Use Aristotle Metadata to search for metadata...',
   # Extensions that add additional object types for search/display.
    'CONTENT_EXTENSIONS' : [ 'comet' ],
   # Separators for auto-generating the names of constructed items.
    'SEPARATORS': { 'DataElement':',',
                'DataElementConcept':'–'},
  }

ARISTOTLE_DOWNLOADS = [
    ('pdf','PDF','fa-file-pdf-o','aristotle_mdr'),
    ]

Changing site CSS using Django staticfiles¶

Changing the CSS of the site can be done by overriding the static files that serve the Bootstrap and Aristotle CSS files, these are available at:

aristotle_mdr/static/aristotle_mdr/css/aristotle.css
aristotle_mdr/static/aristotle_mdr/bootstrap/bootstrap.min.css

Overriding these will require setting the STATICFILES_DIR setting in settings.py , like so:

STATICFILES_DIR = [os.path.join(BASE_DIR, "site_static")]

Its important, to make sure if setting a STATICFILES_DIR that 'django.contrib.staticfiles.finders.FileSystemFinder' is added to the STATICFILES_FINDERS setting. If importing all of the settings from Aristotles required_settings.py file this is already included, so this doesn’t need to be redefined. But if settings.py doesn’t import required_settings.py, STATICFILES_FINDERS can be declared like this:

STATICFILES_FINDERS = (
    'django.contrib.staticfiles.finders.FileSystemFinder',
    'django.contrib.staticfiles.finders.AppDirectoriesFinder',
)

Once this is set, to override the Aristotle bootstrap css, a file at the following location in the project site will be used instead:

custom_site_static/aristotle_mdr/bootstrap/bootstrap.min.css

More information about these is available in the Django documentation on static files.

Changing the Bootstrap file by overriding the settings¶

Aristotle uses Django-bootstrap3 to import bootstrap. By default Aristotle stores the boostrap file at:

/static/aristotle_mdr/bootstrap/

but, an alternative solution is to override this value be redefining the BOOTSTRAP3 setting in your projects settings.py, like so:

BOOTSTRAP3 = {
    # The Bootstrap base URL
    'base_url': '/static/your_path_to/bootstrap/',
}

Completely overhauling the site¶

It is also possbile to override the home page and base templates to completely overhaul the look and feel of the site, and these are available under the templates directory at:

• aristotle_mdr/templates/aristotle_mdr/base.html
• aristotle_mdr/templates/aristotle_mdr/static/home.html

However, doing so may break the rendering of pages and prevent the registry from working. It is strongly recommended that overrides of these files are done by someone with a strong working knowledge of HTML, CSS and Django templates.

Django¶

Every django setting can be overridden, but the ones that will be most important when configuring Aristotle-MDR are:

• DATABASE - By default Aristotle will configure a SQLite file-based database. While this is fine for very small low-traffic registries, configuring Django to use a fully-fledged relational database management system like PostgreSQL or MySQL will be better for larger, high-traffic sites.
• ROOT_URLCONF - This is the python library that will be used to define the settings for django to resolve URLs. If you aren’t using any extensions, you can just leave this as the default which points to the Aristotle URLs file - aristotle_mdr.urls. If you are using extensions, you’ll need to point this at the URLs file that you have created to handle all of the different URL configuration files for each extension.
• WSGI_APPLICATION - This points to the file and WSGI application that you have created to if you are intending to deploy via a WSGI server.

Haystack¶

For search to work, Haystack is required to be installed. There are no options to disable this, as without search a registry is quite useless. However you can change some settings.

• HAYSTACK_SEARCH_RESULTS_PER_PAGE - Self explanatory, this defaults to 10 items per page.
• HAYSTACK_CONNECTIONS - This define which search indexers are being used and how they are connected. By default this uses the Whoosh Engine, which is quite fast and because its a Pure-Python implementation reduces the complexity in getting it setup. For more advanced usage, read the Haystack documentation.
• HAYSTACK_SIGNAL_PROCESSOR - Included for completion, this defaults to aristotle_mdr.contrib.help.signals.AristotleHelpSignalProcessor. This is a custom signal processor that performs real-time, status-aware changes to the index and monitors for changes to Help Pages. The alternative recommended option is aristotle_mdr.signals.AristotleSignalProcessor, which only monitors changes to metadata items. Read the warnings below for why you probably only want to use these options.

LESS Compilation:¶

Aristotle-MDR includes a number of uncompiled LESS files that need to be compiled by django-static-precompiler. By default Aristotle-MDR uses the Python-based lesscpy compiler for this which is approximately compatible, but slower than, to the Node lessc compiler. If you have complex requirements in your custom LESS files, want a faster compile time or wish to use another CSS precompile type, override the following setting in your settings.py:

STATIC_PRECOMPILER_COMPILERS = (
  ('static_precompiler.compilers.LESS', {"executable": "lesscpy"}),
)

In production, its advisable to compile the LESS files once and cache these withother static files. This makes the choice of precompiler less of an issue for production environments.

Operating system support¶

• Ubuntu Linux 12.04 LTS

Travis-CI does not yet have containerised support for the Ubuntu 14.04 or 16.04 long-term support releases.

Python¶

• Python 2.7

Some modules are incompatible with Python 3 (support coming soon).

Django¶

• Django version 1.8 LTS

Database support¶

• SQLite
• Postgres

MySQL has a number of small issues in the test suite (full coverage coming soon).

Search index support¶

• Elasticsearch 2.4+
• Whoosh

Creating a download module¶

A download module is just a specialised Django app that includes a specific set of files for generating downloads. The files required in your app are:

• __init__.py - to declare the app as a python module
• downloader.py - for defining your main download method

Other modules can be written, for example a download module may define models for recording a number of times an item is downloaded.

Writing a downloader.py module¶

Your downloader.py file must contain a register of download types and the metadata concept types which this module provides downloads for. This takes the form of a dictionary with keys being the download type provided, and the values define which concepts can be downloaded as that output format:

item_register = {
    'csv': {'aristotle_mdr': ['valuedomain']},
    'xls': {'aristotle_mdr': ['__all__']},
    'pdf': '__template__'
    'txt': '__all__'
}

Describing these options, this register specifies the following downloads:

• csv provides downloads for Value Domains in the Aristotle-MDR module
• xls provides downloads for all metadata types in the Aristotle-MDR module
• pdf provides downloads for items in all modules, only if they have a download template
• txt provides downloads for all metadata types in all modules

The download module must also define a method with the following signature:

def download(request, download_type, item):

This is called from Aristotle-MDR when it catches a download type that has been registered for this module. The arguments are:

• request - the request object that was used to call the download view. The current user trying to download the item can be gotten by calling request.user.
• download_type - a short string used to differentiate different download formats
• item - the item to be downloaded, as retrieved from the database.

Note: If a download method is called the user has been verified to have permissions to view the requested item only. Permissions for other items will have to be checked within the download method.

For an example of how to handle multiple download formats in a single module, review the aristotle_mdr.downloader module which provides downloads in the PDF and CSV format for various content types which is linked below:

aristotle_mdr.downloader.download(request, download_type, item)[source]¶

Built in download method

How the download view works¶

aristotle_mdr.views.downloads.download(request, download_type, iid=None)[source]¶

By default, aristotle_mdr.views.download is called whenever a URL matches the pattern defined in aristotle_mdr.urls_aristotle:

download/(?P<download_type>[a-zA-Z0-9\-\.]+)/(?P<iid>\d+)/?

This is passed into download which resolves the item id (iid), and determines if a user has permission to view the requested item with that id. If a user is allowed to download this file, download iterates through each download type defined in ARISTOTLE_DOWNLOADS.

A download option tuple takes the following form form:

('file_type','display_name','font_awesome_icon_name','module_name'),

With file_type allowing only ASCII alphanumeric and underscores, display_name can be any valid python string, font_awesome_icon_name can be any Font Awesome icon and module_name is the name of the python module that provides a downloader for this file type.

For example, included with Aristotle-MDR is a PDF downloader which has the download definition tuple:

('pdf','PDF','fa-file-pdf-o','aristotle_mdr'),

Where a file_type multiple is defined multiple times, the last matching instance in the tuple is used.

Next, the module that is defined for a file_type is dynamically imported using exec, and is wrapped in a try: except block to catch any exceptions. If the module_name does not match the regex ^[a-zA-Z0-9\_]+$ download raises an exception.

If the module is able to be imported, downloader.py from the given module is imported, this file MUST have a download function defined which returns a Django HttpResponse object of some form.

Registering a bulk action¶

The BULK_ACTIONS setting in the in the ARISTOTLE_SETTINGS dictionary stores the register of bulk actions used for generating lists. Adding a name for the action and the qualified path to the form is sufficient to register a new bulk action. For example this set in ARISTOTLE_SETTINGS would register an action called my_action with the Python location module.forms.MyBulkAction:

'BULK_ACTIONS': {
    'my_action':'module.forms.MyBulkActionForm',
    }

Writing a functional bulk action¶

A bulk action form is just a specialised Django form for acting on multiple Aristotle-MDR concepts, with a few small additions that come from inheriting from aristotle_mdr.forms.bulk_actions.BulkActionForm.

After inheriting to make a form function some properties should exist.

• action_text - This is the name for an action shown in lists to users. Default is based on the class name.
• classes - A string of HTML classes that will be applied to each item. Default empty. Currently these are used for inserting ‘Font Awesome’ icons for each action.
• confirm_page - An optional template name used to render between a user clicking the action and completing it. By adding extra fields to a form, with this template a bulk action can get additional inforamtion from a user before continuing. No default, if this is empty no confirmation is requested.
• items_label - An optional override of the label for the list of items the action form acts on. Defaults to “Select some items”

There are two additional methods that complete the class:

• can_use - A classmethod that provides a boolean response indicating if a certain user has permission to use this action in any context - note this permission does not have knowledge of the items selected. Default is true, so if this is not overriden all users will see the action in their list.
• make_changes - Performs that actual action of the form, this is called once the user invokes a bulk action (after confirmation is required). No default, not including a make_changes method will cause your action to fail. Any text returned from this method will be shown to a user via the django messages framework.

An example bulk action form¶

Below is an example bulk action that is only visible for staff users, and deletes the items requested by a user.:

from django import forms
from aristotle_mdr.forms.bulk_actions import BulkActionForm
from django.utils.translation import ugettext_lazy as _


class StaffDeleteActionForm(BulkActionForm):
    action_text = _('Delete')
    classes="fa-trash"
    confirm_page = "confirm_delete.html"
    items_label="Items to delete",

    safe_to_delete = forms.BooleanField(required=True, label="Tick to confirm deletion")

    @classmethod
    def can_use(cls, user):
        return user.is_staff

    def make_changes(self):
        if not self.user.is_staff:
            raise PermissionDenied
        else:
            self.cleaned_data['items'].delete()
        return "Items deleted"

{% extends "aristotle_mdr/base.html" %}

{% block title %}Delete items{% endblock %}
{% block content %}
{{ form.media }}
<form method="post" action="{% url 'aristotle:bulk_action' %}?next={{next}}">{% csrf_token %}

    <input type="hidden" name="bulkaction" value="{{action}}"/>
    <table>
        {{ form.as_table }}
    </table>
    <div>
        <a class="btn btn-default" href="{{ next }}">Cancel</a>
        <button type="submit" name="confirmed" class="btn btn-primary" value="Delete">Delete</button>
    </div>
</form>
{% include 'autocomplete_light/static.html' %}
{% endblock %}

This will produce a button wherever other bulk actions are available, similar to the ‘Delete’ button available on the right in the image below.

Available tags and filters¶

aristotle_mdr.templatetags.aristotle_tags.adminEdit(item)[source]¶

A tag for easily generating the link to an admin page for editing an item. For example:

<a href="{% adminEdit item %}">Advanced editor for {{item.name}}</a>

aristotle_mdr.templatetags.aristotle_tags.can_edit(item, user)[source]¶

A filter that acts as a wrapper around aristotle_mdr.perms.user_can_edit. Returns true if the user has permission to edit the item, otherwise it returns False. If calling user_can_edit throws an exception it safely returns False.

For example:

{% if myItem|can_edit:request.user %}
  {{ item }}
{% endif %}

aristotle_mdr.templatetags.aristotle_tags.can_view(item, user)[source]¶

A filter that acts as a wrapper around aristotle_mdr.perms.user_can_view. Returns true if the user has permission to view the item, otherwise it returns False. If calling user_can_view throws an exception it safely returns False.

For example:

{% if myItem|can_view:request.user %}
  {{ item }}
{% endif %}

aristotle_mdr.templatetags.aristotle_tags.can_view_iter(qs, user)[source]¶

A filter that is a simple wrapper that applies the aristotle_mdr.models.ConceptManager.visible(user) for use in templates. Filtering on a Django Queryset and passing in the current user as the argument returns a list (not a Queryset at this stage) of only the items from the Queryset the user can view.

If calling can_view_iter throws an exception it safely returns an empty list.

For example:

{% for item in myItems|can_view_iter:request.user %}
  {{ item }}
{% endfor %}

aristotle_mdr.templatetags.aristotle_tags.clone(item)[source]¶

A tag for easily generating the link to an admin page for “cloning” an item. For example:

<a href="{% clone item %}">Clone {{item.name}}</a>

aristotle_mdr.templatetags.aristotle_tags.doc(item, field=None)[source]¶

Gets the appropriate help text or docstring for a model or field. Accepts 1 or 2 string arguments: If 1, returns the docstring for the given model in the specified app. If 2, returns the help_text for the field on the given model in the specified app.

aristotle_mdr.templatetags.aristotle_tags.downloadMenu(item)[source]¶

Returns the complete download menu for a partcular item. It accepts the id of the item to make a download menu for, and the id must be of an item that can be downloaded, otherwise the links will show, but not work.

For example:

{% downloadMenu item %}

aristotle_mdr.templatetags.aristotle_tags.historyLink(item)[source]¶

A tag for easily generating the link to an admin page for “cloning” an item. For example:

<a href="{% clone item %}">Clone {{item.name}}</a>

aristotle_mdr.templatetags.aristotle_tags.in_workgroup(user, workgroup)[source]¶

A filter that acts as a wrapper around aristotle_mdr.perms.user_in_workgroup. Returns true if the user has permission to administer the workgroup, otherwise it returns False. If calling user_in_workgroup throws an exception it safely returns False.

For example:

{% if request.user|in_workgroup:workgroup %}
  {{ something }}
{% endif %}

aristotle_mdr.templatetags.aristotle_tags.public_standards(regAuth, itemType='aristotle_mdr._concept')[source]¶

This is a filter that accepts a registration Authority and an item type and returns a list of tuples that contain all public items with a status of “Standard” or “Preferred Standard” in that Registration Authority only, as well as a the status object for that Authority.

The item type should consist of the name of the app the item is from and the name of the item itself separated by a period (.).

This requires the django django.contrib.contenttypes app is installed.

If calling public_standards throws an exception or the item type requested is not found it safely returns an empty list.

For example:

{% for item, status in registrationAuthority|public_standards:'aristotle_mdr.DataElement' %}
  {{ item }} - made standard on {{ status.registrationDate }}.
{% endfor %}

aristotle_mdr.templatetags.aristotle_tags.stateToText(state)[source]¶

This tag takes the integer value of a state for a registration status and converts it to its text equivilent.

aristotle_mdr.templatetags.aristotle_tags.ternary(condition, a, b)[source]¶

A simple ternary tag - it beats verbose if/else tags in templates for simple strings If the condition is ‘truthy’ return a otherwise return b. For example:

<a class="{% ternary item.is_public 'public' 'private' %}">{{item.name}}</a>

aristotle_mdr.templatetags.aristotle_tags.zws(string)[source]¶

zws or “zero width space” is used to insert a soft break near em-dashed. Since em-dashs are commonly used in Data Element Concept names, this helps them wrap in the right places.

For example:

<h1>{% zws item.name %}</h1>

Permissions in perms.py¶

aristotle_mdr.perms.user_can_change_status(user, item)[source]¶

Can the user change the status of the item?

aristotle_mdr.perms.user_can_edit(user, item)[source]¶

Can the user edit the item?

aristotle_mdr.perms.user_can_view(user, item)[source]¶

Can the user view the item?

Permissions-based ConceptManager¶

All correctly derived concept items should have their default manager set to the aristotle.models.ConceptManager. For more information on how this works see the full documentation on the ConceptManager and ConceptQuerySet.

class aristotle_mdr.models.ConceptManager[source]

The ConceptManager is the default object manager for concept and _concept items, and extends from the django-model-utils InheritanceManager.

It provides access to the ConceptQuerySet to allow for easy permissions-based filtering of ISO 11179 Concept-based items.

Permissions template tags¶

{% load aristotle_tags %}

There are more template tags available in Aristotle

Making metadata-specific browse lists¶

To make a metadata specific browse page, add a directory and template into your custom templates directory for that specific app of the form:

'aristotle_mdr_browse/<app_label>/<model_name>_list.html