{
    "info": {
        "author": "",
        "author_email": "",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "# Pathways\n\nThe Opal Pathways plugin provides developers with a highly extensible method of\nworking with complex forms in [Opal](https://github.com/openhealthcare/opal).\nTypically pathways are forms that allow the user to enter information that spans multiple\n`Subrecords` - which can be challenging with the `Subrecord forms` provided by\nOpal itself.\n\n`Pathways` provides Wizards, long multi-model forms, custom validation and much more,\nall usable either in full page or modal contexts.\n\nThis plugin is **Alpha** software.\n\nAlthough it aldeady provides significant and useful functionality, it is in active development,\nand delvelopers should anticipate backwards-incompatible API changes as part of minor\n(x.VERSION.x) releases.\n\n[![Build\nStatus](https://travis-ci.org/openhealthcare/opal-pathway.png?branch=v0.4)](https://travis-ci.org/openhealthcare/opal-pathway)\n[![Coverage Status](https://coveralls.io/repos/github/openhealthcare/opal-pathway/badge.svg?branch=v0.4)](https://coveralls.io/github/openhealthcare/opal-pathway)\n\n## Contents\n\n* [Introduction: What is a Pathway?](#introduction-what-is-a-pathway)\n* [Installation](#installation)\n* [Quickstart Guide](#quickstart-guide)\n* [Detailed Topic Guides](#detailed-topic-guides)\n* [Reference Guides](#reference)\n* [Road Map](#road-map)\n* [Modal Pathways](#modal-pathways)\n\n## Introduction: What Is A Pathway?\n\nA pathway is a complex form that we can use in an Opal application. Pathways are comprised of a\ncollection of `Steps`.\n\n`Pathway Steps` are individual sections of that complex form which provide hooks to\ncustomise validation, presentation or behaviour in a granular manner.\n\nThe Pathways plugin ships with two types of pathway, which can be used either on their\nown page, or in an Opal modal:\n\n* Wizard style - e.g. the user has to click next to reveal each subsequent step\n* Single Page - e.g. displaying all the `Pathway Steps` from the start and the user scrolls to the next one\n\n## Installation\n\nClone `git@github.com:openhealthcare/opal-pathway`\n\nRun `python setup.py develop`\n\nAdd `pathway` to `INSTALLED_APPS` in your `settings.py`.\n\n## Quickstart Guide\n\nIn this section we walk you through creating a simple Pathway.\n\n### A First Pathway\n\nPathways are an Opal\n[Discoverable feature](http://opal.openhealthcare.org.uk/docs/guides/discoverable/) -\nthis means that Opal will automatically load any Pathways defined in a python module\nnamed `pathways.py` inside a Django App.\n\nIndividual pathways are defined by subclassing a `Pathway` class. You must set at least the\ndisplay name, and will\noften want to also set a slug.\n\nOut of the box, pathways ships with two types of pathways. A page pathway, a whole bunch of\nmodel forms on the same page, and a wizard pathway, a bunch of steps where the next step is\nonly revealed after the step before it has been completed.\n\nLet's look at a page pathway definition.\n\n```python\n# yourapp/pathways.py\nimport pathway\n\nclass MyPathway(pathway.PagePathway):\n    display_name = 'My Awesome Pathway'\n    slug         = 'awesomest-pathway'\n```\n\n### Taking Our First Steps\n\nA Pathway should have at least one `Step` - a section within the form.\n\n`Steps` are defined on the pathway class using the `Pathway.steps` tuple.\n\n```python\nimport pathway\nfrom myapp import models\n\nclass SimplePathway(pathway.PagePathway):\n    display_name = 'A simple pathway'\n    steps        = (\n        pathways.Step(model=models.PastMedicalHistory)\n    )\n ```\n\n### Model Steps\n\nA common case is for steps to be simply a single Opal `Subrecord` using the subrecord form template.\n\nIn fact we can simply add Opal `Subrecords` to the `steps` tuple to achieve the same effect.\n\nFor instance, to create a pathway with three steps to record a\npatient's allergies, treatment and past medical history, we could use the following:\n\n```python\nimport pathway\nfrom myapp import models\n\nclass SimplePathway(pathway.PagePathway):\n    display_name = 'A simple pathway'\n    slug         = 'simples'\n    steps        = (\n        models.Allergies,\n        models.Treatment,\n        models.PastMedicalHistory\n    )\n```\n\nPathways 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.\n\n\n### Viewing The Pathway\n\nThis pathway is then available from e.g. `http://localhost:8000/pathway/#/simples`.\n\n\n## Detailed Topic Guides\n\nIn this section we cover Pathway concepts in more detail.\n\n* [Loading data from Existing Episodes](#loading-data-from-existing-episodes)\n* [Customising server side logic](#customising-the-server-side-logic)\n* [Multiple instances of records](#multiple-instances-of-records)\n* [Validation](#validation)\n* [Wizards](#wizards)\n* [Complex steps](#complex-steps)\n* [Success Redirects](#success-redirects)\n\n### Loading Data From Existing Episodes\n\nA URL without a patient id or episode id will create a new patent/episode when\nyou save it.\n\nTo update a particular patient with a new episode, the URL should be:\n`http://localhost:8000/pathway/#/simples/{{ patient_id }}`\n\nTo update a particular episode the URL should be:\n`http://localhost:8000/pathway/#/simples/{{ patient_id }}/{{ episode_id }}`\n\nWhen you load from these urls, your forms will come prepulated with the\nexisting data for that patient/episode.\n\n\n### Customising The Server-side Logic\n\nIf 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).\n\n*TODO: How does the data work ? Is the expectation that I alter the data or save a subrecord?*\n\n*TODO: Is there a post-save ?*\n\n*TODO: What if I want to do validation on the server ?*\n\n### Multiple Instances Of Records\n\nIf the model is not a singleton, by default it will be show in the form as\na multiple section that allows the user to add one or more models.\n\nThis displays a delete button for existing subrecords.\n\nBy default, any subrecords that are deleted, or are not included in the data sent back\nto the server are deleted.\n\nIf you don't wish this to happen, pass `delete_others=False` to the `MultiSaveStep`.\n\n\n\n```python\nimport pathway\nfrom myapp import models\n\nclass SimplePathway(pathway.Pathway):\n    display_name = 'A simple pathway'\n    slug         = 'simples'\n    steps        = (\n        pathways.MultiSaveStep(model=models.Allergies, delete_others=True),\n        models.Treatment,\n        models.PastMedicalHistory\n    )\n```\n\nIn this case, the pathway will delete any existing instances of the given Subrecord Model that\nare not sent back to the API in the JSON data.\n\n###\u00a0Complex Steps\n\nIf we want to save multiple types of subrecords at the same step, we can do that by including the\nrelevant form templates in a custom step template.\n\n```python\nimport pathway\nfrom myapp import models\n\nclass SimplePathway(pathway.Pathway):\n    display_name = 'A simple pathway'\n    slug         = 'simples'\n    steps        = (\n        pathways.Step(\n            display_name='Demographics and Diagnosis',\n            icon='fa fa-clock',\n            template='pathways/demographics_and_diagnosis_step.html'\n            ),\n    )\n```\n\nThe display name and icon are rendered in the header for this step in your pathway, which\nexist outside the scope of the step template itself. Then all we would need is the template\nitself:\n\n```html\n<!-- pathways/demographics_and_diagnosis_step.html -->\n{% include models.Demographics.get_form_template %}\n{% include models.Diagnosis.get_form_template %}\n```\n\nNote pathways created in this way will not add in the model defaults.\n\n\n#### Complex step logic\n  Pathway steps can be injected with a custom controller. You can do this by declaring an angular step in your controller.\n\n  for example\n\n  ```python\n  steps = (\n    Step(\n        model=\"NyModel\",\n        step_controller=\"FindPatientCtrl\",\n    ),\n  ```\n\n  Your javascript controller should then look something like...\n\n  ```js\n  angular.module('opal.controllers').controller('FindPatientCtrl',\n    function(scope, step, episode) {\n      \"use strict\";\n      // your custom logic\n  });\n  ```\n\n  The scope passed in comes fully loaded with reference data and meta data.\n  It also comes with the scope.editing. This is the dictionary that will\n  appear in the form and will be saved back at the end.\n\n  The step is the step definition from the server, ie the output of\n  step.to_dict.\n\n  The episode is the episode in its display state, before its been changed\n  into a state that is ready to be displayed in the form.\n\n  steps can declare optional `preSave` method on their scope. This is passed\n  the editing dictionary which will then be saved and can be altered in place\n  if necessary.\n\n\n\n#### Complex Steps With Multiple Instances Per Subrecord\n\nIf we need to also save multiple types of the same subrecord e.g. `Treatment` in this step,\nwe simply use the `multisave` template tag.\n\n```html\n{% load pathways %}\n\n{% include models.Demographics.get_form_template %}\n{% include models.Diagnosis.get_form_template %}\n{% multisave models.Treatment %}\n```\n\nAlternatively you may want to create your own multisave step forms, you can use the multi-save-wrapper for this.\n\n```html\n\n<div save-multiple-wrapper=\"editing.treatment\">\n  <div ng-repeat=\"editing in model.subrecords\">\n    {% input field=\"Treatment.drug\" %}\n    <button ng-click=\"remove($index)\"></button>\n  </div>\n\n  <button ng-click=\"addAnother()\"></button>\n</div>\n```\n\n#### Complex Steps With Custom Javascript Logic\n\nWe can pass in custom controllers to individual steps. Custom\ncontrollers 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.\n\nThe scope is the already preloaded with metadata and all the lookup lists so you that's already done for you.\n\nscope.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.\n\nfor example to make a service available in the template for a step, and only in that step\n\n```js\nangular.module('opal.controllers').controller('AddResultsCtrl',\nfunction(scope, step, episode, someService) {\n    \"use strict\";\n\n    scope.someService = someService\n});\n```\n\n`scope.editing is shared between all the steps` and its what is sent back to the server at the end.\n\nIf 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.\n\n\n### Validation\n\nIf 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.\n\n*TODO - Server side validation?*\n\n*TODO - Error messages - how do I set them?*\n\n### Wizards\n\nWizard 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\nsteps based on options they chose. This is a handy option for you.\n\nIf you want to handle complex order, this is best done in a custom controller\nfor you step class. You can set this with.\n\n*TODO - Next step determination ?*\n\n### Success Redirects\n\nOften, after successfully saving a pathway, we want to redirect the user to a different\nURL - we do this by overriding the `redirect_url` method on the pathway. For example -\nto create a pathway that always logged the user out after a successful save:\n\n```python\nclass LogoutPathway(pathway.Pathway):\n    display_name = 'Logout-O-Matic'\n    steps        = (...)\n\n    def redirect_url(self, patient):\n        return '/accounts/logout/'\n```\n\n#### Redirect Mixins\n\nBy default any full page pathway (ie not a modal) will redirect to the episode\ndetail view of that episode.\n\nIf you do not wish this to be the case you can override the redirect_url.\n\nPathways comes with the RedirectsToPatientMixin, which redirects to the Patient\ndetail view and can be used as follows.\n\n\n```python\nfrom pathways import RedirectsToPatientMixin\n\nclass PatientRedirectPathway(pathway.RedirectsToPatientMixin, pathway.PagePathway):\n    display_name = 'Redirector example Pathway'\n    steps = (...)\n```\n\n##### pathways.RedirectsToPatientMixin\n\nRedirect to the patient detail page for this patient.\n\n\n## Modal Pathways\n\nPathways detect when you're opening a pathway from a modal.\n\nYou can use a different template for your modal pathway by adding a modal_template attribute to your pathway\n\nPathways 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.\n\nTo open a modal pathway in a template you can use the open-pathway directive:\n\n```html\n<a open-pathway=\"test_results\">open test results pathway</a>\n```\n\nThe 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.\n\nBy default the pathway is opened with whichever episode is on $scope.episode, you can use pathway-episode to define a different episode.\n\ne.g.\n\n```html\n<a open-pathway=\"test_results\"\n   pathway-episode=\"someOtherEpisode\"\n   pathway-callback=\"refreshEpisode(episode_id)\">\n   open test results pathway\n</a>\n\n```\n\n\n## Reference\n\n### pathways.Pathway\n\nThe base pathway class.\n\n#### Pathway.Pathway. _attributes_\n\n##### Pathway.display_name\n\nThe human readable display name for this pathway. Will be used in the base template for\nfull page pathways.\n\n##### Pathway.slug\n\nThe slug to use in the URL for accessing an individual pathway, and the string that can\nbe passed to `Pathway.get()` that will return i.t\n\n##### Pathway.steps\n\nThe steps that make up this pathway. A tuple of either `opal.models.Subrecord` or\n`pathway.Step` subclasses.\n\n###### Patway.pathway_service\n\nThe Service that is used to instantiate the pathway. This should inherit from the Pathway js service.\n\n\n###### Patway.pathway_insert\n\nThe name of the class that you're replaceing with the pathway template. You probably shouldn't have to change this.\n\n###### Patway.template\nThe 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.\n\n###### Patway.modal_template\n\nIf set, this template will be used if your pathway is opened in a modal. If its not set the template attribute will be used.\n\n\n#### Pathway. _methods_\n\n##### Pathway.redirect_url(self, patient, episde)\n\nReturns a string that we should redirect to on success. Defaults to\nan episode detail screen\n\n##### pathways.RedirectsToPatientMixin\n\nRedirect to the patient detail page for this patient.\nhe patient detail page, viewing the last episode for this patient.\n\n##### Pathway.save(user=None, episode=None, patient=None)\n\nSaves a pathway, it removes items that haven't changed and then\nsaves with the Patient.bulk_update method\n\n\n#### Utilities\n\n##### pathways.steps.delete_others\n\ndeletes models that have not been pushed through in the data dictionary. This\nis the default behaviour, but if you're manually managing how subrecords are\nbeing saved in a custom save method, this can be useful.\n\n\n### Documentation Todo\n\n*Theming and templating Guide*\n\n*Screenshots of default skin*\n\n## Road Map\n\nEarly versions of Pathways leant heavily on the concept of wizard-style forms with multiple steps.\nAfter testing this with real users however we find that they frequently prefer long forms.\n\nThe next iteration for pathways therefore...\n\n* Must build on the UnrolledPathway to make it easier to enter new steps\n* Must use the Item api and take advantage of the form controller argument so we can have the same forms accross the board\n",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "http://opal.openhealthcare.org.uk/",
        "keywords": "",
        "license": "LICENSE",
        "maintainer": "",
        "maintainer_email": "",
        "name": "opal-pathway",
        "package_url": "https://pypi.org/project/opal-pathway/",
        "platform": "",
        "project_url": "https://pypi.org/project/opal-pathway/",
        "project_urls": {
            "Homepage": "http://opal.openhealthcare.org.uk/"
        },
        "release_url": "https://pypi.org/project/opal-pathway/0.4/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "The pathway OPAL Plugin",
        "version": "0.4"
    },
    "last_serial": 2927359,
    "releases": {
        "0.4": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "c9ae8bd5a9a4d901ae46ea7211b30b60",
                    "sha256": "79945eb3845d09d03871f4faa79f841ffec15083aa0824ca989aea886ee7833e"
                },
                "downloads": -1,
                "filename": "opal-pathway-0.4.tar.gz",
                "has_sig": false,
                "md5_digest": "c9ae8bd5a9a4d901ae46ea7211b30b60",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 38424,
                "upload_time": "2017-06-05T19:25:02",
                "url": "https://files.pythonhosted.org/packages/c4/c5/44bede47ee96ae3d58b4ebbd7ddd727fd05ed25b37ed6362cd056b26e175/opal-pathway-0.4.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "c9ae8bd5a9a4d901ae46ea7211b30b60",
                "sha256": "79945eb3845d09d03871f4faa79f841ffec15083aa0824ca989aea886ee7833e"
            },
            "downloads": -1,
            "filename": "opal-pathway-0.4.tar.gz",
            "has_sig": false,
            "md5_digest": "c9ae8bd5a9a4d901ae46ea7211b30b60",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 38424,
            "upload_time": "2017-06-05T19:25:02",
            "url": "https://files.pythonhosted.org/packages/c4/c5/44bede47ee96ae3d58b4ebbd7ddd727fd05ed25b37ed6362cd056b26e175/opal-pathway-0.4.tar.gz"
        }
    ]
}