Frontend API - Overview

The frontend API handles the creation of the web components and the processing of learning events. The frontend API is exposed by the global AlgebraKIT javascript object.

Include a script tag to your web page to load the frontend API. Use the endpoint closest to your location.

Ireland: https://widgets.algebrakit.com/akit-widgets.min.js
Singapore: https://prod.widgets.sg-1.algebrakit.com/akit-widgets.min.js

Note: Make sure you use the same location for the webservice endpoint.

Configuration

You can specify configuration parameters in the AlgebraKIT object. Include this configuration before the script tag that loads and initialises the frontend API.

<script>
    AlgebraKIT = {
        config: {
            proxy: {
                url: 'proxy/algebrakit'
            },
            //optional predefined theme
            theme: 'my-custom-theme',
            //optional styling configurations
            styles: {
                ...
            },
            //optional functional configuration
            behavior: {
                ...
            }

        }
    };
</script>
<!--Load API *after* setting configuration  -->
<script src="https://widgets.algebrakit.com/akit-widgets.min.js"></script>

Note:

Define the AlgebraKIT.config object before you load akit-widgets.min.js.
Do not add the async attribute to the script tag that loads akit-widgets.min.js. This guarantees that the AlgebraKIT object is fully initialised before you use it.
Do not load the akit-widgets.min.js script more than once.

Property	Description
`proxy`	If set, the web components will communicate with Algebrakit’s web service through this local proxy to prevent cross-origin communication. See the Proxy Config section to find out how to configure the proxy
`styles`	Can be used to customize the appearance of the Web Components. You can find the documentation for this here
`behavior`	Can be used to customize the functionality of the Web Components. See the Behavior Config section to find out how to configure this property
`theme`	An optional identifier to a predefined theme, which defines the style and design of the web components. Custom themes are created by the Algebrakit team based on your requirements.

Proxy Config

The Algebrakit components in the webpage need to communicate with the Algebrakit web service. You can configure that these requests are sent through a proxy that you provide. This proxy must support HTTP methods GET and POST.

If you use the Algebrakit Authoring Component inside your environment then you MUST provide another proxy that adds the API key to the requests. This allows the Authoring Component to run the exercises such that authors can test their work. This "secure proxy" must support HTTP methods GET, POST, and DELETE.

You can configure the proxies using properties proxy and secureProx in the AlgebraKIT.config object. Both properties are objects with the following schema.

Property	Description
`url`	The url for the proxy
`headers`	(optional) A key value map cointaining headers that will be added to the proxy request.

Example:

    AlgebraKIT = {
        config: {
            proxy: {
                url: 'proxy/algebrakit',
                headers: {
                    'X-CSRF-Token': 'my-value'
                }
            },
        }
    };

In this example, every request that does not require authorization will be sent through proxy/algebrakit with the added header X-CSRF-Token: my-value.

Behavior Config

You can configure behavior properties for all Algebrakit widgets or for specific interaction types.

    AlgebraKIT = {
        config: {
            behavior: {
                general: {
                    externalSubmitButton: false,
                    reviewModeShowSolution: true
                },
                components: {
                    inline: {
                        submitOnEnter: true
                    }
                }
            }
            //... other config properties
        }
    };

Any behavior property defined in the general section will be added to the configuration of every interaction type. while the properties defined in the components section will only be applied to that specific component. In the example shown above, the externalSubmitButton behavior is applied to every interaction type while submitOnEnter is only applied to "inline" interactions.

The following behavior can be configured in the general section:

Property	Type	Default	Description
`externalSubmitButton`	`boolean`	`false`	Set this to `true` if your learning platform has its own "hint" and "submit" buttons and you want to hide all built-in buttons from Algebrakit
`reviewModeShowSolution`	`boolean`	`false`	This applies to review mode. If set to `true` both the (incorrect) student input and the correct input is shown. Currently applies to multiple choice interactions only. The solution can only be shown if it is allowed. This is either if the session is locked or if the option `requireLockForSolution` is disabled in create session
`emitEventsOnRehydrate`	`boolean`	`false`	If true, re-emits all session events when an interaction is rehydrated (e.g. resumed after closing the browser window)

All properties from general can also be specified for a single component.

The following behavior can only be assigned to specific components:

`arithmeticNotebook`

Property	Type	Default	Description
`showProgress`	`boolean`	`true`	If false, hides the progress bar on the top right of Arithmetic Notebook

`inline`

Property	Type	Default	Description
`submitOnEnter`	`boolean`	`true`	If true, submits the student's input for the currently active widget when pressing "enter"

`mathTable`

Property	Type	Default	Description
`submitOnEnter`	`boolean`	`true`	If true, submits the student's input for the currently active widget when pressing "enter"

`geometry`

Property	Type	Default	Description
`measureInstrument`	`'GEO90' \| 'GEO180'`	`'GEO90'`	The type of measuring instrument that should be used for geometry interactions

`multistep`

Property	Type	Default	Description
`delayedFeedback`	`boolean`	`false`	When set to `true`, student input will not be evaluated until the 'Check' button is pressed. Otherwise, and when not in assessment mode, Multistep evaluates every expression immediately when entered.
`showCheckButton`	`boolean`	`true`	When set to `false`, the Check button in the Multistep question type is hidden.
`placeholderText`	`string`	"Enter your calculation here"	The text shown in the Multistep input area.

`authoring.multistep`

Property	Type	Default	Description
`initialExpression`	`boolean`	`false`	If true, the default setting for "initialExpression" is set to "From Task"

Exposed API

After the akit-widgets.min.js script is initialized, the following functionality is added to Algebrakit:

Function	Description
addExerciseListener	Add a listener to one of the events that are generated by Algebrakit web components.
getWidgets	Retrieve a list of all created web component instances.
render	Search and render expressions written in latex or MathML.
waitUntilReady	Wait until an exercise or interaction is fully initialised.

Add exercise listener

Register a listener for learning events on a session.

AlgebraKIT.addExerciseListener(
    function(eventData){
        //Do something with the eventData
    })

AlgebraKIT.addExerciseListener(
    sessionId: "my-session-id", 
    function(eventData){
        //Do something with the eventData
    })

The properties of the eventData object are listed below.

Parameter	Type	Description
`sessionId`	string	If given, register to events for this session. If omitted, register to events on all sessions.
`refId`	string	An ID corresponding to the specific interaction where the event originated
`event`	string	The type of this event. You can find a list of all events here
`data`	object	The event data sent with the event. The event overview describes what data objects can be expected with each event type

Get widgets

Returns a list with general data for all created web component instances.

AlgebraKIT.getWidgets(): <WidgetData[]>

<WidgetData> = {
   id <string>,
   tag <string>,
   attributes: [{key: value}],
   node: <HTMLElement>,
   interaction:<boolean>
}

Returns

Property	Description
`id`	An ID that is assigned to this web component.
`tag`	The tag name for this web component. Identifies the type of interaction.
`attributes`	List of attributes that are defined on the element.
`node`	The root DOM element of the generated web component.
`interaction`	Indicates whether the web component corresponds to an interactive exercise, or a non-interactive element such as a worked out solution, graph, table, etc.

Render

Searches for latex expressions or <mathml> nodes within node, or in the whole document if node is absent. Latex expressions are text enclosed within single or double dollar signs. Where a single dollar sign denotes inline rendering and double dollar signs denote so called ‘display view’ rendering.

AlgebraKIT.render(node: <HTMLElement>)

Wait for element initialisation

Wait until an Algebrakit interaction or Algebrakit exercise is fully initialised and ready to accept student input.

let elm = {some <akit-exercise> element}
await AlgebraKIT.waitUntilReady({<akit-exercise> element})
// the element is now ready for use
elm.submit();

Elements2HTML

Text content generated by Algebrakit generally contains math expressions. Examples are hint texts and error feedback in scoring information, see /session/score.

This function converts these content elements into HTML.

AlgebraKIT.elements2html(content: ContentElement[]): Promise<string>

Note that you can also include math content in your webpage without Javascript using the Web Component akit-content-view.