Authoring Web Components

Algebrakit offers web components that allow authors to create Algebrakit exercises or interactions. You can integrate these web components into your authoring environment.

Setup

Algebrakit offers two types of authoring components:

An Exercise Authoring Component for authoring complete exercises, which can contain multiple instruction blocks and multiple interactions
Components to author elements inside an exercise, such as a single interaction or question in a multi-question exercise.

Which type of authoring components you should use depends on your integration approach.

Proxy setup

The authoring web components must be able to access the Algebrakit web service to test and run exercises. They communicate through a proxy on your backend for security reasons. This proxy relays incoming traffic to the Algebrakit API (for example, https://api.algebrakit.com) and adds the X-API-KEY header with your security token. The example code clarifies how you set up such a proxy.

Using the Exercise Authoring component

You can find a working example here.

Inserting the Web Component

The Exercise Authoring Component is an HTML/javascript component that you can add to your web page with just a few lines of code:

<html>
   <head></head>
   <body>
      ...  <!-- Whatever your page contains... -->

      <!--Insert the authoring component here -->
      <akit-exercise-editor></akit-exercise-editor>

      ...  <!-- Whatever your page contains... -->

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

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

Getting and setting the Exercise Specification

You can call the following methods on the akit-exercise-editor element. All methods are asynchronous.

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 Authoring component

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	Enable 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`

Authoring elements in exercises

The structure of exercises

An exercise contains one or more 'elements', where each element is either a content block or a question block (think questions a, b, c, etc.). Elements have zero or more 'interactions', which are the dynamic math components. Examples of such interactions are a Multistep question type, a dynamic graph, a ratio table, etc.

Note that every question type is an interaction, but not every interaction is a question type. For example, graphs or tables are interactions, even when they don't accept student input. Content blocks can contain interactions that are not question types.

An exercise has global properties that apply to all elements and interactions. Examples are the Student Profile, which configures language and curriculum, or random parameters to support auto-generated, random exercises.

Exercise =
  - Global Exercise Settings
  - List of Elements

Element = 
  - type: `CONTENT` or `QUESTION`
  - refId: a unique identifier for this Element
  - text and math content 
  - List of Interactions

Interaction = 
  - type (see list of question types above)
  - refId: a unique identifier for this Interaction
  - ... interaction-specific data

Figure: A schematic and high-level structure of an Algebrakit exercise

The ExerciseManager

You can manage an Exercise through an ExerciseManager object, which you can create for a new exercise or from an existing exercise specicication.

AlgebraKIT.createExercise(options?: IEditorOptions): Promise<ExerciseManager>
AlgebraKIT.setExercise(spec: Exercise, options?: IEditorOptions): Promise<ExerciseManager>

The ExerciseManager offers the following functionality:

Method	Description
`getExercise():Exercise`	Get the authored exercise specification
`getExerciseId():string`	Get the unique exercise ID of this exercise
`setDefaultOptions(options: IEditorOptions)`	Set options for this exercise
`addElement(elementIndex?: number, type? = "QUESTION")`	Adds a new block element to the exercise.
`addInteraction(elementRef: number\|string, name?: string):InteractionSpec`	Adds a new interaction to an Element. Refer to the element through index or the element refId.
`removeInteraction(refId: string)`	Remove the interaction from the exercise.
`removeElement(elementRef: number\|string)`	Remove the question element from the exercise
`listInteractions(elementIndex: number):string[]`	Retrieve the unique ID (ref-id) of all interactions in the given question element
`listElements():{ [elementIndex: number]: string[] }`	Get all element indices and the ref-ids in the elements at that index

Inserting the Web Component

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 can add the authoring component to your web page with a few lines of code:

<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: {
                    secureProxy: {
                        url: '/algebrakit-secure'
                    },
                }
            }
      </script>

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

Example code

You can find a working example here.