Cores¶
UIRESTModelISCore¶
The purpose of ISCore
is to get a shared functionality of views into a one source.
The UIRESTModelISCore
class is the representation of a model in the django-is-core interface. These
representations are stored in a file named cores.py
in your application. We will start with the most common case when
you want to create three typical views for information system:
- table view for printing objects
- add view for creating new objects
- detail view for reading or editing objects
As example project we use Issue tracker. Firstly for every application you need management of users. We use default Django user model.
For creating add, detail and table views you must only create file cores.py
inside specific application that
contains:
from django.contrib.auth.models import User
from is_core.main import UIRESTModelISCore
class UserISCore(UIRESTModelISCore):
model = User
There is no obligation for registration. Cores are registered automatically. The result views with preview are:
Table/List¶
image 1
Add¶
image 2
Edit¶
image 3
REST¶
But there is created REST resource too. By default on URLs /api/user/
and /api/user/{obj_id}
that returns
object in asked format (HTTP header Content-type: application/json
).
RESTModelISCore¶
The RESTModelISCore
is parent of UIRESTModelISCore
. As the name suggests this class is used only for creating
REST resources without UI HTML views. The usage is the same as UIRESTModelISCore
:
from django.contrib.auth.models import User
from is_core.main import RESTModelISCore
class RESTUserISCore(RESTModelISCore):
model = User
UIModelISCore¶
The UIModelISCore
is the second parent of UIRESTModelISCore
. It is used for creating only UI views. Because UI
views needs some REST resources is necessary to specify on which URL is deployed REST resource of model (api_url_name is
transformed to URL by Django resolve helper):
from django.contrib.auth.models import User
from is_core.main import UIModelISCore
class UIUserISCore(UIModelISCore):
model = User
api_url_name = 'api-user'
You can specify URL manually:
class UIUserISCore(UIModelISCore):
model = User
def get_api_url(self, request):
return '/api/user/'
ISCore hiearchy¶
Now we provide detailed description of all ISCore objects. Firstly for better understanding you can see UML class diagram of core hierarchy.
# TODO add diagram
ISCore¶
Following options and methods can be applied for all Core objects like RESTModelISCore
, UIModelISCore
or
UIRESTModelISCore
(all descendants of ISCore class).
Options¶
-
ISCore.
abstract
¶
The variable abstract
provides way how to create core that is not registered but this class variable is not inherited.
Let’s show an example:
from django.contrib.auth.models import User
from is_core.main import RESTModelISCore
class AbstractUIRESTUserISCore(RESTModelISCore):
model = User
abstract = True
verbose_name = 'example of abstract user core'
class UIRESTUserISCore(AbstractUIRESTUserISCore):
pass
First core is not registered. Therefore views and REST resources are not created. But the second core that inherits from the abstract core is registered. All configuration from parent class is inhered (without abstract variable).
-
ISCore.verbose_name,ISCore.verbose_name_plural
These variables are used inside generic views. It can be added to context_data
and rendered inside templates.
It is necessary have a slug that distinguish one core from another. For this purpose is used variable menu_group
.
This variable is used for example to generate URL patterns or menu. Value of the variable is generated automatically
for cores that is connected to model.
Methods¶
-
ISCore.
init_request
(request)¶
Every core views/REST resources calls this method before calling dispatch. You can use it to change request its calling.
-
ISCore.
get_url_prefix
()¶
Every core must have unique URL. Therefore a method get_url_prefix
is way how to achieve it. Method defines URL
prefix for all views and rest resources. By default the URL prefix is value of attribute menu_group.
ModelISCore¶
The next class that extends ISCore
is ModelISCore
. All cores that inherits from ModelISCore works
as controller over a model.
Options¶
-
ModelISCore.
list_actions
¶
Variable list_action
contains actions that user can perform via REST or UI. More detailed explanation with example
you find inside UIRESTModelISCore options
part.
-
ModelISCore.
form_fields
¶
Use the form_fields
option to make simple layout changes in the forms on the add and detail and REST resources
pages such as showing only a subset of available fields, modifying their order, or grouping them into rows. We will
show it on UIRESTModelISCore
. If you want to restrict form fields to username
, first_name
and last_name
the simpliest way is use:
from django.contrib.auth.models import User
from is_core.main import UIRESTModelISCore
class UserISCore(UIRESTModelISCore):
model = User
form_fields = ('username', 'fist_name', 'last_name')
-
ModelISCore.
form_exclude
¶
This attribute, if given, should be a list of field names to exclude from the form.:
from django.contrib.auth.models import User
from is_core.main import UIRESTModelISCore
class UserISCore(UIRESTModelISCore):
model = User
form_exclude = ('password',)
-
ModelISCore.
form_class
¶
If you want to change default form class which is SmartModelForm
you can change it with this option. The form is
changed for add, detail views and REST resources too.
-
ModelISCore.
ordering
¶
Option for changing default ordering of model for core.:
from django.contrib.auth.models import User
from is_core.main import UIRESTModelISCore
class UserISCore(UIRESTModelISCore):
model = User
ordering = ('last_name', 'fist_name', '-created_at')
Methods¶
-
ModelISCore.
get_form_fields
(request, obj=None)¶
Use this method to define form fields dynamically or if you want to define different form fields for add, detail, view of REST resources.
-
ModelISCore.
get_form_exclude
(request, obj=None)¶
The opposite to get_form_fields.
-
ModelISCore.
get_form_class
(request, obj=None)¶
Use this method to define form dynamically or if you want to define different form for add, detail view of REST resources.
-
ModelISCore.
pre_save_model
(request, obj, form, change)¶
Method per_save_model
is called before saving object to database. Body is empty by default.
-
ModelISCore.
post_save_model
(request, obj, form, change)¶
Method post_save_model
is called after saving object to database. Body is empty by default.
-
ModelISCore.
save_model
(request, obj, form, change)¶
You can rewrite this method if you want to change way how is object saved to database. Default body is:
def save_model(self, request, obj, form, change):
obj.save()
-
ModelISCore.
pre_delete_model
(request, obj)¶
Method pre_delete_model
is called before removing object from database. Body is empty by default.
-
ModelISCore.
post_delete_model
(request, obj)¶
Method post_delete_model
is called after removing object from database. Body is empty by default.
-
ModelISCore.
delete_model
(request, obj)¶
You can rewrite this method if you want to change way how is object removed from database. Default body is:
def delete_model(self, request, obj):
obj.delete()
-
ModelISCore.
verbose_name
(), ModelISCore.verbose_name_plural()¶
Default verbose names of ModelISCore
is get from model meta options:
self.model._meta.verbose_name
self.model._meta.verbose_name_plural
Default menu_group
value is get from module name of model (self.model._meta.module_name
)
-
ModelISCore.
get_ordering
(request)¶
Use this method if you want to change ordering dynamically.
-
ModelISCore.
get_queryset
(request)¶
Returns model queryset, ordered by defined ordering inside core. You can filter here objects according to user permissions.
-
ModelISCore.
preload_queryset
(request, qs)¶
The related objects of queryset should sometimes very slow down retrieving data from the database. If you want to improve a speed of your application use this function to create preloading of related objects.
-
ModelISCore.
get_list_actions
(request, obj)¶
Use this method if you want to change list_actions
dynamically.
-
ModelISCore.
get_default_action
(request, obj)¶
Chose default action for object used inside UI and REST. For example default action is action that is performed if you
select row inside table of objects. For table view default action is open detail view. If you return None
no action is performed by default.
UIISCore¶
Options¶
Every UI core has one place inside menu that addresses one of UI views of a core. This view is selected by option
menu_url_name
.
Option show_in_menu is set to True
by default. If you want to remove core view from menu set this option to
False
.
-
UIISCore.
view_classes
¶
Option contains view classes that are automatically added to Django urls. Use this option to add new views. Example
you can see in section generic views (this is a declarative way if you want to register views dynamically see
UIISCore.get_view_classes
).:
from django.contrib.auth.models import User
from is_core.main import UIRESTModelISCore
from .views import MonthReportView
class UserISCore(UIRESTModelISCore):
model = User
view_classes = (
('reports', r'^/reports/$', MonthReportView),
)
-
UIISCore.
default_ui_pattern_class
¶
Every view must have assigned is-core pattern class. This pattern is not the same patter that is used with django urls. This pattern has higher usability. You can use it to generate the url string or checking permissions. Option default_ui_pattern_class contains pattern class that is used with defined view classes. More about patterns you can find in section patterns. #TODO add link
Methods¶
-
UIISCore.
init_ui_request
(request)¶
Every view defined with option view_classes
calls this method before calling dispatch. The default implementation of
this method calls parent method init_request
:
def init_ui_request(self, request):
self.init_request(request)
-
UIISCore.
get_view_classes
()¶
Use this method if you want to change view_classes
dynamically. A following example shows overriding detail view
and registering a custom view:
from django.contrib.auth.models import User
from is_core.main import UIRESTModelISCore
from .views import UserDetailView, MonthReportView
class UserISCore(UIRESTModelISCore):
model = User
def get_view_classes(self):
view_classes = super(UserISCore, self).get_view_classes()
view_classes['detail'] = (r'^/(?P<pk>\d+)/$', UserDetailView)
view_classes['reports'] = (r'^/reports/$', MonthReportView)
return view_classes
-
UIISCore.
get_ui_patterns
()¶
Contains code that generates ui_patterns
from view classes. Method returns ordered dict of pattern classes.
Returns boolean
if menu link is provided for the core, by default there are three rules:
- show_in_menu must be set to
True
- menu_url_name need not be empty
- current user must have permissions to see the linked view
This method finds if a menu link of a core is active (if the view with menu_url_name
is the current displayed page).
This method returns a menu item object that contains information about the link displayed inside menu.
Returns URL string of menu item.
RESTISCore¶
RESTISCore
is very similar to UIISCore
, but provides REST resources instead of UI views.
Options¶
-
RESTISCore.
rest_classes
¶
Option contains REST classes that are automatically added to django urls. Use this option to add new REST resources. Example you can see in section REST. #TODO add link
-
RESTISCore.
default_rest_pattern_class
¶
As UI views every resource must have assigned is-core pattern class. Default pattern for REST resources is RESTPattern. More about patterns you can find in section patterns. #TODO add link
Methods¶
-
RESTISCore.
init_rest_request
(request)¶
Every resource defined with option rest_classes
calls this method before calling dispatch. The default implementation
of this method calls parent method init_request
.
-
RESTISCore.
get_rest_classes
()¶
Use this method if you want to change rest_classes
dynamically.
-
RESTISCore.
get_rest_patterns
()¶
Contains code that generates rest_patterns
from rest classes. Method returns an ordered dict of pattern classes.
HomeUIISCore¶
HomeISCore
contains only one UI view which is index page. By default this page is empty and contains only menu
because every information system has custom index. You can very simply change default view class by changing settings
attribute HOME_VIEW
, the default value is:
HOME_VIEW = 'is_core.generic_views.HomeView'
You can change whole is core too by attribute HOME_IS_CORE
, default value:
HOME_IS_CORE = 'is_core.main.HomeUIISCore'
UIModelISCore¶
UIModelISCore
represents core that provides standard views for model creation, editation and listing. The
UIModelISCore
will not work correctly without REST resource. Therefore you must set api_url_name
option.
Options¶
-
UIModelISCore.
default_model_view_classes
¶
For the UIModelISCore
default views are add, detail and list:
default_model_view_classes = (
('add', r'^/add/$', AddModelFormView),
('detail', r'^/(?P<pk>[-\w]+)/$', DetailModelFormView),
('list', r'^/?$', TableView),
)
-
UIModelISCore.
api_url_name
¶
The api_url_name
is required attribute. The value is pattern name of REST resource.
-
UIModelISCore.
list_display
¶
Set list_display
to control which fields are displayed on the list page.
-
UIModelISCore.
export_display
¶
Set export_display
to control which fields are displayed inside exports (e.g. PDF, CSV, XLSX).
-
UIModelISCore.
export_types
¶
REST resources provide the ability to export output to several formats:
- XML
- JSON
- CSV
- XLSX (you must install library XlsxWriter)
- PDF (you must install library reportlab)
- List view provides export buttons. Option
export_types
contains tripple: - title
- type
- serialization format (content-type).
For example if you want to serialize users to CSV:
class UIRESTUserISCore(UIRESTISCore): export_types = ( ('export to csv', 'csv', 'text/csv'), )
If you want to set export_types
for all cores you can use EXPORT_TYPES
attribute in your settings:
EXPORT_TYPES = (
('export to csv', 'csv', 'text/csv'),
)
-
UIModelISCore.
default_list_filter
¶
UI table view support filtering data from REST resource. There are situations where you need to set default values for filters. For example if you want to filter only superusers you can use:
class UIRESTUserISCore(UIRESTISCore):
default_list_filter = {
'filter': {
'is_superuser': True
}
}
On the other hand if you want to filter all users that is not superusers:
class UIRESTUserISCore(UIRESTISCore):
default_list_filter = {
'exclude': {
'is_superuser': True
}
}
Exclude and filter can be freely combined:
class UIRESTUserISCore(UIRESTISCore):
default_list_filter = {
'filter': {
'is_superuser': True
},
'exclude': {
'email__isnull': True
}
}
-
UIModelISCore.
form_inline_views
¶
The django-is-core interface has the ability to edit models on the same page as a parent model. These are called inlines. We will use as example new model issue of issue tracker system:
class Issue(models.Model):
name = models.CharField(max_length=100)
watched_by = models.ManyToManyField(AUTH_USER_MODEL)
created_by = models.ForeignKey(AUTH_USER_MODEL)
Now we want to add inline form view of all reported issues to user add and detail views:
class ReportedIssuesInlineView(TabularInlineFormView):
model = Issue
fk_name = 'created_by'
class UIRESTUserISCore(UIRESTISCore):
form_inline_views = (ReportedIssuesInlineView,)
The fk_name
is not required if there is only one relation between User
and Issue
. More about inline views you
can find in generic views section # TODO add link.
-
UIModelISCore.
form_fieldsets
¶
Set form_fieldsets
to control the layout of core add and change pages. Fieldset defines a list of form fields
too. If you set form_fieldsets
the form_fields
is rewritten with a set of all fields from fieldsets.
Therefore you should use only one of these attributes.
form_fieldsets
is a list of two-tuples, in which each two-tuple represents a <fieldset> on the core form page.
(a <fieldset> is a section of the form.).
The two-tuples are in the format (name
, field_options
), where name is a string representing the title of the
form_fieldset
and field_options
is a dictionary of information about the fieldset
, including a list of fields
to be displayed in it.
As a example we will use User
model again:
class UIRESTUserISCore(UIRESTISCore):
form_fieldsets = (
(None, {'fields': ('username', 'email')}),
('profile', {'fields': ('first_name', 'last_name'), 'classes': ('profile',)}),
)
If neither form_fieldsets
nor form_fields
options are present, Django will default to displaying each field
that isn’t an AutoField
and has editable=True
, in a single fieldset
, in the same order as the fields are
defined in the model.
The field_options
dictionary can have the following keys:
- fields
A tuple of field names to display in this
fieldset
. This key is required.Example:
{ 'fields': ('first_name', 'last_name'), }fields can contain values defined in
form_readonly_fields
to be displayed as read-only.If you add
callable
to fields its result will be displayed as read-only.
- classes
A list or a tuple containing extra CSS classes to apply to the fieldset.
Example:
{ 'classes': ('profile',), }
- inline_view
inline_view
attribute can not be defined together withfields
. This attribute is used for definig position of inline view inside form view. The value of the attribute is a string class name of the inline view.Example:
{ 'inline_view': 'ReportedIssuesInlineView' }
-
UIModelISCore.
form_readonly_fields
¶
By default the django-is-core shows all fields as editable. Any fields in this option (which should be a list or
a tuple) will display its data as-is and non-editable. Compare to django-admin fields defined in a form are used
too (due SmartModelForm
).
menu_url_name
is set to list
by default, for all UIModelISCore
and its descendants.
Methods¶
-
UIISCore.
get_form_fieldsets
(request, obj=None)¶
Use this method if you want to change form_fieldsets
dynamically.
-
UIISCore.
get_form_readonly_fields
(request, obj=None)¶
Use this method if you want to change form_readonly_fields
dynamically.
-
UIISCore.
get_ui_form_class
(request, obj=None)¶
Change this method to get a custom form only for UI. By default it uses get_ui_form_class(request, obj)
method
to obtain a form class.
-
UIISCore.
get_ui_form_fields
(request, obj=None)¶
Change this method to get a custom form fields only for UI. By default it uses get_form_fields(request, obj)
method
to obtain form fields.
-
UIISCore.
get_ui_form_exclude
(request, obj=None)¶
Change this method to get a custom form exclude fields only for UI. By default it uses
get_form_exclude(request, obj)
method to obtain excluded form fields.
-
UIISCore.
get_form_inline_views
(request, obj=None)¶
Use this method if you want to change form_inline_views
dynamically.
-
UIISCore.
get_default_list_filter
(request)¶
Use this method if you want to change default_list_filter
dynamically.
-
UIISCore.
get_list_display
(request)¶
Use this method if you want to change list_display
dynamically.
-
UIISCore.
get_export_display
(request)¶
Method returns export_display
if no export_display is set the output is result of method
get_list_display(request)
.
-
UIISCore.
get_export_types
(request)¶
Use this method if you want to change export_types
dynamically.
-
UIISCore.
get_api_url_name
(request)¶
Use this method if you want to change api_url_name
dynamically.
-
UIISCore.
get_api_url
(request)¶
A result of this method is an URL string of REST API. The URL is generated with Django reverse function from
api_url_name
option.
-
UIISCore.
get_add_url
(request)¶
Returns an URL string of add view. Rewrite this method if you want to change a link of add button at the list view.
RESTModelISCore¶
RESTModelISCore
represents core that provides a standard resource with default CRUD operations.
Options¶
-
RESTModelISCore.
rest_detailed_fields
¶
Set rest_detailed_fields
if you want to define fields that will be returned inside REST response for a request on
concrete object (an URL contains an ID of a concrete model object. For example an URL of a request is /api/user/1/
).
This option rewrites settings inside RESTMeta
(you can find more about it at section #TODO add link).
-
RESTModelISCore.
rest_general_fields
¶
Set rest_general_fields
if you want to define fields that will be returned inside REST response for a request on
more than one object (an URL does not contain an ID of a concrete objects, eq. /api/user/
). This defined set of
fields is used for generating result of a foreign key object. This option rewrites settings inside RESTMeta
(you can find more about it at section #TODO add link).
-
RESTModelISCore.
rest_extra_fields
¶
Use rest_extra_fields
to define extra fields that is not returned by default, but can be extra requested
by a HTTP header X-Fields
or a GET parameter _fields
. More info you can find in django-piston library
documentation. This option rewrites settings inside RESTMeta
(you can find more about it at section #TODO add link).
-
RESTModelISCore.
rest_default_guest_fields
¶
rest_guest_fields
contains list of fields that can be seen by user that has not permission to see the whole
object data. In case that a user has permission to see an object that is related with other object that can not be
seen. In this situation is returned only fields defined inside rest_guest_fields
. This option rewrites settings
inside RESTMeta
(you can find more about it at section #TODO add link).
-
RESTModelISCore.
rest_default_detailed_fields
¶
The purpose of rest_default_detailed_fields
is the same as rest_detailed_fields
but this option does not rewrite
settings inside RESTMeta
but the result fields is intersection of RESTMeta
options and this option.
-
RESTModelISCore.
rest_default_general_fields
¶
The purpose of rest_default_general_fields
is the same as rest_general_fields
but this option does not rewrite
settings inside RESTMeta
but the result fields is intersection of RESTMeta
options and this option.
-
RESTModelISCore.
rest_default_extra_fields
¶
The purpose of rest_default_extra_fields
is the same as rest_extra_fields
but this option does not rewrite
settings inside RESTMeta
but the result fields is intersection of RESTMeta
options and this option.
-
RESTModelISCore.
rest_default_guest_fields
The purpose of rest_default_guest_fields
is the same as rest_guest_fields
but this option does not rewrite
settings inside RESTMeta
but the result fields is intersection of RESTMeta
options and this option.
-
RESTModelISCore.
rest_allowed_methods
¶
A default value of rest_allowed_methods
is:
rest_allowed_methods = ('get', 'delete', 'post', 'put')
Use this option to remove a REST operation from a model REST resource. For example if you remove post
, the REST
resource will not be able to create new model object:
rest_allowed_methods = ('get', 'delete', 'put')
-
RESTModelISCore.
rest_obj_class_names
¶
This option is used with UIIScore
. A REST resource will return a list of defined class names inside a response.
The atribute inside response has named _class_names
.
-
RESTModelISCore.
rest_resource_class
¶
A default resource class is RESTModelResource
. You can change it with this attribute.