Skip to content

Models

Models within Centurion ERP are how the data is structured within the database. This page contains documentation pertinent to the development of the models for use with Centurion ERP.

All models within Centurion ERP are what we call a "Tenancy Object." A tenancy object is a model that takes advantage of the multi-tenancy features of Centurion ERP.

Requirements

All models must meet the following requirements:

  • inherits from app.access.models.TenancyObject

    Tip

    There is no requirement to include class app.core.mixin.history_save.SaveHistory for inheritence as this class is already included within class app.access.models.TenancyObject.

    Note

    If there is a specific use case for the object not to be a tenancy object, this will need to be discussed with a maintainer.

  • class has __str__ method defined to return that is used to return a default value if no field is specified.

  • Fields are initialized with the following parameters:

    • verbose_name

    • help_text

  • No queryset is to return data that the user has not got access to. see queryset()

  • Single Field validation is conducted if required.

    Requirement

    Multi-field validation, or validation that requires access to multiple fields must be done within the form class.

  • contains a Meta sub-class with following attributes:

    • ordering Order the results are returned in.

    • verbose_name Name of the Model.

    • verbose_name_plural Plural Name of the model

  • If creating a new model, function access.functions.permissions.permission_queryset() has been updated to display the models permission(s)

  • Attribute page_layout is defined with the models UI page layout

  • Attribute table_fields is defined with the fields to display by default for viewing the model within a table.

Checklist

This section details the additional items that may need to be done when adding a new model:

  • If the model is a primary model, add it to model reference rendering in app/core/lib/markdown_plugins/model_reference.py function tag_html

  • If the model is a primary model, add it to the model link slash command in app/core/lib/slash_commands/linked_model.py function command_linked_model

Tip

It's a good idea to create the initial model class, then create and add the model tests for that class. This way you can run the tests to ensure that the requirements are met. Of Note, the tests may not cover ALL of the requirements section, due diligence will need to be exercised.

page_layout Attribute

Within the model attributes, page_layout is required. This attribute is what the UI uses to render the page. simply put, it's the layout of the page. Currently this layout is for a models details page only.

The page_layout attribute is a python list that is broken down into dictionaries for the page tabs, which then contain the page sections. Breakdown of the page layout is as follows:

  • Tab These are the tabs at the top of a models details page. A tab contains sections.

  • Section The page is broken down horizontially into sections. A section contains columns or a table.

  • Column Vertical breakdown of a section. A column contains fields.

  • Table A table is a layout for a section. The table renders a sub-model as part of the existing models information.

Example of ALL available options for the page_layout attribute.

page_layout: list = [
    {    # Detail Tab.
        "name": "Details",    # Tab name.
        "slug": "details",    # HTML id field.
        "sections": [    # Page Sections.
            {    # double column section.
                "layout": "double",
                "left": [    # Left column. This list is a list of fields that match the serializer fields.
                    'organization',
                    'name',
                    'is_global',
                ],
                "right": [    # right column. This list is a list of fields that match the serializer fields.
                    'model_notes',
                    'created',
                    'modified',
                ]
            },
            {    # Table Section.
                "layout": "table",
                "name": "Dependent Services",    # Heading for the section.
                "field": "service",    # field name within the `_urls` dict of the api query. which is where the data will be fetched from.
            },
            {    # single column section.
                "layout": "single",
                "fields": [    # This list is a list of fields that match the serializer fields.
                    'config',
                ]
            }
        ]
    },
    {    # Notes Tab.
        "name": "Notes",
        "slug": "notes",
        "sections": []    # The notes tab is a special case that requires no sections to be defined.
    },
]

table_fields Attributes

The table_fields attribute within a model is what the UI List View or section table uses as the fields to add to the table. The table_fields attribute is a python list of strings that are the field names as are defined within the serializer.

History

Currently the adding of history to a model is a manual process. edit the file located at core.views.history and within View.get_object add the model to the switch statement.

Tests

The following Unit test cases exists for models:

Info

If you add a feature you will have to write the test cases for that feature if they are not covered by existing test cases.

Docs to clean up

Note

The below documentation is still to be developed. As such what is written below may be incorrect.

for items that have a parent item, modification will need to be made to the mixin by adding the relevant check and setting the relevant keys.

if self._meta.model_name == 'deviceoperatingsystem':

    item_parent_pk = self.device.pk
    item_parent_class = self.device._meta.model_name

About:

This page forms part of our Project Centurion ERP.

Page Metadata
Version: ToDo: place files short git commit here
Date Created: 2024-07-14
Date Edited: 2024-11-28

Contribution:

Would You like to contribute to our Centurion ERP project? You can assist in the following ways:

 

ToDo: Add the page list of contributors