A crud library for python
Project description
django-beam
django-beam provides you with a set of views, templates and integrations for the most common CRUD applications.
The goal is having the functionality provided by django's own admin, but in a way that integrates with your other frontend code.
This project is still in early development.
Most of the core concepts have stabilized and it is being used in production. However there may still be breaking changes going forward
Features
- CRUD operations based on class based views
- Easily extensible
- Extensions for common use cases and popular third party packages
Documentation
Should end up at https://django-beam.readthedocs.io/en/latest/
Example
# people/models.py
class Group(models.Model):
name = models.TextField()
class Person(models.Model):
name = models.TextField()
email = models.EmailField()
groups = models.ManyToManyField(Group)
# people/views.py
import beam
class PersonViewSet(beam.ViewSet):
fields = ['name', 'groups']
class GroupViewSet(beam.ViewSet):
fields = ['name']
# urls.py
urlpatterns += [
path('person/', include(PersonViewSet().get_urls())),
path('group/', include(GroupViewSet().get_urls())),
]
# settings.py
INSTALLED_APPS += [
"beam",
"beam.themes.bootstrap4", # or choose any theme you like
]
Core concepts
There are a few pieces beyond standard django that you need to understand to use beam.
The first one are ViewSets. They are used to group and configure several views for a single model (similar to
django-rest-framework
). Specifying e.g. fields = ["name", "age"]
will pass those fields to all views for the specified model. They also allow you to specify and override configuration for single views, by setting e.g. update_fields = ["name"]
the update view will be restricted to just the name.
The next concept are Components. Components are used to group and pass relevant attributes from
the viewset to the individual views. A view is only passed data that it's component expects in
__init__
.
The viewset figures out which attributes should be passed to a component and also takes into account
the specificity. If you specify both fields
and detail_fields
, the detail component will receive
the latter, while all other components will be passed the former.
Example of using a custom component
Below you can see an example of adding a custom view
class CustomerCallView(beam.views.ComponentMixin, MyBaseView):
phone = None
# your custom view code goes here ...
class CustomerViewSet(beam.ViewSet):
model = Customer
fields = ["first_name", "last_name", "email", "phone"]
call_component = Component
call_url = "call/{phone}/"
call_url_kwargs = ["phone"]
Layouts
Form layouts
Beam layouts are a simple way to give forms and detail views some structure without the use of custom templates. By specifying a tripple nested list on the viewset, fields can be grouped into rows and columns. The default theme supports up to 4 columns per row.
layout = [
[ # first row
["name", "age",], # first column
["phone", "email",], # second column
]
[ # second row
["a", "b",], # first column
["c", "d",], # second column
]
]
FIXME IMAGE
Link layouts
Beam shows links to other views in the viewset both at the top of all pages
as well as next to items in the list page.
In order to specify which links should be visible at the top of the detail page,
you can e.g. specify detail_links = ["update", "...", "delete", "!create"]
.
This would cause create to be hidden, the first link to be to the update view, the last one to
the delete view and all other components would show up in between those two.
If you e.g. want the create view to be the only one shown at the top of the list view, set
list_links = ["create"]
. To specify the links shown next to list items, set list_item_links
.
Inlines
class ContactDataInline(beam.RelatedInline):
fields = ["medium", "value"]
fk_field_name = 'person'
class PersonViewSet(beam.ViewSet):
create_inline_viewset_classes = []
inline_viewset_classes = [ContactDataInline]
Themes
We currently ship only one theme.
-
beam.themes.bootstrap4
Using default Bootstrap v4 markup and include a basic Bootstrap CSS file.In order to use the bootstrap4 theme you have to install the optional dependency
django-crispy-forms
and add it to yourINSTALLED_APPS
in settings.py:INSTALLED_APPS = (..., 'crispy_forms')
beam.contrib
We include a beam.contrib
package that provides integration with several third party django apps.
beam.contrib.reversion
Provides a base viewset for integration with django-reversion
.
Usage
First add reversion
and beam.contrib.reversion
to your installed apps.
Either use beam.contrib.reversion.VersionViewSet
as the base class for the
models where you want reversion or use the VersionViewSetMixin
.
By default create and update views are tracked. You can use the versioned_component_names
class attribute to control which components are tracked.
If you do not manually register your models with reversion then VersionViewSet.model
is registered
following all the inlines specified for the versioned_component_names
.
beam.contrib.autocomplete_light
Provides a viewset mixin for integration with django-autocomplete-light
.
It also provides some bootstrap compatible css to override django-autocomplete-light defaults. To use those
you'll have to add beam.contrib.autocomplete_light
to your installed apps before django-autocomplete-light
.
Usage
Add the mixin to your viewset, then use django-autocomplete-light
as per the projects docs, for
example by overriding the widget dicts.
# settings.py
INSTALLED_APPS = [
"dal",
"beam.contrib.autocomplete_light",
"dal_select2",
...
]
# views.py
import beam
from beam.contrib.autocomplete_light import AutocompleteMixin
class GroupViewSet(AutocompleteMixin, beam.ViewSet):
fields = ['name']
autocomplete_search_fields = ["name"]
# forms.py
from django import forms
from people.models import Person
from dal_select2.widgets import ModelSelect2Multiple
class PersonForm(forms.ModelForm):
class Meta:
model = Person
fields = ["name", "email", "groups"]
widgets = {
"groups": ModelSelect2Multiple(
url="people_group_autocomplete"
),
}
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.