Elements

Photon Elements are a set of prebuilt UI-components that can be used to add prescribing functionality into any web-based clinical tool.

Elements are built using WebComponent technology and can be used in any frontend app - regardless of framework. Elements do not use outdated iframe technology!

Elements automatically handle authentication and ensure that only authorized prescribers can send prescriptions. The UI is designed to be responsive across various screen sizes and can be easily styled.

1708 — This UI can be embedded directly in your clinical app.

<photon-client 
  id="YOUR_CLIENT_ID"
  org="YOUR_ORG_ID"
>
  <photon-prescribe-workflow/>
</photon-client>

Get Started

First install our elements package from NPM:

npm i @photonhealth/elements

If using a framework like React, you'll need to dynamically import the package. This will register the custom elements with the browser's CustomElementRegistry.

import("@photonhealth/elements")

You can also import within head tag in HTML:

<script src="https://cdn.rx.dev/elements/@latest/dist/index.js" type="module"></script>

Client Element

Next, add the photon-client element toward the top level of your application.

<photon-client
  id="your_client_id"
  org="your_org_id"
  redirect-uri="https://localhost:3000"
  dev-mode="true"
>
  <!-- nested photon elements -->
</photon-client>

Property	Description
`id`	The public ID registered to your application (with whitelisted URLs)
`org`	The Photon organization ID associated with your account
`auto-login`	Optional. Set this to `auto-login="true"` to trigger automatically login on page load if the user is unauthenticated
`redirect-uri`	Optional. Specifies where to redirect the user after a successful login. This cannot include a pathname, so for example it should look like `https://example.com` rather than `https://example.com/user/1234/prescribe`. You can however incorporate a strategy that handles a query parameter such as `https://example.com?redirect=user%2F1234%2Fprescribe`. When working locally, set the port to `3000` for authentication to work.
`redirect-path`	Optional. Helper that reroutes to a pathname after logging in returns the user to the redirect URI. An example redirect path is `user/1234/prescribe`. This will only work if the `photon-client` element exists at the `redirect-uri` base path.
`dev-mode`	Optional. When working locally set this to `"true"`in order to point our service at our staging service `neutron` rather than our production services at `photon`

These values can be found in the settings page of the Photon App, or in the Sandbox App. All photon- elements must be contained within the photon-client to function correctly.

If you're unable to put the photon-client at the root of your domain, then the property redirect-path will not work. However you can pass a query parameter to the redirect-uri property such as https://localhost:3000?redirect=dashboard and then handle the redirect with your own application logic.

Check out our example repo that shows how to handle the authentication redirect. The main branch shows how to use a query string to redirect and the root branch shows how to use the photon-client at root with the redirect-path.

Prescribe Element

The photon-prescribe-workflow can be added anywhere within the photon-client and renders a basic prescribe workflow. It accepts the following props:

Property	Description
`patient-id`	ID of the patient receiving the prescription
`template-ids`	Templates that should be pre-selected
`template-overrides`	When adding `template-ids` this attribute allows for overriding specific fields on the template. The overrides are a mapping where the keys are template IDs and the values are the override specifications. `<photon-prescribe-workflow template-ids="tmp_01H5JB37PPK9F64RE3QQ52WD7M,tmp_01GQJDV39GPEJ03BATZV1X0SRJ" template-overrides='{"tmp_01H5JB37PPK9F64RE3QQ52WD7M": {"instructions": "these instructions are overriding the previous instructions", "fillsAllowed": 200}}' />`
`prescription-ids`	Prescriptions that should be pre-selected
`enable-order`	Boolean that enables the creation of an order at the same time as a prescription. When this flag is set with nothing else, a pharmacy selection card will default to a "Local Pickup" option.
`enable-send-to-patient`	Prerequisite `enable-order` set to `true` . Boolean that allows prescribers to send patients the option to set their own pharmacy.
`enable-local-pickup`	Prerequisite `enable-order` set to `true` . Boolean that allows prescribers to set the patient's pharmacy for them.
`mail-order-ids`	Prerequisite `enable-order` set to `true`. Comma separated list of mail order pharmacy ids.
`pharmacy-id`	Prerequisite `enable-order` set to `true` . Sets a preselected pharmacy.
`address`	Optional, setting `address` will override the prescriber's ability to manually set the the patient's address when `enable-order` is set to `true`. The `address` object to be passed takes this shape: `{ city: string; postalCode: string; state: string; street1: string; street2?: string; country?: string; }` Please note that web components accept attributes as strings. Therefore, when passing an object as a prop, you must stringify it first. Here's an example of how to pass the address object to a web component: `address={JSON.stringify(address)}`

Here's an example of a Photon Element that enables orders to a preselected pharmacy:

<photon-prescribe-workflow
  patient-id="pat_9876zyxw"
  enable-order="true"
  pharmacy-id="phr_1234abcd"
/>

Alternatively, here's how you would enable an prescribe element with all of the pharmacy selection options:

<photon-prescribe-workflow
  patient-id="pat_01GQ0XFBHSH3YXN936A2D2SD7Y"
  enable-order="true"
  enable-send-to-patient="true"
  enable-local-pickup="true"
  mail-order-ids="phr_01GA9HPVBVJ0E65P819FD881N0"
/>

The above code will enable a similar Pharmacy Select card.

Events

Event payloads will be on detail.

document.addEventListener('photon-order-created', (e) => {
  console.log('Order Info: ', e.detail.order);
});

Event Name	Description	Detail
`photon-prescriptions-created`	Fired after prescriptions have been successfully created.	`{ prescriptions: Prescription[] }`
`photon-order-created`	If the `enable-order` flag is set and the prescriber selects to "Send Order", this will be fired after successfully creating the prescription and order.	`{ order: Order }`
`photon-prescriptions-error`	Fired upon errors creating prescriptions.	`{ errors: GraphQLError[] }`
`photon-order-error`	Fired upon errors creating the order.	`{ errors: GraphQLError[] }`

Framework Support

Below you'll find example integrations for React, Angular, and Vue.

import("@photonhealth/elements").catch(() => {});
import { createRef, useEffect, useState } from "react";

function App() {
  const photonPrescribeRef = createRef();

  useEffect(() => {
    const log = () => {
      console.log("treatment prescribed!");
    }
    if (photonPrescribeRef.current) {
      photonPrescribeRef.current.addEventListener("photon-prescribe-success", log);
      const removal = () => photonPrescribeRef.current.removeEventListener("photon-prescribe-success", log);
      return () => removal()
    }
  }, [])

  return (
    <div>
      <photon-client
        id="CLIENT_ID"
        org="ORGANIZATION_ID"
      >
         <photon-prescribe-workflow ref={photonPrescribeRef} />
      </photon-client>
    </div>
  );
}

export default App;

import { Component } from '@angular/core';
import('@photonhealth/webcomponents').catch(() => {});

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  title = 'my-app';

  public log() {
    console.log("treatment prescribed!");
  }
}

...

<div>
  <photon-client
      id="CLIENT_ID"
      org="ORGANIZATION_ID"
    >
      <photon-prescribe-workflow (photon-prescribe-success)="log()"></photon-prescribe-workflow>
    </photon-client>
</div>

<script setup lang="ts">
import("@photonhealth/webcomponents").catch((err) => {});

const log = () => {
  console.log("treatment prescribed!");
}
</script>

<template>
  <div>
    <photon-client
      id="CLIENT_ID"
      org="ORGANIZATION_ID"
    >
      <photon-prescribe-workflow v-on:photon-prescribe-success="log()" />
    </photon-client>
  </div>
</template>