Welcome to Django Model Controller Documentation¶
Keep tracking all of your record.
Overview¶
Come to a time that you want to able to keep track on each record of data that was created or updated. This project give you the ability to answer these questions: When this record was created? When this record was updated? Who created this record? Who updated this record?
Requirements¶
- Python (2.7, 3.2, 3.3, 3.4, 3.5)
- Django (1.8, 1.9, 1.10)
Content¶
Getting Started¶
A quick start guide for getting start using Django Model Controller.
Model¶
Usage¶
Extend your model with AbstractModelController
from django.db import models
from model_controller.models import AbstractModelController
class MyModel(AbstractModelController):
name = model.CharField()
Now MyModel will include fields such as name, created_at, updated_at, created_by and updated_by.
Field Explanation¶
- created_at timestamp of when model instance created.
- updated_at timestamp of when model instance was updated.
- created_by store foreign key of User model. Recorded the user whose responsible for creating this model instance.
- updated_by
Form¶
In order for created_user and updated_user get record automatically, Form and View must work together. Django Model controller has already included ModelControllerForm for usage with form.
Usage¶
from model_controller.forms import ModelControllerForm
class MyForm(ModelControllerForm):
class Meta:
model = MyModel
fields = ('name', )
NOTE: Since ModelControllerForm class is extended from django.forms.ModelForm the usage is the same as Django form model.
If you want to show all the fields in your model except fields from AbstractModelController, you can use pre-defined tuple EXCLUDE_MODEL_CONTROLLER_FIELDS. Example:
from model_controller.utils import EXCLUDE_MODEL_CONTROLLER_FIELDS
...
class Meta:
model = MyModel
exclude = EXCLUDE_MODEL_CONTROLLER_FIELDS
Views¶
If you followed our guided all along the only think left now is View. We have already included CreateViewMixin, UpdateViewMixin, ListViewMixin, DetailViewMixin and DeleteViewMixin.
Only CreateViewMixin and UpdateViewMixin are important, other are bonus.
Each mixin is extended from Django View Generic so the usage is the same. Also, each mixin is extended from ExtendedLoginRequiredMixin, extended from django.braces, this mean that each view extended from our mixin is required user is authenticated (since we need to record created_by and updated_by).
Usage¶
Since our view is required user to login, we will need to tell view mixin what URL it should redirect to when user is not logged in.
In your settings file
LOGIN_URL = '/Your/Login/URL'
Here is the usage for view mixin.
from model_controller.views import CreateViewMixin, UpdateViewMixin
class MyCreateView(CreateViewMixin):
template_name = '/template/create.html'
model = MyModel
form_class = MyForm
success_url = reverse_lazy('success')
class MyUpdateView(UpdateViewMixin):
template_name = '/template/update.html'
model = MyModel
form_class = MyForm
success_url = reverse_lazy('success')
Admin¶
If you don’t want your admin page to select the user each time it create or update you can use ModelControllerAdmin, which already provided for admin site usage. ModelControllerAdmin will automatically record current login user when an instance got created or updated.
Usage¶
from django.contrib import admin
from model_controller.admins import ModelControllerAdmin
from app.models import MyModel
class MyModelAdmin(ModelControllerAdmin):
list_display('name', )
admin.site.register(MyModel, MyModelAdmin)
Conclusion¶
If there is a time that you want to keep tracking your model instance and to answer question like who create or update this, when was this create or update. For it to happen Model, Form and View must work together.
Thank you¶
Please feel free to fork and submit bug or feature request.
License¶
Copyright (c) 2016, Khemanorak Khath All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.