Package: opal-pathway
# PathwaysThe Opal Pathways plugin provides developers with a highly extensible method ofworking with complex forms in [Opal](https://github.com/openhealthcare/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 byOpal 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.[![BuildStatus](https://travis-ci.org/openhealthcare/opal-pathway.png?branch=v0.4)](https://travis-ci.org/openhealthcare/opal-pathway)[![Coverage Status](https://coveralls.io/repos/github/openhealthcare/opal-pathway/badge.svg?branch=v0.4)](https://coveralls.io/github/openhealthcare/opal-pathway)## Contents* [Introduction: What is a Pathway?](#introduction-what-is-a-pathway)* [Installation](#installation)* [Quickstart Guide](#quickstart-guide)* [Detailed Topic Guides](#detailed-topic-guides)* [Reference Guides](#reference)* [Road Map](#road-map)* [Modal Pathways](#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 acollection of `Steps`.`Pathway Steps` are individual sections of that complex form which provide hooks tocustomise validation, presentation or behaviour in a granular manner.The Pathways plugin ships with two types of pathway, which can be used either on theirown 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## InstallationClone `git@github.com:openhealthcare/opal-pathway`Run `python setup.py develop`Add `pathway` to `INSTALLED_APPS` in your `settings.py`.## Quickstart GuideIn this section we walk you through creating a simple Pathway.### A First PathwayPathways are an Opal[Discoverable feature](http://opal.openhealthcare.org.uk/docs/guides/discoverable/) -this means that Opal will automatically load any Pathways defined in a python modulenamed `pathways.py` inside a Django App.Individual pathways are defined by subclassing a `Pathway` class. You must set at least thedisplay name, and willoften want to also set a slug.Out of the box, pathways ships with two types of pathways. A page pathway, a whole bunch ofmodel forms on the same page, and a wizard pathway, a bunch of steps where the next step isonly revealed after the step before it has been completed.Let's look at a page pathway definition.```python# yourapp/pathways.pyimport pathwayclass MyPathway(pathway.PagePathway):display_name = 'My Awesome Pathway'slug         = 'awesomest-pathway'```### Taking Our First StepsA Pathway should have at least one `Step` - a section within the form.`Steps` are defined on the pathway class using the `Pathway.steps` tuple.```pythonimport pathwayfrom myapp import modelsclass SimplePathway(pathway.PagePathway):display_name = 'A simple pathway'steps        = (pathways.Step(model=models.PastMedicalHistory))```### Model StepsA 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 apatient's allergies, treatment and past medical history, we could use the following:```pythonimport pathwayfrom myapp import modelsclass 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 PathwayThis pathway is then available from e.g. `http://localhost:8000/pathway/#/simples`.## Detailed Topic GuidesIn this section we cover Pathway concepts in more detail.* [Loading data from Existing Episodes](#loading-data-from-existing-episodes)* [Customising server side logic](#customising-the-server-side-logic)* [Multiple instances of records](#multiple-instances-of-records)* [Validation](#validation)* [Wizards](#wizards)* [Complex steps](#complex-steps)* [Success Redirects](#success-redirects)### Loading Data From Existing EpisodesA URL without a patient id or episode id will create a new patent/episode whenyou 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 theexisting data for that patient/episode.### Customising The Server-side LogicIf 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 RecordsIf the model is not a singleton, by default it will be show in the form asa 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 backto the server are deleted.If you don't wish this to happen, pass `delete_others=False` to the `MultiSaveStep`.```pythonimport pathwayfrom myapp import modelsclass 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 thatare not sent back to the API in the JSON data.### Complex StepsIf we want to save multiple types of subrecords at the same step, we can do that by including therelevant form templates in a custom step template.```pythonimport pathwayfrom myapp import modelsclass 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, whichexist outside the scope of the step template itself. Then all we would need is the templateitself:```html<!-- 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 logicPathway steps can be injected with a custom controller. You can do this by declaring an angular step in your controller.for example```pythonsteps = (Step(model="NyModel",step_controller="FindPatientCtrl",),```Your javascript controller should then look something like...```jsangular.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 willappear in the form and will be saved back at the end.The step is the step definition from the server, ie the output ofstep.to_dict.The episode is the episode in its display state, before its been changedinto a state that is ready to be displayed in the form.steps can declare optional `preSave` method on their scope. This is passedthe editing dictionary which will then be saved and can be altered in placeif necessary.#### Complex Steps With Multiple Instances Per SubrecordIf we need to also save multiple types of the same subrecord e.g. `Treatment` in this step,we simply use the `multisave` template tag.```html{% 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.```html<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 LogicWe can pass in custom controllers to individual steps. Customcontrollers 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```jsangular.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.### ValidationIf 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?*### WizardsWizard 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 differentsteps 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 controllerfor you step class. You can set this with.*TODO - Next step determination ?*### Success RedirectsOften, after successfully saving a pathway, we want to redirect the user to a differentURL - 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:```pythonclass LogoutPathway(pathway.Pathway):display_name = 'Logout-O-Matic'steps        = (...)def redirect_url(self, patient):return '/accounts/logout/'```#### Redirect MixinsBy default any full page pathway (ie not a modal) will redirect to the episodedetail 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 Patientdetail view and can be used as follows.```pythonfrom pathways import RedirectsToPatientMixinclass PatientRedirectPathway(pathway.RedirectsToPatientMixin, pathway.PagePathway):display_name = 'Redirector example Pathway'steps = (...)```##### pathways.RedirectsToPatientMixinRedirect to the patient detail page for this patient.## Modal PathwaysPathways 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 pathwayPathways 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:```html<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.```html<a open-pathway="test_results"pathway-episode="someOtherEpisode"pathway-callback="refreshEpisode(episode_id)">open test results pathway</a>```## Reference### pathways.PathwayThe base pathway class.#### Pathway.Pathway. _attributes_##### Pathway.display_nameThe human readable display name for this pathway. Will be used in the base template forfull page pathways.##### Pathway.slugThe slug to use in the URL for accessing an individual pathway, and the string that canbe passed to `Pathway.get()` that will return i.t##### Pathway.stepsThe steps that make up this pathway. A tuple of either `opal.models.Subrecord` or`pathway.Step` subclasses.###### Patway.pathway_serviceThe Service that is used to instantiate the pathway. This should inherit from the Pathway js service.###### Patway.pathway_insertThe name of the class that you're replaceing with the pathway template. You probably shouldn't have to change this.###### Patway.templateThe 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_templateIf 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 toan episode detail screen##### pathways.RedirectsToPatientMixinRedirect 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 thensaves with the Patient.bulk_update method#### Utilities##### pathways.steps.delete_othersdeletes models that have not been pushed through in the data dictionary. Thisis the default behaviour, but if you're manually managing how subrecords arebeing saved in a custom save method, this can be useful.### Documentation Todo*Theming and templating Guide**Screenshots of default skin*## Road MapEarly 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