config_files.md 4.63 KB
Newer Older
1 2 3 4 5
Words relative to *config files*
=========

<!-- This file is referenced in the config_files, if you modify its location, please update those files too. -->

6 7 8
There exist different kinds of *config files* throughout the app and all of them are absolutely necessary, so it's good to understand what is their purpose.


9 10
## Django config files

11 12 13 14 15 16 17 18 19
Django's main config file in `backend/base_app/settings.py`. This file is a standard Django one and defines many important aspects of the app such as:

- Which packages should be bundled with the app,
- What Middleware to use,
- Custom behaviors depending on if we are in testing, developing or production environment,
- Config to serve the frontend files from the backend,
- App specific settings,
- Database settings,
- Etc.
20 21 22 23


## Custom config files

24 25 26 27 28 29 30
To centralize the definition of certain certain Models and (all) viewsets attributes, we gathered a lot of information in few configuration files.

-----

?> For your information, some of those files are also read at *frontend-*compile time to automatically generate the required `Redux` actions and reducers.

!> :warning: Models are imported in Django as soon as (and only if) a corresponding viewset is registered in the config files. :warning:
31

32
*A viewset is (most often) associated with a serializer class and a serializer class is associated with a model, so we can transparently go up the chain.*
33

34
?> If for some reason you need to bypass this behavior, then you will need to follow the standard way of using Django and register the models in `backend/backend_app/admin.py` and the viewsets in `backend/backend_app/urls.py`.
35

36 37 38 39 40
-----

Below is the documentation about those custom config files that are located in the folder `backend/backend_app/config`, along we some python scripts to help handle them.

*NB: all those files use the awesome `yaml` syntax.*
41 42 43 44


### defaults.yaml

45
Contains default values use across the app, nothing special to say here.
46 47 48 49


### viewsets_config.yml

50
This file contains the configuration of the (all) the app viewsets. It has a key/value (dict) structure with key the viewset name.
51

52
Each viewset entry is defined with the following required required attributes:
53 54

* `api_end_pont`: it is the main part of the url for making request to the api. This string will also be used for naming variables in JS, so keep it simple and consistent please. :smile:
55 56 57 58 59
* `import_location`: in what file path (dot like notation - just like any python import) is the viewset available ? You should only specify the part that comes after `backend_app.models.`. *NB: the associated model should be available from the same path.*

!> **If you change an `api_end_pont` you will most likely need to update some JS files (see [here](Application/Frontend/redux.md)).**

TODO direct link to section
60 61 62 63 64 65 66 67 68 69 70 71 72 73 74


There can also be optional parameters:

* :warning: `viewset_permission` (defaults to `(IsAuthenticated & (IsStaff | NoDelete))`): What are the permissions associated with each viewset. If something is specified then it will be composed (`&`) with the default one. You can compose permissions with `&` (logical *and*) or `|` (logical *or*). All the available permissions are listed in the `__get_viewset_permissions.py` file. You can also create your own.
* `api_attr` (defaults to `None`): to specify some attributes that may be captured and used in the viewset (eg: `(?P<content_type_id>[0-9]+)/(?P<object_pk>[0-9A-Za-z]+)`)
* `requires_testing` (defaults to `false`): boolean to tell if this viewset is only available in a testing environment, for testing purposes.
* `is_api_view` (defaults to `false`): Boolean to tell if the viewset is an API View (a viewset that is not tied to django model).
* `api_name` (defaults to `None`): If you have a custom `get_queryset` function in your viewset, you need to specify an

If no value is taken, then the default one is added in the `load_viewsets_config` function (in `backend/backend_app/config/utils.py`).


### models_config.yml

75
This file contains the configuration of the app models. It has a key/ (dict) structure with key the model name.
76 77 78

For now, there is only one attribute which can be set: `moderation_level`. This attribute tells how moderation should be applied to each model.

79
Moderation levels are defined as follow:
80

81 82 83
* `0`: moderation will never be applied,
* `1`: moderation will be on if the global settings for moderation is turned on,
* `2`: (default for security reasons) moderation will always be on no matter what.
84

85
*NB: staff members, dri members and moderators won't be subject to (model-level) moderation.*
86

87
*NB: moderation can be moreover enforced at the object level. But that's for [another documentation part](Application/Backend/moderation_and_versioning.md).*