Embed the authoring components

Algebrakit's authoring components let your users create and edit Algebrakit exercises without leaving your platform. Use them when you want authoring inside your own CMS rather than sending authors to the Algebrakit CMS.

There are three ways to use them, from whole exercises down to a single question:

Component	Use it when
Exercise editor	Authors work on a complete exercise, with all questions and settings in one editor.
Element and interaction editors	Your CMS owns the page layout and you want to edit one question or instruction block at a time.
ExerciseManager	You need to create, change or read exercises from code rather than through an editor.

All three need the proxy configured, exactly like the question components.

This page covers mounting the editors. Guidance on writing good exercises - question types, feedback, strategies - lives in the authoring documentation.

Exercise editor

Inserting the web component

You insert the Exercise Authoring Component using the akit-exercise-editor tag.

<html>
   <body>
      ...
      <akit-exercise-editor></akit-exercise-editor>
      ...
      <!--Configure proxy -->
      <script>
            AlgebraKIT = {
                config: {
                    proxy: {
                        url: '/algebrakit/proxy'
                    },
                }
            }
      </script>

      <!--Load frontend API -->
      <script src="https://widgets.algebrakit.com"></script>
   </body>
</html>

Getting and setting the exercise specification

The exercise editor initializes with an empty exercise. Use javascript to set or get the Exercise Definition object.

Method	Description
`getExercise`	`getExercise(): Promise<ExerciseDefinition>` Obtain the exercise definition, which you can use to create a new session.
`updateExercise`	`updateExercise(ex: ExerciseDefinition): Promise<void>` Initialises the authoring components with the given exercise definition.

Configuring the exercise editor

Attribute	Description
audiences	An 'audience' refers to a student profile, which Algebrakit uses to adjust language, mathematical notation, and solution strategies. This attribute specifies which audiences are available for the author. If omitted, Algebrakit will use the highest secondary education level in the United Kingdom (A-level). Example: audiences='[ {"name": "Nederlands", "id":"vwo-b"}, {"name": "English", "id": "uk_KS5"}]'
enable‑basic‑info	Enable fields for general information, such as exercise name, comments, and description. The default value is `false`.
enable‑metadata	Enable metadata fields in the settings tab. The default value is `false`.
enable‑id‑field	Show the button to copy the exercise ID to the clipboard. The default value is `true`
enable‑multiple-questions	Allow creating multiple questions, indexed with a, b, c, etc. The default value is `true`.
enable‑preview	Enable a preview button to run the exercise. The default value is `true`.
allow‑assets	Allow including images in the exercise. Default value is `true`.
interaction-blacklist	An optional list of question type identifiers to exclude from the editor. See below for the current list of question types

These are the question types (interactions) with their identifiers:

Question type	Identifier
Multi-step	`MULTISTEP`
Fill in the Blanks	`FILL_IN_THE_BLANKS`
Math Table	`MATH_TABLE`
Geometry & Graphs	`GEOMETRY`
Arithmetic Notebook	`CALCBOOK`
Number line	`NUMBER_LINE`
Written Arithmetic	`ARITHMETIC`
Multiple Choice	`CHOICE`
Open Answer	`OPEN_ANSWER`
Data Analysis	`STATISTICS`
Bar Model Method	`MODEL_METHOD`

Element and interaction editors

Algebrakit offers an Interaction Editor and an Element Editor. They need at least the following attributes:

exercise-id: The unique ID of the exercise object. The editor uses the ID to find the ExerciseManager for this exercise.
ref-id: the unique ID of the Interaction or Element in the exercise.

You insert these components using the akit-interaction-editor and akit-element-editor tags.

<html>
   <head></head>
   <body>
      <!--Insert one of these two options -->
      <akit-interaction-editor exercise-id="..." ref-id="..."></akit-interaction-editor>
      <akit-element-editor exercise-id="..." ref-id="..."></akit-element-editor>

      <!--Configure proxy -->
      <script>
            AlgebraKIT = {
                config: {
                    proxy: {
                        url: '/algebrakit/proxy'
                    },
                }
            }
      </script>

      <!--Load frontend API -->
      <script src="https://widgets.algebrakit.com"></script>
   </body>
</html>

ExerciseManager

When using Algebrakit's authoring components - especially in a custom integration - you may need to author or manage a single exercise or interaction block (e.g. a question or instruction). In this case, use the ExerciseManager interface to create, edit, and retrieve Algebrakit exercises programmatically.

Creating an exercise

Use one of the following methods depending on whether you are creating a new exercise or loading an existing one:

// Create a new exercise
AlgebraKIT.createExercise(options?: IEditorOptions): Promise<ExerciseManager>

// Load an existing exercise
AlgebraKIT.setExercise(spec: Exercise, options?: IEditorOptions): Promise<ExerciseManager>

ExerciseManager methods

Once you've created or loaded an exercise, the ExerciseManager gives you access to the following functionality:

Method	Description
`getExercise(): ExerciseDefinition`	Returns the full authored exercise specification.
`getExerciseId(): string`	Returns the unique ID of the exercise.
`setDefaultOptions(options: IEditorOptions)`	Sets default options for this exercise (e.g. audience or mode).
`addElement(elementIndex?: number, type: ElementType = "QUESTION")`	Adds a new block to the exercise. Use `"QUESTION"` for a scorable block or `"CONTENT"` for an instruction block.
`addInteraction(elementRef: number \| string, name?: string): InteractionSpec`	Adds a new interaction to the specified element (by index or ID).
`removeInteraction(refId: string)`	Removes the interaction with the given ID.
`removeElement(elementRef: number \| string)`	Removes the block (question or content) identified by index or ID.
`listInteractions(elementIndex: number): string[]`	Returns the IDs of all interactions in a given question block.
`listElements(): { [elementIndex: number]: string[] }`	Returns all block indices and their associated interaction IDs.

Editor options

You can customize the behavior and availability of certain features using the IEditorOptions object:

interface IEditorOptions {
  defaultQuestionMode: QuestionMode
  defaultAudience: { id: string }           // e.g. "uk_KS5"
  availableAudiences: Audience[]
}

Here, an Audience represents a student profile:

interface Audience {
  name: string  // e.g. "UK Key Stage 5"
  id: string    // e.g. "uk_KS5"
}

An element represents a question or instruction block. An instruction block cannot contain scorable interactions.

enum ElementType {
  "QUESTION"  // Scorable interactions
  "CONTENT"   // Instructional text or rich content
}

The QuestionMode controls how questions are presented to the student.

enum QuestionMode {
  "ALL_AT_ONCE"   // All question elements are visible at once
  "ONE_BY_ONE"    // Completing a question element shows the next one
}