Content format

The content format of the Serlo editor

The basic idea behind the plugin system

Let's consider the following article about the difference quotient as an example:

The content can be separated in a list of logical sub-elements like "text", "equation" or "GeoGebra applet" in the above example. More elements like "multiple choice exercise", "video" or "definition" can be considered. We call these logical elements of a content "plugins". A plugin is described in JSON in the form:

{
  "plugin": "...", // name of the plugin
  "state": ... // necessary information to describe the plugin
}

Each plugin defines the form of its state. For example, for rendering an externally hosted GeoGebra applet we only need its ID on geogebra.org and thus only a string. In the above example we have the GeoGebra applet with ID nnrmthf4 and thus we describe the applet integration via the JSON:

{
  "plugin": "geogebra",
  "state": "nnrmthf4"
}

In this form we can describe the whole content and thereby get a list of plugins. We unite this list in a so called rows plugin. The rows plugin describes semantically an arbitrary list of plugins from a list of possible plugin types. So we end up with the following JSON:

This content format can be used to describe arbitrary educational content. When a new content format is needed (like a certain type of interactive exercise) we can define a plugin type. In this way the content format of Serlo is easily extendable.

Template plugins

Plugins can be also used to structure content. An example is our article plugin for serlo.org. We learned that a good article at our website follows a certain structure: There is often a short introduction in the beginning, possibly with a picture illustrating the topic. Afterwards, there is the main content which is followed by exercises and links to related content. Since we wanted to help our authors to create high quality content, we introduced the article plugin a couple of months ago. It follows the basic structure we identified to be useful (in the editing mode all elements besides the main content are optional):

You can use template plugins to standardize your own content formats or learning scenarios and guide your authors accordingly.

Combining template and content plugins

We can combine the power of template plugins with the list of available content plugins. In the following you see content format for the article "Differenzenquotient":

Storing and editing Metadata

Metadata about a plugin - like the license and the description meta_description of an article - is also stored inside the state object:

{
  "plugin": "article",
  "state": {
    "id": 234583,
    "license": {
      "id": 1,
      "title": "Dieses Werk steht unter der freien Lizenz CC BY-SA 4.0.",
      "url": "https://creativecommons.org/licenses/by-sa/4.0/deed.de",
      "iconHref": "https://i.creativecommons.org/l/by-sa/4.0/88x31.png"
    },
    "title": "Differenzenquotient",
    "meta_title": "Differenzenquotient",
    "meta_description": "Der Differenzenquotient beschreibt..."
  }
}

List of plugins

List of already implemented plugins at serlo.org

The following plugins are already implemented (see also this list in our source code).

Standard elements

• anchor – an anchor which can be referenced in a link

interface Anchor {
  state: string
}

• box – a semantic box like an example, a definition, a theorem, a hint, etc.

interface Box {
  type: string,
  title: {
    plugin: 'text',
    config: {
      plugins: {
        code: true,
        colors: false,
        headings: false,
        katex: true,
        links: false,
        lists: false,
        math: true,
        paragraphs: false,
        richText: false,
        suggestions: false,
      },
      noLinebreaks: true,
    },
  }
  anchorId: string,
  content: {
    plugin: Rows
  }
}

• blockquote – a citation

interface Blockquote {
  state: {
    content: {
      plugin: Text
    }
  }
}

• equations

interface Equations {
  steps: [
    { 
      left: string,
      sign: string,
      right: string,
      transform: string,
      explanation: {
        plugin: Text
    }
  ]
  firstExplanation: {
    plugin: Text
  }
  transformationTarget: 'equation',
}

• important – a box with an important message

interface Important {
  state: {
    plugin: Text
  }
}

• image – an image

interface Image {
  state: {
    src: upload(''),
    link?: {
        href: string,
        openInNewTab: false
    },
    alt?: string,
    maxWidth?: number(),
    caption?: {
      plugin: 'text'
    }
  }
} 

• multimedia – text with an illustration media object (like an image)

interface Multimedia {
  state: {
    explanation: {
      plugin: Rows
    },
    multimedia: {
      plugin: Image | Video | Geogebra
    },
    illustrating: true,
    width: number
  },
}

• rows – an arbitrary list of plugins from a defined list of plugin types

interface Rows {
  state: [
    {
      plugin: string, 
      state: unkwon
    }
  ]
}

• separator – a separator (e.g. <hr/> in HTML)
• spoiler – a spoiler

interface Spoiler {
  title: string, 
  content: {
    plugin: Rows
  }
}

• table – a table

interface Table {
  state: string
}

• text – a rich text element

• video – an included video

interface Video {
  state: {
    src: string,
    alt: string
  }
} 

Educational content plugins

• geogebra – an included GeoGebra applet

interface Geogebra {
  state: string
}

• inputExercise – an exercise with an input element

interface InputExercise {
  state: {
    type: string, 
    unit: string, 
    answers: [
      {
        value: string,
        isCorrect: boolean,
        feedback: {
          plugin: Text
        }
      }
    ]
  }
}

• scMcExercise – single or multiple choice exercise

interface ScMcExercise {
  isSingleChoice: false, 
  answers: [
    {
      content: {
        plugin: Text
      },
      isCorrect: false,
      feedback: {
        plugin: Text
      }
    }
  ]
} 

• serloInjection – another content of serlo.org which shall be included

interface SerloInjection {
  state: string
} 

• solution – the solution of an exercise

interface Solution {
  prerequisite?: {
      id: string,
      title: string,
  },
  strategy: {
    plugin: Text
  },
  steps: {
    plugin: Rows
  }
}

• textExercise – an exercise

Template Plugins

• serloArticle – a basic structure of an article for serlo.org
• serloArticleIntroduction – the introduction of an article

List of planned features

• "Fill the blanks" exercises
• "Drag and Drop" exercises
• "Image hotspot" exercises