! Important Notice !

This plugin was incorporated into Opal core as of Opal 0.9.

The standalone plugin version here is no longer actively maintained, application developers are strongly advised to upgrade to Opal >= 0.9.0 moving forwards.

Pathways

The Opal Pathways plugin provides developers with a highly extensible method of working with complex forms in Opal. Typically pathways are forms that allow the user to enter information that spans multiple Subrecords - which can be challenging with the Subrecord forms provided by Opal itself.

Pathways provides Wizards, long multi-model forms, custom validation and much more, all usable either in full page or modal contexts.

This plugin is Alpha software.

Although it aldeady provides significant and useful functionality, it is in active development, and delvelopers should anticipate backwards-incompatible API changes as part of minor (x.VERSION.x) releases.

Contents

• Introduction: What is a Pathway?
• Installation
• Quickstart Guide
• Detailed Topic Guides
• Reference Guides
• Road Map
• Modal Pathways

Introduction: What Is A Pathway?

A pathway is a complex form that we can use in an Opal application. Pathways are comprised of a collection of Steps.

Pathway Steps are individual sections of that complex form which provide hooks to customise validation, presentation or behaviour in a granular manner.

The Pathways plugin ships with two types of pathway, which can be used either on their own page, or in an Opal modal:

• Wizard style - e.g. the user has to click next to reveal each subsequent step
• Single Page - e.g. displaying all the Pathway Steps from the start and the user scrolls to the next one

Installation

Clone git@github.com:openhealthcare/opal-pathway

Run python setup.py develop

Add pathway to INSTALLED_APPS in your settings.py.

Quickstart Guide

In this section we walk you through creating a simple Pathway.

A First Pathway

Pathways are an Opal Discoverable feature - this means that Opal will automatically load any Pathways defined in a python module named pathways.py inside a Django App.

Individual pathways are defined by subclassing a Pathway class. You must set at least the display name, and will often want to also set a slug.

Out of the box, pathways ships with two types of pathways. A page pathway, a whole bunch of model forms on the same page, and a wizard pathway, a bunch of steps where the next step is only revealed after the step before it has been completed.

Let's look at a page pathway definition.

# yourapp/pathways.py
import pathway

class MyPathway(pathway.PagePathway):
    display_name = 'My Awesome Pathway'
    slug         = 'awesomest-pathway'

Taking Our First Steps

A Pathway should have at least one Step - a section within the form.

Steps are defined on the pathway class using the Pathway.steps tuple.

import pathway
from myapp import models

class SimplePathway(pathway.PagePathway):
    display_name = 'A simple pathway'
    steps        = (
        pathways.Step(model=models.PastMedicalHistory)
    )

Model Steps

A common case is for steps to be simply a single Opal Subrecord using the subrecord form template.

In fact we can simply add Opal Subrecords to the steps tuple to achieve the same effect.

For instance, to create a pathway with three steps to record a patient's allergies, treatment and past medical history, we could use the following:

import pathway
from myapp import models

class SimplePathway(pathway.PagePathway):
    display_name = 'A simple pathway'
    slug         = 'simples'
    steps        = (
        models.Allergies,
        models.Treatment,
        models.PastMedicalHistory
    )

Pathways is smart enough to provide a single form step pathway if the model is a model or a pathway that allows a user to edit/add/remove multiple models if its not.

Viewing The Pathway

This pathway is then available from e.g. http://localhost:8000/pathway/#/simples.

Detailed Topic Guides

In this section we cover Pathway concepts in more detail.

• Loading data from Existing Episodes
• Customising server side logic
• Multiple instances of records
• Validation
• Wizards
• Complex steps
• Success Redirects

Loading Data From Existing Episodes

A URL without a patient id or episode id will create a new patent/episode when you save it.

To update a particular patient with a new episode, the URL should be: http://localhost:8000/pathway/#/simples/{{ patient_id }}

To update a particular episode the URL should be: http://localhost:8000/pathway/#/simples/{{ patient_id }}/{{ episode_id }}

When you load from these urls, your forms will come prepulated with the existing data for that patient/episode.

Customising The Server-side Logic

If you want to add any custom save logic for your step, you can put in a pre_save method. This is passed the full data dictionary that has been received from the client and the patient and episode that the pathways been saved for, if they exist (If you're saving a pathway for a new patient/episode, they won't have been created at this time).

TODO: How does the data work ? Is the expectation that I alter the data or save a subrecord?

TODO: Is there a post-save ?

TODO: What if I want to do validation on the server ?

Multiple Instances Of Records

If the model is not a singleton, by default it will be show in the form as a multiple section that allows the user to add one or more models.

This displays a delete button for existing subrecords.

By default, any subrecords that are deleted, or are not included in the data sent back to the server are deleted.

If you don't wish this to happen, pass delete_others=False to the MultiSaveStep.

import pathway
from myapp import models

class SimplePathway(pathway.Pathway):
    display_name = 'A simple pathway'
    slug         = 'simples'
    steps        = (
        pathways.MultiSaveStep(model=models.Allergies, delete_others=True),
        models.Treatment,
        models.PastMedicalHistory
    )

In this case, the pathway will delete any existing instances of the given Subrecord Model that are not sent back to the API in the JSON data.

### Complex Steps

If we want to save multiple types of subrecords at the same step, we can do that by including the relevant form templates in a custom step template.

import pathway
from myapp import models

class SimplePathway(pathway.Pathway):
    display_name = 'A simple pathway'
    slug         = 'simples'
    steps        = (
        pathways.Step(
            display_name='Demographics and Diagnosis',
            icon='fa fa-clock',
            template='pathways/demographics_and_diagnosis_step.html'
            ),
    )

The display name and icon are rendered in the header for this step in your pathway, which exist outside the scope of the step template itself. Then all we would need is the template itself:

<!-- pathways/demographics_and_diagnosis_step.html -->
{% include models.Demographics.get_form_template %}
{% include models.Diagnosis.get_form_template %}

Note pathways created in this way will not add in the model defaults.

Complex step logic

Pathway steps can be injected with a custom controller. You can do this by declaring an angular step in your controller.

for example

steps = (
  Step(
      model="NyModel",
      step_controller="FindPatientCtrl",
  ),

Your javascript controller should then look something like...

angular.module('opal.controllers').controller('FindPatientCtrl',
  function(scope, step, episode) {
    "use strict";
    // your custom logic
});

The scope passed in comes fully loaded with reference data and meta data. It also comes with the scope.editing. This is the dictionary that will appear in the form and will be saved back at the end.

The step is the step definition from the server, ie the output of step.to_dict.

The episode is the episode in its display state, before its been changed into a state that is ready to be displayed in the form.

steps can declare optional preSave method on their scope. This is passed the editing dictionary which will then be saved and can be altered in place if necessary.

Complex Steps With Multiple Instances Per Subrecord

If we need to also save multiple types of the same subrecord e.g. Treatment in this step, we simply use the multisave template tag.

{% load pathways %}

{% include models.Demographics.get_form_template %}
{% include models.Diagnosis.get_form_template %}
{% multisave models.Treatment %}

Alternatively you may want to create your own multisave step forms, you can use the multi-save-wrapper for this.

<div save-multiple-wrapper="editing.treatment">
  <div ng-repeat="editing in model.subrecords">
    {% input field="Treatment.drug" %}
    <button ng-click="remove($index)"></button>
  </div>

  <button ng-click="addAnother()"></button>
</div>

Complex Steps With Custom Javascript Logic

We can pass in custom controllers to individual steps. Custom controllers are sandboxed, they share scope.editing with other scopes but nothing else. They come prefilled with the defaults that you need. They are passed scope, step and episode.

The scope is the already preloaded with metadata and all the lookup lists so you that's already done for you.

scope.editing is also populated. If the subrecord is a singleton (ie with _is_singleton=True), its populated as an object. Otherwise it comes through to the custom controller and scope as an array of subrecords which is empty if there isn't one.

for example to make a service available in the template for a step, and only in that step

angular.module('opal.controllers').controller('AddResultsCtrl',
function(scope, step, episode, someService) {
    "use strict";

    scope.someService = someService
});

scope.editing is shared between all the steps and its what is sent back to the server at the end.

If you want to change any data before its sent back to the server you add a function called preSave on the scope. This is passed scope.editing.

Validation

If you want to add custom validation, there is an valid(form) method that is passed in the form. This means you can set validation rules on the form. An invalid form will have the save button disabled.

TODO - Server side validation?

TODO - Error messages - how do I set them?

Wizards

Wizard pathways look for a hideFooter variable that defaults to false. If set to true, this will hide the default next/save button. If you don't want the wizard pathway to be a linear progression, ie you want the user to go to different steps based on options they chose. This is a handy option for you.

If you want to handle complex order, this is best done in a custom controller for you step class. You can set this with.

TODO - Next step determination ?

Success Redirects

Often, after successfully saving a pathway, we want to redirect the user to a different URL - we do this by overriding the redirect_url method on the pathway. For example - to create a pathway that always logged the user out after a successful save:

class LogoutPathway(pathway.Pathway):
    display_name = 'Logout-O-Matic'
    steps        = (...)

    def redirect_url(self, patient):
        return '/accounts/logout/'

Redirect Mixins

By default any full page pathway (ie not a modal) will redirect to the episode detail view of that episode.

If you do not wish this to be the case you can override the redirect_url.

Pathways comes with the RedirectsToPatientMixin, which redirects to the Patient detail view and can be used as follows.

from pathways import RedirectsToPatientMixin

class PatientRedirectPathway(pathway.RedirectsToPatientMixin, pathway.PagePathway):
    display_name = 'Redirector example Pathway'
    steps = (...)

pathways.RedirectsToPatientMixin

Redirect to the patient detail page for this patient.

Modal Pathways

Pathways detect when you're opening a pathway from a modal.

You can use a different template for your modal pathway by adding a modal_template attribute to your pathway

Pathways ships with a no footer modal template, the same as the normal modal template but it doesn't display the section at the bottom with the save/cancel button.

To open a modal pathway in a template you can use the open-pathway directive:

<a open-pathway="test_results">open test results pathway</a>

The open-pathway directive also includes an optional callback, that is called with the context of the result of the modal.save method, ie episode_id, patient_id and redirect_url.

By default the pathway is opened with whichever episode is on $scope.episode, you can use pathway-episode to define a different episode.

e.g.

<a open-pathway="test_results"
   pathway-episode="someOtherEpisode"
   pathway-callback="refreshEpisode(episode_id)">
   open test results pathway
</a>

Reference

pathways.Pathway

The base pathway class.

Pathway.Pathway. attributes

Pathway.display_name

The human readable display name for this pathway. Will be used in the base template for full page pathways.

Pathway.slug

The slug to use in the URL for accessing an individual pathway, and the string that can be passed to Pathway.get() that will return i.t

Pathway.steps

The steps that make up this pathway. A tuple of either opal.models.Subrecord or pathway.Step subclasses.

Patway.pathway_service

The Service that is used to instantiate the pathway. This should inherit from the Pathway js service.

Patway.pathway_insert

The name of the class that you're replaceing with the pathway template. You probably shouldn't have to change this.

Patway.template

The name of the pathway template, it must include a div/span with the class .to_append which will be replaced by the wrapped step templates.

Patway.modal_template

If set, this template will be used if your pathway is opened in a modal. If its not set the template attribute will be used.

Pathway. methods

Pathway.redirect_url(self, patient, episde)

Returns a string that we should redirect to on success. Defaults to an episode detail screen

pathways.RedirectsToPatientMixin

Redirect to the patient detail page for this patient. he patient detail page, viewing the last episode for this patient.

Pathway.save(user=None, episode=None, patient=None)

Saves a pathway, it removes items that haven't changed and then saves with the Patient.bulk_update method

Utilities

pathways.steps.delete_others

deletes models that have not been pushed through in the data dictionary. This is the default behaviour, but if you're manually managing how subrecords are being saved in a custom save method, this can be useful.

Documentation Todo

Theming and templating Guide

Screenshots of default skin

Road Map

Early versions of Pathways leant heavily on the concept of wizard-style forms with multiple steps. After testing this with real users however we find that they frequently prefer long forms.

The next iteration for pathways therefore...

• Must build on the UnrolledPathway to make it easier to enter new steps
• Must use the Item api and take advantage of the form controller argument so we can have the same forms accross the board