Merge pull request #4350 from serlo/feat/add-learner-events-to-package

feat(editor): add learner event handler to package

packages/editor/README.md

@@ -84,7 +84,13 @@ See below for the current API specification.
 - **Long-Term Support**: Unsure
 - **Needs Change?**: Unsure
 
-### `SerloEditor` component props
+#### 7. `type LearnerEventData`
+
+- **Why Exported/How Used**: This is how the `SerloRenderer` provides the details of a learners interaction to `handleLearnerEvent` (see below).
+- **Long-Term Support**: Unsure
+- **Needs Change?**: Unsure
+
+### `SerloEditor` component props (`SerloEditorProps`)
 
 - **`children`**: When passed in a function as the `children` prop, the `SerloEditor` component provides an `editor` render prop as the argument to the `children` function. This `editor` object provides:
 
@@ -107,6 +113,12 @@ See below for the current API specification.
 
 - **`_ltik` (optional)**: Required by the custom plugin `edusharingAsset` only used in `serlo-editor-for-edusharing`. **To be removed once a better solution is found or the plugin is removed.**
 
+### `SerloRenderer` component props (`SerloRendererProps`)
+
+- For `language`, `state`, `_ltik` and `editorVariant` please see props for `SerloEditor` above.
+
+- **`handleLearnerEvent` (optional)**: Function that receives details about the learners interaction in the form of `LearnerEventData`. Provide if you want to connect the editor to you LRS (Learning Record Store) or similar. [In our wiki you can find more details and a xAPI example](https://github.com/serlo/documentation/wiki/Learner-Events-and-xAPI).
+
 ### `pluginMenuEn` / `pluginMenuDe` constant and `Plugin` enum
 
 Exports two records with following structure which you can use to create your own plugin menu in either German or English. This is useful when you for example want to integrate the Serlo Editor as a block / part of another editor.

packages/editor/src/___dev-demo/preview.tsx

@@ -1,5 +1,6 @@
 import { showToastNotice } from '@editor/editor-ui/show-toast-notice'
 import { EditorPluginType, SerloEditor, SerloRenderer } from '@editor/package'
+import { LearnerEventData } from '@editor/plugin/helpers/editor-learner-event'
 import { parseDocumentString } from '@editor/static-renderer/helper/parse-document-string'
 import { AnyEditorDocument } from '@editor/types/editor-plugins'
 import { useMemo, useState } from 'react'
@@ -90,6 +91,10 @@ export function Preview() {
           <SerloRenderer
             state={parseDocumentString(previewState)}
             editorVariant="unknown"
+            handleLearnerEvent={(data: LearnerEventData) => {
+              // eslint-disable-next-line no-console
+              console.log(data)
+            }}
           />
         </div>
       </section>

packages/editor/src/package/index.ts

@@ -3,6 +3,7 @@ export { SerloRenderer, type SerloRendererProps } from './serlo-renderer'
 
 export type { SupportedLanguage } from '@editor/types/language-data'
 export type { BaseEditor } from '@editor/core'
+export type { LearnerEventData } from '@editor/plugin/helpers/editor-learner-event'
 
 // We need to make a distinction between entires on our menu and technical
 // plugin types Internally we have for example a `scMcExercise` which has a

packages/editor/src/package/serlo-renderer.tsx

@@ -2,6 +2,10 @@ import { EditorMetaContext } from '@editor/core/contexts/editor-meta-context'
 import { createRenderers } from '@editor/editor-integration/create-renderers'
 import { EditStringsProvider } from '@editor/i18n/edit-strings-provider'
 import { StaticStringsProvider } from '@editor/i18n/static-strings-provider'
+import {
+  editorLearnerEvent,
+  LearnerEventData,
+} from '@editor/plugin/helpers/editor-learner-event'
 import { editorRenderers } from '@editor/plugin/helpers/editor-renderer'
 import { StaticRenderer } from '@editor/static-renderer/static-renderer'
 import type { SupportedLanguage } from '@editor/types/language-data'
@@ -16,6 +20,7 @@ export interface SerloRendererProps {
   state: unknown
   _ltik?: string
   editorVariant: EditorVariant
+  handleLearnerEvent?: (data: LearnerEventData) => void
 }
 
 export function SerloRenderer(props: SerloRendererProps) {
@@ -36,6 +41,10 @@ export function SerloRenderer(props: SerloRendererProps) {
   const basicRenderers = createRenderers()
   editorRenderers.init(basicRenderers)
 
+  if (props.handleLearnerEvent) {
+    editorLearnerEvent.init(props.handleLearnerEvent)
+  }
+
   return (
     <StaticStringsProvider value={staticStrings}>
       <EditStringsProvider value={editStrings}>