README

== Configure your OpenERP server for analytic fields ==


In your OpenERP server's configuration file, you can set several optional
parameters related to the analytic module.

[analytic]
key = value ...


Those options must be grouped under the [analytic] category. If the category
doesn't exist, add it to your configuration file.

key (default value): description

analytic_size (5): define the maximum number of analytic dimensions
that can be associated with a model.

translate (False): enable or disable the translation of field values on
analytic dimensions (name) and codes (name and description).



== Add the MetaAnalytic metaclass to a model ==


At the beginning of the source file, import the MetaAnalytic metaclass:

from openerp.addons.analytic_structure.MetaAnalytic import MetaAnalytic


Inside your Model class, define MetaAnalytic to be used as metaclass:

__metaclass__ = MetaAnalytic



== Add analytic fields to a model ==


First of all, make sure you are using the MetaAnalytic metaclass.
Then, add the _analytic attribute to your class, using the following syntax.


Use the analytic fields associated with the model:

_analytic = True


Use analytic fields associated with another model:

_analytic = 'account_move_line'


Use several analytic field structures, associated with different prefixes:

_analytic = {
    'a': 'account_asset_asset',
    't': 'account_move_line',
}



== Add analytic fields to a view ==


Analytic fields can be added to the view individually, like any other field:

<field name="a1_id" />

'a' is the prefix associated with the structure. By default, it is 'a'.
'1' is the dimension's ordering as defined by the analytic structure.


You can also use a div to insert every analytic field within a given structure
(defined by its prefix) that wasn't explicitly placed in the view.

<div class="oe_analytic" required="1" prefix="t" />

The class, oe_analytic, mark the div that will be replaced by analytic fields.
The prefix can be omitted for a structure that uses the default prefix 'a'.
Any other attribute will be propagated to the analytic fields.


Warning: analytic fields should generally not be used inside nested sub-views.
If possible, create a separate record and use the context to specify the view:

<field name="order_line" colspan="4" nolabel="1" context="{
    'form_view_ref' : 'module.view_id',
    'tree_view_ref' : 'module.view_id'
}"/>



== Bind an analytic dimension to a model ==


First of all, make sure you are using the MetaAnalytic metaclass.
Then, add the _dimension attribute to your class, using the following syntax.


Bind the model to an analytic dimension named after the model, using default values:

_dimension = True


Bind the model to an analytic dimension with a specified name, using default values:

_dimension = 'Funding Source'


Bind the model to an analytic dimension, using either custom or default values:

_dimension = {
    'name': 'School',
    'column': 'analytic_code_id',
    'ref_id': 'school_analytic_dimension',
    'ref_module': 'my_module',
    'sync_parent': False,
    'rel_description': True,
    'rel_active': (u"Active", 'active_code'),
    'use_inherits': False,
    'use_code_name_methods': False,
}


key (default value): description

name (= _description or _name): The name of the analytic dimension.
This name is only used when creating the dimension in the database.

column (analytic_id): The field that links each record to an analytic code.

ref_id (= _name + analytic_dimension_id): The external ID that will
be used by the analytic dimension. By setting this value, you can allow two
models to use the same dimension, or a model to use an already existing one.

ref_module (empty string): The name of the module associated with the dimension
record. Change this value in order to use a dimension defined in a data file.

sync_parent (False): Controls the synchronization of the codes' parent-child
hierarchy with that of the model. When using an inherited, renamed parent field,
you must give the parent field name rather than simply True.

use_inherits (special): Determines whether the analytic codes should be bound
to the records by inheritance, or through a simple many2one field.
Inheritance allows for better synchronization, but can only be used if there
are no duplicate fields between the two objects.
The default value is True if the model has no 'name' and 'code_parent_id' field
as well as no inheritance of any kind, and False otherwise. If the object has
inheritances that do not cause conflicts, you can set it to True.

rel_active (False): Create a related field in the model, targeting the
analytic code field 'active' and with an appropriate store parameter.
This is useful when the model doesn't inherit analytic_code and/or when it
already has a field named 'active'.
Can take a pair of string values: (field label, field name).
If given a string, the default field name 'active' will be used.
If given True, the default field label 'Active' will also be used.

rel_description (False): Same as rel_active for the code field 'description'.
If given a string, the default field name 'description' will be used.
If given True, the default field label 'Description' will also be used.

use_code_name_methods (False): Set to True in order to override the methods
name_get and name_search, using those of analytic code.
This allows the analytic code's description to be displayed (and searched)
along with the entry's name in many2one fields targeting the model.