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
An Interaction Authoring Component for authoring a single interaction.

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 https://api.algebrakit.com while adding 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	If set to `true`, the authoring component contains fields for general information, such as exercise name, comments, and description. The default value is `false`.
enable‑id‑field	If set to `false`, hide the button to copy the exercise ID to the clipboard. The default value is `true`
enable‑multiple-questions	If set to `false`, you cannot use the Authoring Component for multipart exercises. A multipart exercise consists of multiple questions indexed with a, b, c, etc. The default value is `true`.
enable‑preview	Set to `false` to hide the button to run the exercise. The default value is `true`.

Using the Interaction Authoring Component

The Interaction Authoring Component allows authoring a single interaction within an exercise. You can find a working example here.

The ExerciseManager

The Interaction Authoring Component needs an Exercise Manager, which represents the exercise the interaction is part of. You can create an Exercise Manager 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`	Obtain the authored exercise specification
`getExerciseId():string`	Obtain the unique exercise ID of this exercise
`setDefaultOptions(options: IEditorOptions)`	Set options that apply an authoring editor for this exercise
`addInteraction(elementIndex: number, name?: string):InteractionSpec`	Adds a new interaction to the exercise.
`removeInteraction(refId: string)`	Remove the interaction from the exercise.
`addElement(elementIndex?: number, type? = "QUESTION")`	Adds a new block element to the exercise. Type is "QUESTION" if the block contains questions or "CONTENT" if the block is an instruction.
`removeElement(elementIndex?: number)`	Removes 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[] }`	Returns all element indices and the ref-ids in the elements at that index

Inserting the Web Component

You can add the Interaction Authoring 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-interaction-editor exercise-id="..." ref-id="..."></akit-interaction-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>