> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praxis-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Theme Tools

> Theme Tools is a Nice Add-On to the Canvas Theme install — it layers editor widgets and on-page interactions on top of the embedded Pria SDK so Pria feels native to Canvas.

## Overview

**Theme Tools is a Nice Add-On** that sits on top of the standard [Canvas Theme integration](/mdx/integrations/canvas/theme). The base theme install (`pria-sdk-canvas.js`) embeds Pria as a floating button on every course page. **Theme Tools (`pria-sdk-canvas-tools.js`) is optional** — it adds editor widgets and on-page interactions that make Pria feel like a native part of Canvas:

* A **"Praxis" button in the TinyMCE toolbar** (pages, quizzes, assignments) that opens a modal to insert a Pria action button into your content.
* **Pria action buttons** authors can drop into pages — a single click sends a pre-canned message to Pria.
* **Start in Convo Mode** — a per-button checkbox that makes the saved button launch a Pria voice (Convo) session instead of a text chat.
* **"Submit Quiz to Praxis"** and **"Submit Assignment to Praxis"** interceptors that forward submissions to Pria alongside the normal Canvas submission.
* **"Explain with \<AI name>"** — a floating popup on text selection that asks Pria to explain the highlighted phrase in context.

<Tip>
  The base theme install works without Theme Tools. Add this file only if you want the editor widgets and Canvas-aware interactions.
</Tip>

## Source Code Access

The [pria-sdk-canvas-tools.js source code](https://gitlab.com/praxis-ai/pria-client-sdk/-/blob/main/canvas/tools/pria-sdk-canvas-tools.js) is available free of charge in the official community GitLab repository.

<Note>
  Always use the latest version on the `main` branch to ensure up-to-date features and security fixes. When linking the file in Canvas, **upload the raw file** — do not save the GitLab page itself.
</Note>

## Examples of widgets added by this library

<img src="https://mintcdn.com/praxisai/TvBOp6VaKv2F0wB2/images/integrations/canvas/tools/canvastools-explain.jpg?fit=max&auto=format&n=TvBOp6VaKv2F0wB2&q=85&s=9f7e33f4ac164ed49850a834b78a30ff" alt="Contextual Help: Explain" width="633" height="830" data-path="images/integrations/canvas/tools/canvastools-explain.jpg" />

<img src="https://mintcdn.com/praxisai/TvBOp6VaKv2F0wB2/images/integrations/canvas/tools/canvastools-button.jpg?fit=max&auto=format&n=TvBOp6VaKv2F0wB2&q=85&s=22001824e41f03936241cfd60edaff8c" alt="Edit Module: Assistant Button" width="896" height="626" data-path="images/integrations/canvas/tools/canvastools-button.jpg" />

<img src="https://mintcdn.com/praxisai/TvBOp6VaKv2F0wB2/images/integrations/canvas/tools/canvastools-assistanthelper.jpg?fit=max&auto=format&n=TvBOp6VaKv2F0wB2&q=85&s=115c0720db4201794c46827a0e7586c9" alt="Edit Module: Assistant Helper" width="486" height="659" data-path="images/integrations/canvas/tools/canvastools-assistanthelper.jpg" />

<img src="https://mintcdn.com/praxisai/TvBOp6VaKv2F0wB2/images/integrations/canvas/tools/canvastools-selectassistant.jpg?fit=max&auto=format&n=TvBOp6VaKv2F0wB2&q=85&s=4d690bbf726caf2046a268b9d030f6b5" alt="Edit Module: Assistant Chooser" width="275" height="391" data-path="images/integrations/canvas/tools/canvastools-selectassistant.jpg" />

***

## Installation

This step assumes the base [Canvas Theme integration](/mdx/integrations/canvas/theme) is already installed and customised. Theme Tools is **not uploaded as a separate file** — Canvas's Theme Editor only accepts a single JavaScript upload, so you concatenate Theme Tools onto the end of your customised `pria-sdk-canvas.js` and re-upload the combined file.

<Warning>
  Canvas Theme Editor accepts **one** custom JavaScript file per theme. Append, don't add a second upload. If the Upload tab already shows a JavaScript file, replacing it with the combined file is the right move.
</Warning>

<Steps>
  <Step title="Download the Theme Tools file">
    <Card title="pria-sdk-canvas-tools.js" icon="link" href="https://gitlab.com/praxis-ai/pria-client-sdk/-/raw/main/canvas/tools/pria-sdk-canvas-tools.js" cta="Download">
      Open the link, then save as `pria-sdk-canvas-tools.js`. We recommend keeping the file in your own source control so you can re-pull the latest version when upgrading.
    </Card>
  </Step>

  <Step title="Append Theme Tools to your customised pria-sdk-canvas.js">
    1. Open your customised `pria-sdk-canvas.js` (the one already in your theme) in a text editor.
    2. Paste the **entire contents** of `pria-sdk-canvas-tools.js` at the very end of the file.
    3. Save the combined file (still named `pria-sdk-canvas.js`).

    <Tip>
      **Order matters:** Theme Tools must come *after* the base SDK so that `window.priasdk` / `window.pria` exist by the time Theme Tools runs. The base SDK already exposes these globally.
    </Tip>

    **Recommended workflow for ongoing maintenance**

    Keep `pria-sdk-canvas.js` (your customised copy) and `pria-sdk-canvas-tools.js` as **separate** source files in version control, and concatenate them at deploy time:

    ```bash theme={null}
    # Linux / macOS
    cat pria-sdk-canvas.js pria-sdk-canvas-tools.js > pria-sdk-canvas-combined.js
    ```

    ```powershell theme={null}
    # Windows PowerShell
    Get-Content pria-sdk-canvas.js, pria-sdk-canvas-tools.js | Set-Content pria-sdk-canvas-combined.js
    ```

    This way, upgrades stay painless: pull the latest `pria-sdk-canvas-tools.js` from GitLab, re-concatenate, re-upload — without losing your `pria-sdk-canvas.js` customisations.
  </Step>

  <Step title="Upload the combined file to your Canvas theme">
    1. In Canvas, go to **Admin → Themes**, open your theme, and click **Edit**.
    2. On the **Upload** tab, under the **JavaScript file** section, click **Select** and choose your combined `pria-sdk-canvas.js`. This **replaces** the previously uploaded version.

    <Tip>
      No separate CSS upload is required. The modal styles are injected inline by the appended Theme Tools code.
    </Tip>
  </Step>

  <Step title="Preview, save, and verify">
    * Click **Preview Your Changes** in the Theme Editor.
    * Reload any course page; edit a page, quiz, or assignment description.
    * The **Praxis** button should appear in the TinyMCE toolbar (Miscellaneous group) with a sparkles icon over the "Praxis" label.
    * Click **Save** in the Theme Editor to apply the changes.
  </Step>
</Steps>

<Note>
  Canvas caches uploaded JS aggressively. Whenever you re-upload an updated combined file, save the theme and force-reload (Ctrl+Shift+R / Cmd+Shift+R) in your browser to flush old cached versions.
</Note>

***

## Configuration flags

The script exposes a `window.priaEnhancedCanvas` object with toggles you can edit before uploading the file. All flags default to `true`:

```javascript theme={null}
window.priaEnhancedCanvas.enablePriaButtons              = true; // Activate Pria action buttons on rendered pages
window.priaEnhancedCanvas.enablePageEditorButtons        = true; // Praxis toolbar button in the page editor
window.priaEnhancedCanvas.enableQuizEditorButtons        = true; // "Submit Quiz to Praxis" insert + interceptor
window.priaEnhancedCanvas.enableAssignmentEditorButtons  = true; // "Submit Assignment to Praxis" insert + interceptor
window.priaEnhancedCanvas.enableExplainWithAIPopup       = true; // Floating "Explain" popup on text selection
window.priaEnhancedCanvas.enableExplainWithAIName        = true; // If true, popup says "Explain with <AI name>"
window.priaEnhancedCanvas.explainWithAIButtonText        = 'Explain with'; // Customisable label
```

| Flag                            | What it controls                                                                                                                                                    |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enablePriaButtons`             | Whether on-page Pria action buttons (the ones authors place in content) actually fire when clicked. Set to `false` to deploy "preview only" without active buttons. |
| `enablePageEditorButtons`       | The **Praxis** toolbar button in the wiki page editor + its insert modal.                                                                                           |
| `enableQuizEditorButtons`       | The **Praxis** toolbar button in the quiz description editor + the runtime quiz-submit interceptor.                                                                 |
| `enableAssignmentEditorButtons` | Same as above, for assignments.                                                                                                                                     |
| `enableExplainWithAIPopup`      | The floating "Explain with…" popup that appears when a learner highlights text on a Canvas page.                                                                    |
| `enableExplainWithAIName`       | If `true`, the popup substitutes the live AI name (e.g. "Explain with Richard"). If `false` it stays generic.                                                       |
| `explainWithAIButtonText`       | The base label used by the popup. Defaults to `Explain with`.                                                                                                       |

***

## Inserting a Pria action button (page editor)

Open any Canvas page in **Edit** mode. In the TinyMCE toolbar, click the **Praxis** sparkles button. The "Assistant Helper Button" modal opens:

| Field                     | Purpose                                                                                                                                                                                                        |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Button Text**           | The label shown on the inserted button.                                                                                                                                                                        |
| **Button Style**          | CSS classes for styling — defaults to `btn btn-primary`. The encoded data class is added automatically and is not visible here.                                                                                |
| **Assistant**             | Pick a Digital Twin assistant the click should target, or "No Assistant" to use the page's default.                                                                                                            |
| **Message**               | The pre-canned text the button will send to Pria. Ignored when **Start in Convo Mode** is checked.                                                                                                             |
| **Conversation Id**       | The Pria conversation thread to attach this message to. Defaults to the current Canvas course id. Use `-1` to always start a new conversation.                                                                 |
| **Conversation Name**     | The display name of that conversation.                                                                                                                                                                         |
| **Open Pria after click** | When checked, after the button sends its message, the Pria UI panel auto-opens (`pria.display(true)`). Equivalent to clicking the floating Pria button. Has no effect in Convo mode (Pria is always revealed). |
| **Start in Convo Mode**   | See the next section.                                                                                                                                                                                          |

Click **OK** and the button is inserted at the cursor with the configuration encoded in its CSS class. Save the page; the button is live for learners.

To edit a button later, place the cursor on it and click the Praxis toolbar button again — the modal repopulates from the saved class (or from a legacy `data-custom` attribute, on older pages, which is automatically migrated to the class form on save).

***

## Start in Convo Mode (voice button)

When **Start in Convo Mode** is checked in the page-editor modal, the inserted button no longer sends a text message. Instead, on click it:

1. Sends a `convo.start` request to Pria with the configured assistant and conversation.
2. Reveals the Pria widget at a compact size in the bottom-right corner of the screen (smaller than the regular text panel) so it doesn't block course content.
3. The Pria UI initialises a voice session with the chosen assistant — the learner can talk to the AI directly.

If the learner subsequently clicks any **non-Convo** Pria action button (a regular text message button), Theme Tools and the SDK cooperate to:

* Send `convo.stop` so Pria tears down the voice session.
* Pass `interruptConvo: true` on the new `post` request as a backstop.
* Revert the widget to its normal docked text size and surface the text reply.

In other words, the user can switch from voice to text mid-flow by clicking another button — they don't need to manually close the panel.

<Tip>
  The **Message** field is ignored in Convo mode, but it's preserved in the saved configuration so you can toggle the checkbox back off later without retyping.
</Tip>

<Warning>
  Convo Mode requires that the institution have Convo (voice) enabled and that the user be authorised. If the AI service responds that Convo isn't available, the button click still reveals Pria so the learner can interact in text mode — but the voice session won't start. Verify entitlements with your Praxis AI administrator if Convo buttons aren't producing audio.
</Warning>

***

## Submit Quiz / Submit Assignment to Praxis

In the **quiz description** or **assignment description** editor, the Praxis toolbar button inserts a small placeholder block (`Submit Quiz Results to Praxis` / `Submit Assignment to Praxis`). Authors don't show this block to learners — it's a marker that activates the matching submit-time interceptor at runtime:

* When the learner clicks Canvas's **Submit Quiz** / **Submit File** button, the interceptor first forwards the answers (or a submission notice) to Pria, then lets Canvas continue with its native submit.
* The interceptor uses Pria's `post` command, which in turn cleanly closes any running Convo session before sending the message.

***

## Versioning and updates

The script's first line shows the current version, e.g.:

```javascript theme={null}
/* Enhanced Pria SDK with Canvas Tools - Version 1.5 - 2026-04-25 */
```

When you upgrade, re-download `pria-sdk-canvas-tools.js` from GitLab, re-concatenate it onto your customised `pria-sdk-canvas.js` (see the Installation steps above), re-upload the combined file to the Canvas Theme Editor, save the theme, and force-reload your browser. Existing `data-custom` buttons authored by previous versions continue to work in the editor and are silently migrated to the new class-encoded form the next time a teacher opens and saves the page.

***

## What's next?

<CardGroup cols={2}>
  <Card title="Canvas Theme integration" icon="code-fork" href="/mdx/integrations/canvas/theme">
    The base install. Theme Tools depends on this being in place.
  </Card>

  <Card title="Pria Tools (Canvas API access)" icon="wrench" href="/mdx/integrations/canvas/pria-tools">
    Let your Digital Twin read course content, modules, and assignments to give context-aware help.
  </Card>
</CardGroup>