Quick start

Assuming you already have some experience with web development and building Django applications, have you ever followed the “Writing your first Django app” tutorial on the Django website, only to be left with a lackluster result?

In this tutorial, we’ll guide you through building a basic Viewflow app that is both functional and presentable to your customers. We’ll start by creating a basic structure in the first part, then dive into adding BPMN and FSM workflows, customizing forms and CRUD, and finish it all off with a reporting dashboard.

Set up and application

Let’s create a fresh virtual environment for the demo project. In an empty directory run the following commands.

python3 -m venv .venv
source .venv/bin/activate

Viewflow works with Python>=3.8 and Django>=4.0

At first install viewflow open source package

pip install django-viewflow

Or Viewflow PRO

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

In the current directory, scaffold a new django project:

django-admin startproject demo .

Create an app:

./manage.py startapp helloworld

Now you should have following file structure:

demo/
├── asgi.py
├── __init__.py
├── settings.py
├── urls.py
└── wsgi.py
helloworld
├── admin.py
├── apps.py
├── __init__.py
├── migrations
│   └── __init__.py
├── models.py
├── tests.py
└── views.py
manage.py

Configuration

Open the demo/settings.py and add viewflow and helloworld into INSTALLED_APPS setting

INSTALLED_APPS = [
    ...
    'viewflow',
    'helloworld',
]

Initial Site structure

Let’s create the basic structure for our site. Viewflow is based on a simple concept: a Class-Based URL configuration, called Viewset. Each viewset combines a set of views and builds a list of URL patterns that work with them.

Think of Viewset as the main building block of your website. You can start with a working solution right out of the box, without doing any configuration. But, like any Python class, you can also inherit from it and customize its behavior to suit your needs.

Viewflow comes with several pre-built Viewsets that are perfect for building business applications. The Site viewset is the top-level one, and can contain several Application viewsets. Each Application viewset can have nested viewsets of their own. To get started, open demo/urls.py and add the following code:

from django.urls import path
from django.contrib.auth.models import User
from viewflow.contrib.auth import AuthViewset
from viewflow.urls import Application, Site, ModelViewset


site = Site(title="ACME Corp", viewsets=[
    Application(
        title='Sample App',
        icon='people',
        app_name='sample',
        viewsets=[
            ModelViewset(model=User),
        ]
    ),
])

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

Here we set a site, with a single application in it, and expose default CRUD for built-in Django User model.

In addition, we use default Viewflow AuthViewset, to get login dialog enabled.

Run an app

Apply standard Django’s migrations to create an initial database structure

./manage.py migrate

Create an admin user to initial login

./manage.py createsuperuser

Run the server

./manage.py runserver

Go to http://127.0.0.1:8000 and see the viewflow in action!