Layout Effects

Last updated: 20 Jan 2025

Patient Summary #

There are many summary sections in a patient’s chart, organized by data type. While there is a default ordering, you can use an Effect to reorder them or hide some of them entirely. The PatientChartSummaryConfiguration class helps you craft the effect to do so.

The example below shows reordering and hiding or omitting some of the sections:

from canvas_sdk.events import EventType
from canvas_sdk.handlers.base import BaseHandler
from canvas_sdk.effects.patient_chart_summary_configuration import PatientChartSummaryConfiguration


class SummarySectionLayout(BaseHandler):
    RESPONDS_TO = EventType.Name(EventType.PATIENT_CHART_SUMMARY__SECTION_CONFIGURATION)

    def compute(self):
        layout = PatientChartSummaryConfiguration(sections=[
          PatientChartSummaryConfiguration.Section.CARE_TEAMS,
          PatientChartSummaryConfiguration.Section.SOCIAL_DETERMINANTS,
          PatientChartSummaryConfiguration.Section.ALLERGIES,
          PatientChartSummaryConfiguration.Section.CONDITIONS,
          PatientChartSummaryConfiguration.Section.MEDICATIONS,
          PatientChartSummaryConfiguration.Section.VITALS,
        ])

        return [layout.apply()]

The PatientChartSummaryConfiguration takes a single argument, sections, which is expected to be a list at least one element long, filled with choices from the PatientChartSummaryConfiguration.Section enum. The .apply() method returns a well-formed Effect object.

This effect is only used in response to the PATIENT_CHART_SUMMARY__SECTION_CONFIGURATION event. It does nothing in any other context.

Values in the PatientChartSummaryConfiguration.Section enum are:

Constant	Description
SOCIAL_DETERMINANTS	social_determinants
GOALS	goals
CONDITIONS	conditions
MEDICATIONS	medications
ALLERGIES	allergies
CARE_TEAMS	care_teams
VITALS	vitals
IMMUNIZATIONS	immunizations
SURGICAL_HISTORY	surgical_history
FAMILY_HISTORY	family_history
CODING_GAPS	coding_gaps

Action Buttons #

Each section of the patient chart can also be customized with action buttons. Please refer to the Action Buttons documentation for more information.

Patient Profile #

The PatientProfileConfiguration class allows you to reorder, hide, and/or specificy whether sections load expanded or collapsed.

import json

from canvas_sdk.effects import Effect, EffectType
from canvas_sdk.effects.patient_profile_configuration import PatientProfileConfiguration
from canvas_sdk.events import EventType
from canvas_sdk.protocols import BaseProtocol
from logger import log


class Protocol(BaseProtocol):
    """This protocol is used to configure which sections appear in the Patient Profile section.

    The SHOW_PATIENT_PROFILE_SECTIONS payload expects a list of sections where each section is a dict like { "type": str, "start_expanded": bool }
    The accepted values for the "type" are:
    "demographics", "preferences", "preferred_pharmacies", "patient_consents",
    "care_team", "parent_guardian", "addresses", "phone_numbers", "emails", "contacts"
    """

    # Name the event type you wish to run in response to
    RESPONDS_TO = EventType.Name(EventType.PATIENT_PROFILE__SECTION_CONFIGURATION)

    def compute(self) -> list[Effect]:
        """This method gets called when an event of the type RESPONDS_TO is fired."""

        sections = [
            PatientProfileConfiguration.Payload(type=PatientProfileConfiguration.Section.PREFERENCES,
                                                             start_expanded=False),
            PatientProfileConfiguration.Payload(type=PatientProfileConfiguration.Section.DEMOGRAPHICS,
                                                             start_expanded=False),
            PatientProfileConfiguration.Payload(
                type=PatientProfileConfiguration.Section.PREFERRED_PHARMACIES, start_expanded=True),
            PatientProfileConfiguration.Payload(type=PatientProfileConfiguration.Section.PARENT_GUARDIAN,
                                                             start_expanded=False),
            PatientProfileConfiguration.Payload(type=PatientProfileConfiguration.Section.CONTACTS,
                                                start_expanded=True),
            PatientProfileConfiguration.Payload(type=PatientProfileConfiguration.Section.CARE_TEAM,
                                                             start_expanded=False),
            PatientProfileConfiguration.Payload(type=PatientProfileConfiguration.Section.TELECOM,
                                                             start_expanded=False),
            PatientProfileConfiguration.Payload(type=PatientProfileConfiguration.Section.ADDRESSES,
                                                             start_expanded=False),
            PatientProfileConfiguration.Payload(type=PatientProfileConfiguration.Section.PATIENT_CONSENTS,
                                                start_expanded=False),
        ]

        effect = PatientProfileConfiguration(sections=sections).apply()

        return [effect]

The PatientProfileConfiguration takes a single argument, sections, which is expected to be a list at least one element long, filled with PatientProfileConfiguration.Payload objects. These are python typed dictionaries that expect a PatientProfileConfiguration.Section choice, which describes a section of the patient profile, and a start_expanded boolean, which determines if the fields in that section should be exposed by default. The .apply() method returns a well-formed Effect object.

This effect is only used in response to the PATIENT_PROFILE__SECTION_CONFIGURATION event. It does nothing in any other context.

Values in the PatientProfileConfiguration.Section enum are:

Constant	Description
DEMOGRAPHICS	demographics
PREFERENCES	preferences
PREFERRED_PHARMACIES	preferred_pharmacies
PATIENT_CONSENTS	patient_consents
CARE_TEAM	care_team
PARENT_GUARDIAN	parent_guardian
ADDRESSES	addresses
TELECOM	telecom
CONTACTS	contacts

Modals #

The LaunchModalEffect class allows you to launch modals in Canvas, providing a flexible way to display content or navigate to external resources.

Example Usage #

from canvas_sdk.effects import LaunchModalEffect, EffectType

class ModalEffectHandler:
    def compute(self):
        modal_effect = LaunchModalEffect(
            url="https://example.com/info",
            content=None,
            target=LaunchModalEffect.TargetType.DEFAULT_MODAL
        )
        return [modal_effect.apply()]

The LaunchModalEffect class has the following properties:

• url: A string containing the URL to load within the modal. If content is also specified, an error will be raised.
• content: A string containing the content to be displayed directly within the modal. If url is also provided, an error will be raised.
• target: Defines where the modal should be launched. Options include:
  • DEFAULT_MODAL: Opens the URL in a modal centered on the screen.
  • NEW_WINDOW: Opens the content in a new browser window.
  • RIGHT_CHART_PANE: Opens the URL in the right-hand pane of the patient chart.

Custom HTML and Django Templates #

To facilitate the use of custom HTML, you can utilize the render_to_string utility from canvas_sdk.templates to render Django templates with a specified context. This allows for dynamic rendering of HTML that can be passed to a LaunchModalEffect.

def render_to_string(template_name: str, context: dict[str, Any] | None = None) -> str | None:
    """Load a template and render it with the given context.

    Args:
        template_name (str): The path to the template file, relative to the plugin package.
            If the path starts with a forward slash ("/"), it will be stripped during resolution.
        context (dict[str, Any] | None): A dictionary of variables to pass to the template
            for rendering. Defaults to None, which uses an empty context.

    Returns:
        str: The rendered template as a string.

    Raises:
        FileNotFoundError: If the template file does not exist within the plugin's directory
            or if the resolved path is invalid.
    """

Example Template #

Consider a simple HTML file named templates/modal_content.html:

<!DOCTYPE html>
<html>
<head>
    <title>{{ title }}</title>
</head>
<body>
    <h1>{{ heading }}</h1>
    <p>{{ message }}</p>
</body>
</html>

This template uses Django template placeholders like {{ title }}, {{ heading }}, and {{ message }} to dynamically render content based on the provided context.

Rendering the Template in Python #

Here’s how you can use the render_to_string utility to render the template and pass the resulting HTML to a LaunchModalEffect:

from canvas_sdk.effects import LaunchModalEffect
from canvas_sdk.templates import render_to_string

class ModalEffectHandler:
    def compute(self):
        # Define the context for the template
        context = {
            "title": "Welcome Modal",
            "heading": "Hello, User!",
            "message": "This is a dynamically rendered modal using Django templates."
        }

        # Render the HTML content using the template and context
        rendered_html = render_to_string("templates/modal_content.html", context)

        # Create a LaunchModalEffect with the rendered content
        modal_effect = LaunchModalEffect(
            content=rendered_html,
            target=LaunchModalEffect.TargetType.DEFAULT_MODAL
        )

        return [modal_effect.apply()]

Additional Configuration #

To use URLs or custom scripts within the LaunchModalEffect, additional security configurations must be specified in the CANVAS_MANIFEST.json file of your plugin.

1. Allowing URLs: URLs specified in the url property of LaunchModalEffect must be added to the origins.urls section of the CANVAS_MANIFEST.json.
2. Allowing custom scripts: If custom HTML contains scripts, the script origins must be added to the origins.scripts section of the CANVAS_MANIFEST.json.

The URLs must match the format available here.

{
    "sdk_version": "0.1.4",
    "plugin_version": "0.0.1",
    "name": "custom_html",
    "description": "...",
    "origins": {
        "urls": ["https://example.com/info"],
        "scripts": ["https://d3js.org/d3.v4.js"]
    }
}