Metadata-Version: 2.1
Name: django-viewflow
Version: 2.0.0b1
Summary: Reusable library to build business applications fast
Home-page: UNKNOWN
Author: Mikhail Podgurskiy
Author-email: kmmbvnr@gmail.com
License: AGPL
Keywords: django,admin,workflow,fsm,bpm,bpmn
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: Django (>=3.2)
Requires-Dist: django-filter (>=2.3.0)

# Viewflow

**The low-code for developers with yesterday's deadline**

Viewflow is a reusable component library for Django web framework allows to
create full-featured business applications in a few lines of code. Viewflow helps
to implement collaboration and approval workflows, CRUD, and reporting.

The goal of Viewflow to stay small, flexible, and let you create Django
applications as quickly as no-code solutions.

Like Django, Viewflow shipped as a single package with batteries included. Each
part Viewflow can be used independently of each other, but they all work well
together.

[![build]][build] [![coverage]][coverage] [![pypi-version]][pypi] [![py-versions]][pypi]


Viewflow comes in two flavors:
- Open-source library with only non-opinionated core classes that allows you to build
  your custom solution on top.
- PRO: Reference functionality implementation. Integrated with third-party Django packages included.

<img src="assets/ShipmentProcess.png" alt="drawing" width="600"/>


## Installation

Viewflow works with Python 3.8 or greater and Django 4.0+

Viewflow:

    pip install django-viewflow --pre

Viewflow-PRO

    pip install django-viewflow-pro  --extra-index-url https://pypi.viewflow.io/<licence_id>/simple/ --pre


## Documentation

Full documentation for the PRO version available at http://docs-next.viewflow.io/

## Demo

http://demo.viewflow.io/

## Cookbook

Samples applications code for Viewflow PRO available at:

http://cookbook.viewflow.io


## Components

<img src="assets/ViewflowComponents.svg" alt="drawing" width="400"/>

### Class-based URL configurations

Viewflow is built around a simple concept - Class-based URL Configuration or
Viewset.

Viewsets allow you to compose pre-built components into a working solution, but
retain the ability to customize ond override any existing functionality.

```python
from django.urls import path
from viewflow.urls import Viewset

class RootViewset(Viewset):
    app_name = 'root'

    index_path = path('', TemplateView.as_view(
        template_name='viewflow/base.html'
    ), name="index")

    list_view_class = ListView

    @property
    def list_path(self):
        return path('list/', self.list_view_class.as_view(), name='list')

urlpatterns = [
    path('', RootViewset(list_view_class=MyListView).urls)
]
```

Viewset class collects all own attributes with names ending on `_path` into a
patterns list, suitable to include into django URL configuration. You can use
inheritances to override part of Viewset functionality or add new views into it.
To change a few attributes on a Viewset, you can pass them into the
constructor() call itself.

### Model CRUD

Set of pre-built viewsets and mixins to organize user interface interface for django models.

```python
from viewflow.urls import DetailViewMixin, DeleteViewMixin, ModelViewset
from .models import City

class CityViewset(DetailViewMixin, DeleteViewMixin, ModelViewset):
    model = models.City
    create_view_class = MyCreateView
    list_columns = ('name', 'country', 'population')
    list_filter_fields = ('is_capital', 'country', )
    list_search_fields = ['name']
    queryset = City._default_manager.select_related('country')

ocean_viewset = ReadonlyModelViewset(
    app_name='ocean',
    model=models.Ocean,
    list_columns=('name', 'area',),
)

urlpatterns = [
    path('cities', CityViewset().urls)
    path('oceans/', ocean_viewset.urls)
]
```

You can use it directly inside your root URL configuration or within the
Viewflow Frontend (see below)


### Finite State Machine Workflow

<a href="https://demo-next.viewflow.io/admin/review/review/">
  <img src="assets/fsm.png" alt="drawing" width="600"/>
</a>

FSM Workflow is the way to organize series of activities that are necessary to
complete a task. FSM process execution supports only one single active state in
time. Viewflow decompose FSM into a FSM definition class, django model (or
any other) for storage, and FSM Viewset for user interface.

```python
from enum import Enum
from viewflow.fsm import State

class State(Enum):
   NEW = 1
   DONE = 2
   HIDDEN = 3


class ReviewFlow(object):
   state = State(Stage, default=Stage.NEW)

   @state.transition(source=Stage.NEW, target=Stage.DONE)
   def complete():
       pass

   @state.transition(source=State.ANY, target=Stage.HIDDEN)
   def hide():
       pass

flow = ReviewFlow()
flow.stage == State.NEW  # True
flow.stage = State.DONE  # Raises AttributeError

flow.complete()
flow.state == State.DONE  # True

flow.complete()  # Now raises TransitionNotAllowed
```

`viewflow.fsm.*` can help you manage rules and restrictions around moving from
one state to another. The package is suitable for getting low-level,
database-independent FSM implementation or to wrap an existing database model
and implement a simple, persistent workflow process with a quickly bootstrapped
UI.


```python
class Report(models.Model):
    ...
    state = models.CharField(max_length=50)

class ReviewFlow(object):
    ...
    def __init__(self, report):
        self.report = report

    @state.setter()
    def _set_report_stage(self, value):
        self.report.stage = value

    @state.getter()
    def _get_report_stage(self):
        return self.report.stage

class ReviewViewset(FlowViewsMixin, CreateViewMixin, ReadonlyModelViewset):
    def get_object_flow(self, request, obj):
        return ReviewFlow(obj)

urlpatterns = [
    path('review/', ReviewViewset().urls)
]
```

### BPMN Workflow

<a href="https://demo-next.viewflow.io/helloworld/">
  <img src="assets/dashboard.png" alt="drawing" width="600"/>
</a>

lightweight workflow layer on top of Django's Model-View-Template that helps to
organize people's collaboration business logic. BPMN workflows supports parallel
execution with multiple tasks active at the same time. Viewflow defines Nodes
(which is a viewset) that can be composed into a Flow (thats is also viewset).
Multiple flows could be combined into FlowViewset to get a ready to use
interface for a user.

```python
from viewflow import this
from viewflow.contrib import celery
from viewflow.workflow import flow

class Workflow(flow.Flow):
    start = (
        flow.Start(start_view)
        .Permission("workflow.can_start_request")
        .Next(this.process)
    )

    process = celery.Job(process_request).Next(this.end)

    end = flow.End()
```

Viewflow extracts workflow and permission logic out of views into the new BFlow
layer. Same view could be reused in a different parts of workflow process. A
process specific data is handles as `request.activation` object. The
`request.activation.execute()` should be called on as soon as a user completes
the task.

```python
def start_view(request, **kwargs):
    request.activation.prepare(request.POST or None, user=request.user)
    form = StartForm(request.POST or None)

    if form.is_valid():
        artifact = form.save()
        activation.process.artifact = artifact
        request.activation.execute()

        return redirect(
            request.resolver_match.flow_viewset.get_next_task_url(request)
        )

    return render(request, 'viewflow/workflow/task.html', {
        'form': form,
        'activation': request.activation
    })
```

### Material Frontend

Viewflow provides a theme kit based on Google Material Design components. Base
page templates, Login, Logout, Password management views, Dashboard, Forms, and
CRUD.

hotwire/turbo-enabled navigation and form processing provides SPA look and feel
for a common Django application.

<p>
<a href="https://demo-next.viewflow.io/accounts/login/">
  <img src="assets/login.png" alt="drawing" width="193"/>
</a>
<a href="https://demo-next.viewflow.io/atlas/city/">
  <img src="assets/list.png" alt="drawing" width="200"/>
</a>
<a href="https://demo-next.viewflow.io/forms/bank/">
  <img src="assets/form.png" alt="drawing" width="220"/>
</a>
</p>

To define site structure and menu content, you can combine several Viewsets
into an Application Viewset. Several applications could be combined in a Site
Viewset.

```python
from viewflow.contrib.admin import Admin
from viewflow.contrib.auth import AuthViewset
from viewflow.urls import Site

atlas = Application(
    title='CRUD sample',
    app_name='atlas',
    permission='atlas.can_view_city',
    viewsets=[
        CityViewset(),
    ]
)

site = Site(
    title="CRUD 101 Demo",
    primary_color='#3949ab',
    secondary_color='#5c6bc0',
    viewsets=[
        atlas,
        Admin(),
    ]
)

urlpatterns = [
    path('', site.urls),
    path('accounts/', AuthViewset(
        allow_password_change=True,
        with_profile_view=True
    ).urls),
]
```

### Complex Forms

An extension for Django forms rending allows to declaratively modify form layout
and create a forms of any complexity without a single line of HTML/CSS

```python
class AddressForm(forms.Form):
    line_1 = forms.CharField(max_length=250)
    line_2 = forms.CharField(max_length=250)
    state = forms.CharField(max_length=100)
    city = forms.CharField(max_length=100)
    zipcode = forms.CharField(max_length=10)

    layout = Layout(
        Caption('Address'),
        Row(Column('line_1', 'line_2',), 'state'),
        Row('city', 'zipcode'),
    )
```

PRO Version adds the ability to combine forms and define dynamic formsets

```python
AddressFormSet = forms.formset_factory(AddressForm, extra=3, can_delete=True)

class SignupForm(Form):
    username = forms.CharField(
        max_length=50,
        widget=forms.TextInput(attrs={'leading-icon': 'account_box'}),
    )
    first_name = forms.CharField(max_length=250)
    last_name = forms.CharField(max_length=250)
    date_of_birth = forms.DateField()
    emails = FormSetField(formset_class=EmailFormSet)
    addresses = FormSetField(formset_class=AddressFormSet)

    layout = Layout(
        'username',
        Row('first_name', 'last_name', 'date_of_birth'),
        'emails',
        FormSet('addresses', card_desktop=4),
    )
```

### Advanced widgets

Available in the PRO version only

### Reporting Dashboard

Simple and lightweight interactive Plotly dashboards integration into Django
application and Material Frontend

```python
from viewflow.contrib.plotly import Dashboard, material

class DjangoStatsDashboard(Dashboard):
    app_name = 'django_stats'
    title = 'Django User Statistics'
    icon = 'public'

    def layout(self):
        return material.PageGrid([
            material.InnerRow([
                material.Span4([self.badge('Users registered', 'person', self.users_count())]),
                ...
            )
        )

    def users_count(self):
        return User.objects.filter(is_active=True).count()

site = Site(
    viewsets=[
        Application(
            title='Dashboard',
            viewsets=[
                DjangoStatsDashboard(),
            ]
        ),
        Admin(),
    ]
)

urlpatterns = [
    path('', site.urls),
]

```

### Advanced DB support

#### JsonField
Maintain dumb business data and quick prototyping without DB migrations.

`viewflow.jsonstore.*` is the set of virtual Django Model fields that stores data inside a single JSON database column.

```python
from viewflow import jsonstore
from django.db import models

class Employee(models.Model):
    data = JSONField(default={})
    full_name = jsonstore.CharField(max_length=250)
    hire_date = jsonstore.DateField()
```
The result model works like a usual Django model. All virtual fields are available to construct ModelForms, Viewsets, and Admin interfaces.

```python
class EmployeeForm(forms.ModelForm):
    class Meta:
        model = Employee
        fields = ['full_name', 'hire_date', 'salary']

@admin.register(Employee)
class EmployeeAdmin(admin.ModelAdmin):
    list_display = ['full_name', 'hire_date']
    fields = ['full_name', ('hire_date', 'salary')]
```
See more at: https://docs-next.viewflow.io/json_storage.html

#### Composite Foreign Keys support

Provide a way to connect a django model to a legacy database table without single primary key column.
Also works with TimescaleDB tables.

```python
from viewflow.fields import CompositeKey

class Seat(models.Model):
    id = CompositeKey(columns=['aircraft_code', 'seat_no'])
    aircraft_code = models.ForeignKey(
        Aircraft, models.DO_NOTHING,
        db_column='aircraft_code'
    )
    seat_no = models.CharField(max_length=4)

    class Meta:
        managed = False
        db_table = 'seats'
        unique_together = (('aircraft_code', 'seat_no'),)


@admin.register(models.Seat)
class SeatAdmin(admin.ModelAdmin):
    pass
```
CompositeKey field, opens a way to use such models in a Viewflow CRUD and Django
admin. Viewflow does not provide a way to create such models during migration.

### Integrated 3d-party applications
Available in the PRO version only

## License

Viewflow is an Open Source project licensed under the terms of
the AGPL license - `The GNU Affero General Public License v3.0
<http://www.gnu.org/licenses/agpl-3.0.html>`_ with the Additional Permissions
described in `LICENSE_EXCEPTION <./LICENSE_EXCEPTION>`_

You can read more about AGPL at `AGPL FAQ <http://www.affero.org/oagf.html>`_
This package license scheme follow GCC Runtime library licensing. If you use Linux already, this package license likely won't bring anything new to your stack.

Viewflow PRO has a commercial-friendly license allowing private forks
and modifications of Viewflow. You can find the commercial license terms in COMM-LICENSE.


## Changelog

2.0.0b1 2023-01-23
------------------
- Combined with django-material/django-fsm/jsonstore as a single package
- Switched to Google Material Components instead of MaterializeCSS
- Switched to hotwire/turbo instead of Turbolinks
- New Class-based URL configurations
- Composite FK support for legacy database for Django ORM
- Plotly dashboards integration
- Improved order of subsequent workflow tasks activations
- Many more improvements and fixes

[build]: https://img.shields.io/github/actions/workflow/status/viewflow/viewflow/django.yml?branch=main
[coverage]: https://img.shields.io/coveralls/github/viewflow/viewflow/v2
[travis-svg]: https://travis-ci.org/viewflow/viewflow.svg
[travis]: https://travis-ci.org/viewflow/viewflow
[pypi]: https://pypi.org/project/django-viewflow/
[pypi-version]: https://img.shields.io/pypi/v/django-viewflow.svg
[py-versions]: https://img.shields.io/pypi/pyversions/django-viewflow.svg
[requirements-svg]: https://requires.io/github/viewflow/viewflow/requirements.svg?branch=v2
[requirements]: https://requires.io/github/viewflow/viewflow/requirements/?branch=v2


