Creating an Activity - mdenet/educationplatform GitHub Wiki

To create an activity for the education platform there are three steps to complete:

  1. Create the resources for the activity.
  2. Create the activity configuration file.
  3. Make activity files available.

Note that a VSCode extension is now available to support creation of the configuration file.

The following video provides a walk through of creating a teaching activity using the platform:

IMAGE ALT TEXT

Resources

Use your preferred tool(s) to create project files or use pre-existing files to use as the activities' resources, for example, use Eclipse to create an Xtext project.

For some example activities please see the educationplatform-examples repository. To try them out visit the MDENet Education Platform public instance.

Existing Tool Services

The following list indicates tools that are available to use in platform activities.

Tool Source Public Instance Config URL
Conversion https://github.com/mdenet/platformtools https://mdenet-ep.sites.er.kcl.ac.uk/tools/conversion/conversion_tool.json
EMF https://github.com/mdenet/platformtools https://mdenet-ep.sites.er.kcl.ac.uk/tools/emf/emf_tool.json
Emfatic https://github.com/mdenet/platformtools https://mdenet-ep.sites.er.kcl.ac.uk/tools/emfatic/emfatic_tool.json
Epsilon https://github.com/epsilonlabs/playground-micronaut https://mdenet-ep.sites.er.kcl.ac.uk/tools/epsilon/tools
OCL https://github.com/mdenet/platformtools https://mdenet-ep.sites.er.kcl.ac.uk/tools/ocl/ocl_tool.yml
Xtext https://github.com/mdenet/platformtools https://mdenet-ep.sites.er.kcl.ac.uk/tools/xtext/xtext_tool.json

Common Utilities

The education platform provides three built-in common utility panel definitions that can be referenced in activities' panel declarations.

ID description
console Displays textual responses from tool functions e.g. logs.
output Displays file contents which can be textual or diagrammatic.
composite Structural container of panels enables child panels to be selectively hidden.

Note - for further details on panel classes see tool panel definitions

Activity Configuration

activities

Top-level configuration file object

Key Value Multiplicity
activities Activity 1..* Array of Activity objects.

Activity

The activity object describes a learning activity, including how it is displayed by the platform.

Key Value Multiplicity
id String 1..1 A unique string used
title String 1..1 The text used for display.
icon String 1..1 Reference to the name of the icon to use. See Icons for details of where icon files should be located.
tools String 0..* Tool configuration file urls of the tools the activity uses. If this activity includes a panel generated by another activity (e.g., when the Xtext tool generates an editor), you can use {{ID-<panel-id>}} as part of a URL definition. This will be rewritten to the URL generated for that panel, if any, allowing generated tools to be loaded dynamically. The replacement will not include any trailing /.
layout Layout 1..1 Layout object.
actions Action 0..* Array of Action objects.
panels Panel 0..* Array of Panel objects.

Layout

The layout object specifies how the panels are displayed.

Key Value Multiplicity
area String[] 1..* Two-dimensional array of rows of panel ids that corresponds to the position of the displayed position of the panels.

Action

An Action object describes the mapping of panel contents to the input parameters of tool functions when a given button is clicked. Additionally, it specifies the panel where the return of the tool function is displayed. If a tool provides console output in addition to another output type, it can be displayed in the panel with the id given by outputConsole.

Key Value Multiplicity
source String 1..1 The panel id of the panel contains the source button.
sourceButton String 1..1 The button id of the source button.
parameters Parameter 1..1 Parameter object
output String 1..1 Panel id where the tool function return will be displayed.
outputConsole String 0..1 Panel id where the tool function console output will be displayed.

Parameter

The parameter object declares the mapping of input parameters of a tool function to panel contents or a string.

Key Value Multiplicity
[function parameter name] String 0..1 The id of a panel that the contents will be used or a string.

There must be a key for every parameter of the source button's action function.

Panel

A panel object describes the contents that should be displayed in a panel. The types of panels for editing and displaying different files are defined by tools and their configuration. For tools that create editor instances the editor panel that will be created is declared.

The default icon and buttons of a panel definition's can be customised by defining the icon and buttons in the activity panel. Buttons defined by the activity panel take precedence over the panel definition however they can be included by using the corresponding button ID.

Key Value Multiplicity
id String 1..1 A unique string used for identification.
name String 1..1 The text used for display.
ref String 1..1 Reference to a panel definition's id from a tool configuration. Use composite to instantiate a blank CompositePanel so you can add your own sub-panels.
file String 1..1 The relative path to the file that is displayed by the panel. This can also be a full URL, including to files outside of the repository that this activity lives in (though in this case, the contents cannot be saved back by the user). You can use {{ID-<panel-id>}} to indicate the URL of a generated tool, if any (e.g., for Xtext-generated editors).
editorActivity String 0..1 For tools that create editor instances e.g. language workbenches, reference to the id of the activity that contains the editor.
editorPanel String 0..1 For tools that create editor instances e.g. language workbenches, reference to the id of a panel of editorActivity that is the editor instance.
icon string 0..1 Reference to the name of the icon to use instead of the default icon defined by the panel.
buttons Button | Object 0..* Buttons to use instead of the default buttons defined by the panel. Can be a Button object or an Object with a ref attribute whose value is the id of a button from the panel's definition. For composite panels (where ref is set to composite), this can include toggle buttons to show and hide different sub-panels.
childPanels Panel 1..* For composite panels (where ref is set to composite), the child panel objects that it contains.

Making Activities Available

The activities can be made in two ways self-hosting or using GitHub.

Self-hosted

For self-hosting activities the activities and resource files can be hosted using any webserver or webhost service available. The files just need to be accessible via http from the students' browser that is running the education platform.

GitHub

GitHub repositories are supported for loading and saving activities to/from.

Public

Public GitHub repositories can be used by:

  1. Commit the activity files to a new or existing repository.
  2. Provide the raw url of the activity configuration files as the activities url parameter.
[PLATFORM_URL]?activities=[ACTIVITY_RAW_URL]

Private

Private GitHub repositories can be used by:

  1. Set up a tokenserver
  2. Follow the steps for public repositories.
  3. Login when prompted by the platform to access the private activity.
⚠️ **GitHub.com Fallback** ⚠️