.. _admin-references:

====================================================
References -- how to customize generated references
====================================================

.. versionadded:: 2.0


Reference numbers
=================

Parts and documents have a reference which is a short text field.
The reference is shared between two revisions of a part or document.
Generally, a reference includes a number that increases by one after
each creation.

OpenPLM extracts this number and stores it in the database.
When a new object is created, OpenPLM suggests a reference generated
with the maximum stored reference number.

The maximum reference number is not equal to the count of objects
since two revisions shared the same number.


Default behavior
================

By default, OpenPLM generates distinct references for parts and documents.

For parts, it generates the following references: ``PART_00001``, ``PART_00002``,
..., ``PART_00050``, ``PART_155555``.

For documents, it generates the following references: ``DOC_00001``, ``DOC_00002``,
..., ``DOC_00050``, ``DOC_155555``.

Parts and documents have two distinct counters.


How to customize it
===================

It is possible to customize how references are generated by editing
the file :file:`settings.py`.

You need to add one variable: ``REFERENCE_PATTERNS``.

By default, it is set to::

    REFERENCE_PATTERNS = {
        "shared": False,
        "part": (u"PART_{number:05d}", r"^PART_(\d+)$"),
        "doc": (u"DOC_{number:05d}", r"^DOC_(\d+)$"),
    }

As you can see, it is a python dictionary with three keys
(all keys are required).

*shared* is a boolean.
If set to True, parts and documents shared the same counter.

*part* and *document* describe how reference are generated and
how number are extracted.
Their values are a tuple with two strings:

    * the first string is a format template string
    * the second string is a regular expression pattern

Format template string
------------------------

The format template string should be a unicode object (``u""``).
It must be a `standard python format`_ expression.

.. _standard python format: http://docs.python.org/2.6/library/string.html#format-string-syntax

When the reference is generated, the template is formatting with
the following parameters:

    number
        the computed reference number.
        Obviously, it must be present in the template.
        You can add padding, for example ``{number:05d}`` adds up to 5 zeros
        before the number (``00001``, ``00145``, ``78954``, ``12454558``)

    now
        a :class:`datetime.datetime` object representing the current date.
        You can specify a special format to put the current year, month, day, etc.
        See the `strftime documentation`_ for all possibilities.

    user
        a :class:`.User` who will creates the object.
        You should not write directly ``{user}``, you should append one of its attributes:

            * ``{user.username}``: username (login).
            * ``{user.first_name}``: first name 
            * ``{user.last_name}``: last name 

    initials
        initials of the user

.. _strftime documentation: http://docs.python.org/2.6/library/datetime.html?highlight=datetime#strftime-strptime-behavior


Be careful when you add a username, first name or last name since
the generated reference may contains forbidden characters
and be too long.


Regular expression pattern
---------------------------

OpenPLM must known how to extract.
A regular expression pattern must be given.
It must contain one pair of parenthesis that will matches a number (``(\d+)``).

OpenPLM accepts a compiled pattern if you need to set a special flag to
the regular expression.


Examples
========

In all examples, a document, a part, another part and 
a document (in that order) are created.

Reference numbers shared between parts and documents
----------------------------------------------------

PART_XX and DOC_XX
++++++++++++++++++++

settings.py::

    REFERENCE_PATTERNS = {
        "shared": True,
        "part": (u"PART_{number:05d}", r"^PART_(\d+)$"),
        "doc": (u"DOC_{number:05d}", r"^DOC_(\d+)$"),
    }

will generate sequences like ``DOC_00001``, ``PART_00002``, ``PART_00003``, ``DOC_00004``, etc.


OBJ_XX
++++++++

settings.py::

    REFERENCE_PATTERNS = {
        "shared": True,
        "part": (u"OBJ_{number:05d}", r"^OBJ_(\d+)$"),
        "doc": (u"OBJ_{number:05d}", r"^OBJ_(\d+)$"),
    }

will generate sequences like ``OBJ_00001``, ``OBJ_00002``, ``OBJ_00003``, ``OBJ_00004``, etc.


Including the date of creation
-------------------------------

settings.py::

    REFERENCE_PATTERNS = {
        "shared": False,
        "part": ("{now:%Y}-{number}-part", r'^\d{4}-(\d+)-part$'),
        "doc": ("{now:%y}-{number}-doc", r'^\d\d-(\d+)-doc$'),
    }

will generate sequences like ``13-1-doc``, ``2013-1-part``, ``2013-2-part``,
and ``13-2-doc``, etc.


Including user attributes
--------------------------

settings.py::

    REFERENCE_PATTERNS = {
        "shared": False,
        "part": ("{user:username}-{number}-part", r'^.*-(\d+)-part$'),
        "doc": ("{initials}-{number}-doc", r'^.*-(\d+)-doc$'),
    }

If the user is *Robert Baratheon <rbaratheon>*,
it will generate sequences like ``RB-1-doc``, ``rbaratheon-1-part``, 
``rbaratheon-2-part``, and ``RB-2-doc``, etc.