matthias/mayan-edms
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add app creation chapter to documentation.

Browse Source
This commit is contained in:
Roberto Rosario
2015-09-11 22:51:39 -04:00
parent ca6f6c3402
commit ceed96401b
3 changed files with 170 additions and 123 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
docs/topics/app_creation.rst Normal file
View File

@@ -0,0 +1,143 @@
============
App creation
============
**Mayan EDMS** apps are essentially Django app with some extra code to register
navigation, permissions and other relationships.
App modules
===========
- __init__.py
Should be empty if possible. No initialization code should be here, use the
ready() method of the MayanAppConfig class in the apps.py module.
- admin.py
Standard Django app module to define how models are to be presented in the
admin interface.
- api_views.py
REST API views go here. **Mayan EDMS** uses Django REST Framework API view
classes.
- apps.py
Contains the MayanAppConfig subclass as required by Django 1.7 and up. This
is a place to define the app name and translatable verbose name as well as
code to be execute when the modules of the app are ready.
- classes.py
Hold python classes to be used internally or externally. Any class defined by
the app that is not a model.
- events.py
Define event class instances that are later commited to a log by custom
code.
- exceptions.py
Custom exceptions defined by the app.
- fields.py
Place any custom form field classed you define here.
- forms.py
Standard Django app module that hold custom form classes.
- handlers.py
Contains the signal handlers, functions that will process a given signal
emited from this or other apps. Connect the handler functions to the
corresponding signal in the ready() method of the MayanAppConfig subclass in
apps.py
- links.py
Defines the links to be used by the app. Import only from the navigation app
and the local permissions.py file.
- literals.py
Stores magic numbers, module choices (if static), settings defaults, and
constants. Should contain all capital case variables. Must not import from
any other module.
- managers.py
Standard Django app module that hold custom model managers. These act as
model class method to performs actions in a series of model instances or
utilitarian actions on external models instances.
- models.py
Standard Django app module that defines ORM persistent data schema.
- permissions.py
Defines the permissions to be used to validate user access by links and views.
Imports only from the permissions app. Link or view conditions such as
testing for is_staff or is_super_user flag are defined in this same module.
- runtime.py
Use this module when you need the same instance of a class for the entire app.
This module acts as a shared memory space for the other modules of the app or
other apps.
- serializers.py
Hold Django REST Framework serializers used by the api_views.py module.
- settings.py
Define the config settings instances that the app will use.
- signals.py
Any custom defined signal goes here.
- statistics.py
Provides functions that will compute any sort of statistical information on
the app’s data.
- tasks.py
Code to be execute in the background or as an out-of-process action.
- tests/ directory
Hold test modules. There should be one test_*.py module for each aspect being
tested, examples: test_api.py, test_views.py, test_parsers.py, test_permissions.py
Any shared constant data used by the tests should be added to tests/literals.py
- utils.py
Holds utilitarian code that doesn't fit on any other app module or that is
used by several modules in the app. Anything used internally by the app that
is not a class or a literal (should be as little as possible)
- widgets.py
HTML widgets go here. This should be the only place with presentation
directives in the app (aside the templates).
Views
=====
The module common.generics provides custom generic class based views to be used.
The basic views used to create, edit, view and delete objects in **Mayan EDMS**
are: SingleObjectCreateView, SingleObjectDetailView, SingleObjectEditView,
and SingleObjectListView
These views handle aspects relating to view permissions, object permissions,
post action redirection and template context generation.

149
docs/topics/development.rst
View File

@@ -16,7 +16,8 @@ request on GitLab_. Make sure to add yourself to the :ref:`contributors` file.
Project philosophies
--------------------
How to think about **Mayan EDMS** when doing changes or adding new features, why things are the way they are in **Mayan EDMS**.
How to think about **Mayan EDMS** when doing changes or adding new features,
why things are the way they are in **Mayan EDMS**.
- Functionality must be as market/sector independent as possible, code for the 95% of use cases.
- Each user must be able to configure and customize it to their needs after install.
@@ -93,7 +94,9 @@ Example:
)
from .models import Index, IndexInstanceNode, DocumentRenameCount
All local app module imports are in relative form, local app module name is to be referenced as little as possible, unless required by a specific feature, trick, restriction, ie: Runtime modification of the module's attributes.
All local app module imports are in relative form, local app module name is to
be referenced as little as possible, unless required by a specific feature,
trick, restriction, ie: Runtime modification of the module's attributes.
Incorrect:
@@ -113,12 +116,18 @@ Correct:
Dependencies
~~~~~~~~~~~~
**Mayan EDMS** apps follow a hierarchical model of dependency. Apps import from their parents or siblings, never from their children. Think plugins. A parent app must never assume anything about a possible existing child app. The documents app and the Document model are the basic entities they must never import anything else. The common and main apps are the base apps.
**Mayan EDMS** apps follow a hierarchical model of dependency. Apps import from
their parents or siblings, never from their children. Think plugins. A parent
app must never assume anything about a possible existing child app. The
documents app and the Document model are the basic entities they must never
import anything else. The common and main apps are the base apps.
Variables
~~~~~~~~~
Naming of variables should follow a Major to Minor convention, usually including the purpose of the variable as the first piece of the name, using underscores as spaces. camelCase is not used in **Mayan EDMS**.
Naming of variables should follow a Major to Minor convention, usually
including the purpose of the variable as the first piece of the name, using
underscores as spaces. camelCase is not used in **Mayan EDMS**.
Examples:
@@ -158,128 +167,20 @@ Quotation character used in **Mayan EDMS** for strings is the single quote. Doub
General
~~~~~~~
Code should appear in their modules in alphabetic order or in their order of importance if it makes more sense for the specific application.
This makes visual scanning easier on modules with a large number of imports, views or classes.
Class methods that return a value should be prepended with a ``get_`` to differentiate from an object’s properties.
When a variable refers to a file it should be named as follows:
Code should appear in their modules in alphabetic order or in their order of
importance if it makes more sense for the specific application. This makes
visual scanning easier on modules with a large number of imports, views or
classes. Class methods that return a value should be prepended with a
``get_`` to differentiate from an object’s properties. When a variable refers
to a file it should be named as follows:
- filename: The file’s name and extension only.
- filepath: The entire path to the file including the filename.
- path: A path to a directory.
Flash messages should end with a period as applicable for the language.
Only exception is when the tail of the message contains an exceptions message as passed directly from the exception object.
App anatomy
~~~~~~~~~~~
- __init__.py
- Should be empty if possible. No initialization code should be here, use the ready() method of the AppConfig class in the apps.py module.
- api.py
- File to hold functions that are meant to be used by external apps.
- Interfaces meant to be used by other apps that are not models or classes.
- apps.py
- Contains the AppConfig subclass as required by Django 1.7 and up.
- classes.py
- Hold python classes to be used internally or externally.
- Any class defined by the app that is not a model.
- diagnostics.py
- Define functions that will return the state of the data of an app.
- Does not fixes the problems only finds them.
- events.py
- Define history type events.
- exceptions.py
- Exceptions defined by the app.
- fields.py
- Place any custom form field classed you define here.
- handlers.py
- Contains the signal handlers, functions that will process a given signal emited from this or other apps.
- links.py
- Defines the links to be used by the app.
- Import only from the navigation app and the local icons.py file.
- literals.py
- Stores magic numbers, module choices (if static), settings defaults, and constants.
- Should contain all capital case variables.
- Must not import from any other module.
- maintenance.py
- Hold functions that the user may run periodically to fix errors in the app’s data.
- permissions.py
- Defines the permissions to be used by links and views to validate access.
- Imports only from permissions app.
- Link or view conditions such as testing for staff or super admin status are defined in the same file.
- runtime.py
- Use this module when you need the same instance of a class for the entire app. This app is acts as a shared memory space for the modules of the apps or other apps.
- settings.py
- Define the config settings that the app will use here.
- signals.py
- Any custom defined signal goes here.
- statistics.py
- Provides functions that will computer any sort of statistical information on the app’s data.
- tasks.py
- Code to be execute as in the background or a as an process-of-process action.
- utils.py
- Hold utilitarian code that doesn't fit on any other app file or that is used by several files in the app.
- Anything used internally by the app that is not a class or a literal (should be as little as possible)
- widgets.py
- HTML widgets go here. This should be the only place with presentation directives in the app (aside the templates).
Views behavior
~~~~~~~~~~~~~~
- Delete views:
- Redirect to object list view if one object is deleted.
- Redirect to previous view if many are deleted.
- Previous view equals:
- previous variable in POST or
- previous variable in GET or
- request.META.HTTP_REFERER or
- object list view or
- 'home' view
- fallback to ‘/’
- if previous equal same view then previous should equal object list view or ‘/’
Only exception is when the tail of the message contains an exceptions message
as passed directly from the exception object.
Source Control
--------------
@@ -294,7 +195,7 @@ The project is publicly accessible, hosted and can be cloned from **GitLab** usi
Git branch structure
--------------------
**Mayan EDMS** follows the model layout by Vincent Driessen in his `Successful Git Branching Model`_ blog post. Git-flow_ is a great tool for managing the repository in this way.
**Mayan EDMS** follows simplified model layout by Vincent Driessen in his `Successful Git Branching Model`_ blog post. Git-flow_ is a great tool for managing the repository in this way.
``develop``
The "next release" branch, likely unstable.
@@ -308,7 +209,8 @@ Git branch structure
Each release is tagged separately.
When submitting patches, please place your code in its own ``feature/`` branch prior to opening a Merge Request on GitLab_.
When submitting patches, please place your code in its own ``feature/`` branch
prior to opening a Merge Request on GitLab_.
.. _Git: http://git-scm.org
.. _`Successful Git Branching Model`: http://nvie.com/posts/a-successful-git-branching-model/
@@ -331,7 +233,8 @@ Steps to deploy a development version
Setting up a development version using Vagrant
----------------------------------------------
Make sure you have Vagrant and a provider properly installed as per https://docs.vagrantup.com/v2/installation/index.html
Make sure you have Vagrant and a provider properly installed as per
https://docs.vagrantup.com/v2/installation/index.html
Start and provision a machine using: