Action Buttons

Last updated: 20 Jan 2025

Action buttons are UI elements that trigger specific actions when clicked in the Canvas UI. These buttons can be placed in different locations and can interact with runtime data to execute custom code.

Overview #

An ActionButton class allows you to define custom buttons that appear in different sections of the Canvas UI. When a user clicks the button, the action associated with the button is executed. Action buttons can be added to various locations in the UI, and you can control their visibility and behavior through effects in a handler class.

Creating an Action Button #

To implement a custom action button, you need to create a handler class that inherits from the ActionButton class. Your handler class must:

Define the constants BUTTON_TITLE, BUTTON_KEY, and BUTTON_LOCATION.
Implement the handle() method to specify the action that should be triggered when the button is clicked.
Optionally, implement the visible() method to control when the button should be shown.

Required Constants #

BUTTON_TITLE
A string that defines the label of the button displayed in the Canvas UI. This is the text the user sees when interacting with the button.
BUTTON_KEY
A unique identifier for your button. This key is used to route events, such as a click, to the appropriate handler method (handle()).
BUTTON_LOCATION
Specifies where the button will appear within the Canvas UI. The button can be placed in various locations, such as the note header or footer, or other areas within the chart summary.

Optional: Implement the `visible()` Method #

By default, the ActionButton class assumes the button is always visible (return True). If you want the button to only be visible under certain conditions, you can override the visible() method. This method must return a boolean value (True to show the button, False to hide it).

Implementing the `handle()` Method #

The handle() method is called when the action button is clicked. Inside this method, you can define what action should occur. The handle() method must return a list of Effect objects, which represent the actions to be executed when the button is clicked. If no action is required, you can return an empty list.

Button Locations #

The ActionButton class defines several locations where the button can be placed. The location is defined using the ButtonLocation enum. Supported button locations include:

Location	Description
`NOTE_HEADER`	The button will appear in the header of each note.
`NOTE_FOOTER`	The button will appear in the footer of each note.
`CHART_SUMMARY_SOCIAL_DETERMINANTS_SECTION`	The button will appear in the Social Determinants section of the chart summary.
`CHART_SUMMARY_GOALS_SECTION`	The button will appear in the Goals section of the chart summary.
`CHART_SUMMARY_CONDITIONS_SECTION`	The button will appear in the Conditions section of the chart summary.
`CHART_SUMMARY_MEDICATIONS_SECTION`	The button will appear in the Medications section of the chart summary.
`CHART_SUMMARY_ALLERGIES_SECTION`	The button will appear in the Allergies section of the chart summary.
`CHART_SUMMARY_CARE_TEAMS_SECTION`	The button will appear in the Care Teams section of the chart summary.
`CHART_SUMMARY_VITALS_SECTION`	The button will appear in the Vitals section of the chart summary.
`CHART_SUMMARY_IMMUNIZATIONS_SECTION`	The button will appear in the Immunizations section of the chart summary.
`CHART_SUMMARY_SURGICAL_HISTORY_SECTION`	The button will appear in the Surgical History section of the chart summary.
`CHART_SUMMARY_FAMILY_HISTORY_SECTION`	The button will appear in the Family History section of the chart summary.
`CHART_SUMMARY_CODING_GAPS_SECTION`	The button will appear in the Coding Gaps section of the chart summary.

Example Implementations #

Example 1: Log Information When Button is Clicked #

This example demonstrates a simple action button that logs some information when clicked. The button is visible only during the month of January.

from canvas_sdk.effects import Effect
from canvas_sdk.handlers.action_button import ActionButton
from datetime import datetime
from logger import log


class MyButton(ActionButton):
    BUTTON_TITLE = "🪵 Log Action"
    BUTTON_KEY = "LOG_ACTION"
    BUTTON_LOCATION = ActionButton.ButtonLocation.NOTE_HEADER

    def visible(self) -> bool:
        # Only show this button in January
        return datetime.now().month == 1

    def handle(self) -> list[Effect]:
        log.info("Button clicked!")
        log.info(self.event.context)
        log.info(self.event.target)

        return []

Example 2: Commit All Commands in a Note #

This example demonstrates an action button in the note footer that commits all commands within a note. The button is always visible since the visible() method is not overridden.

import json

from canvas_sdk.effects import Effect
from canvas_sdk.handlers.action_button import ActionButton
from canvas_sdk.v1.data.command import Command
from canvas_sdk.effects.base import EffectType

# Define a mapping of schema_key to EffectType
schema_key_to_effect_type = {
    "allergy": EffectType.COMMIT_ALLERGY_COMMAND,
    "assess": EffectType.COMMIT_ASSESS_COMMAND,
    "closeGoal": EffectType.COMMIT_CLOSE_GOAL_COMMAND,
    "diagnose": EffectType.COMMIT_DIAGNOSE_COMMAND,
    "familyHistory": EffectType.COMMIT_FAMILY_HISTORY_COMMAND,
    "goal": EffectType.COMMIT_GOAL_COMMAND,
    "instruct": EffectType.COMMIT_INSTRUCT_COMMAND,
    "hpi": EffectType.COMMIT_HPI_COMMAND,
    "medicalHistory": EffectType.COMMIT_MEDICAL_HISTORY_COMMAND,
    "medicationStatement": EffectType.COMMIT_MEDICATION_STATEMENT_COMMAND,
    "perform": EffectType.COMMIT_PERFORM_COMMAND,
    "plan": EffectType.COMMIT_PLAN_COMMAND,
    "questionnaire": EffectType.COMMIT_QUESTIONNAIRE_COMMAND,
    "reasonForVisit": EffectType.COMMIT_REASON_FOR_VISIT_COMMAND,
    "removeAllergy": EffectType.COMMIT_REMOVE_ALLERGY_COMMAND,
    "stopMedication": EffectType.COMMIT_STOP_MEDICATION_COMMAND,
    "surgicalHistory": EffectType.COMMIT_SURGICAL_HISTORY_COMMAND,
    "task": EffectType.COMMIT_TASK_COMMAND,
    "updateDiagnosis": EffectType.COMMIT_UPDATE_DIAGNOSIS_COMMAND,
    "updateGoal": EffectType.COMMIT_UPDATE_GOAL_COMMAND,
    "vitals": EffectType.COMMIT_VITALS_COMMAND,
}

class CommitButtonHandler(ActionButton):
    BUTTON_TITLE = "Commit all commands"
    BUTTON_KEY = "COMMIT_ALL_COMMANDS"
    BUTTON_LOCATION = ActionButton.ButtonLocation.NOTE_FOOTER

    def handle(self) -> list[Effect]:
        note_id = self.context.get("note_id")

        effects = []
        for command in Command.objects.filter(note_id=note_id):
            effect_type = schema_key_to_effect_type.get(command.schema_key)
            if not effect_type:
                raise ValueError(f"No EffectType defined for schema key '{command.schema_key}'.")

            effects.append(
                Effect(
                    type=effect_type,
                    payload=json.dumps({"command_uuid": str(command.id)}),
                )
            )

        return effects

Example 3: Show Button in Vitals Section and render HTML on click #

In this example, we place a button in the Vitals section and define an action where the button, when clicked, displays custom HTML content to the user. For more info about LaunchModalEffect, check the documentation.

from canvas_sdk.effects import Effect
from canvas_sdk.handlers.action_button import ActionButton
from canvas_sdk.effects.launch_modal import LaunchModalEffect
from logger import log


class VitalsButtonHandler(ActionButton):
    BUTTON_TITLE = "📊 Show Vitals Info"
    BUTTON_KEY = "SHOW_VITALS_INFO"
    BUTTON_LOCATION = ActionButton.ButtonLocation.CHART_SUMMARY_VITALS_SECTION

    def handle(self) -> list[Effect]:
        # This method will be called when the button is clicked
        log.info("Vitals info button clicked!")

        # Custom HTML content to display
        custom_html = """
        <div style="padding: 20px; background-color: #f0f8ff; border-radius: 5px;">
            <h3>Vitals Information</h3>
            <p>Patient's latest vitals data:</p>
            <ul>
                <li>Heart Rate: 72 bpm</li>
                <li>Blood Pressure: 120/80 mmHg</li>
                <li>Respiratory Rate: 16 breaths/min</li>
                <li>Temperature: 98.6°F</li>
            </ul>
            <p>For more details, please refer to the full report.</p>
        </div>
        """

        # Return a LaunchModalEffect to show the custom HTML content in a modal
        return [LaunchModalEffect(
            target=LaunchModalEffect.TargetType.DEFAULT_MODAL,
            content=custom_html
        ).apply()]

    def visible(self) -> bool:
        # Optionally, make the button visible only under specific conditions
        return True

Action Buttons

Overview #

Creating an Action Button #

Required Constants #

Optional: Implement the `visible()` Method #

Implementing the `handle()` Method #

Button Locations #

Example Implementations #

Example 1: Log Information When Button is Clicked #

Example 2: Commit All Commands in a Note #

Example 3: Show Button in Vitals Section and render HTML on click #

Useful guides

On this page

Overview #

Creating an Action Button #

Required Constants #

Optional: Implement the visible() Method #

Implementing the handle() Method #

Button Locations #

Example Implementations #

Example 1: Log Information When Button is Clicked #

Example 2: Commit All Commands in a Note #

Example 3: Show Button in Vitals Section and render HTML on click #

Useful guides

On this page

Optional: Implement the `visible()` Method #

Implementing the `handle()` Method #