Bilimland platform-constructor manifesto.md

Bilimland platform/constructor Manifesto

1. Platform doesn't know anything about Constructor
2. Constructor doesn't know anything about Platform
3. Modules are stand-alone. They do not know anything about neither Platform nor Constructor
   • Modules can be used in any kind of Platform, since it does not depend on it
   • Platform has to expose specific api to Modules, so if one builds such new Platform, it has to provide some properties

There is a contract between Platform and Modules, so in order to co-operate they both must follow some rules.

Platform Interface (IPlatform)

This is a API any Platform must expose to Modules

• module - this is the core is the content of index.json, of actual lesson, though some meta fields might be trimmed. The must-have are:
  • content
  • hints
  • title
  • id
  • type
• Module state information (such as whether module is in check mode, or readonly mode, etc.). Platform sets those variables, and Modules react. It's really up to Module as per how to react to it, from totally ignoring it to doing something with it, the main thing is Platform has to provide it, and Platform should not really care what Modules do with them.
  • isReadonly
  • isFinished
  • isCorrect
  • isFinalChecked
  • isOnceFailed
  • state
• path - path to index.json file. Example: lessons/L_10696
• assets - object containing information about assests (name, imageSize, duration, mime-type, etc.)
• contentState - weird thing, it seems that it holds information about state of some elements (toggleBlock), not sure why Platform has to keep this state
• lessonApi - special object with dispatch, and other methods which Modules need, they can sometimes change something in Platform (setScrollLock, setPage), or contain information about Platform state (isMobile)
• lang - it speaks for itself

What Platform knows about Modules

Platform and Modules require index.json of lesson to be of certain structure, on which they rely. Though these nuances are handled by Constructor which produces those index.json.

What Platform knows about Modules:

• title
• type
• audio
• hints
  • right
  • wrong
  • solution

These fields are used for different purposes inside Platform. For example, Platform accesses Modules hints field in order to display hints, thus each Module must have hints field.

When Platform needs something with Modules state

Sometimes Platform needs certain information about Module, whether about its data, or its state. If data can be accessed just accessing index.json, state is harder to reach, since it lives in Modules ¹. Exposing whole state, for Platform to use does not make sense, since then Modules state will have to be of certain structure, it's better if Platform does not know anything about Modules state (ideally, Modules state must be private to Modules).

And when such case arises, Modules export special functions which calculate information from its state and data, or just objects. They are imported into Platform.

What each Module must export for Platform:

• isCorrect - in order for Platform pagination to display solved modules as green/red
• def, map - those are needed for redux
• genCustomHints - Module must export this function if wants to display custom hints (currently, only Module utilizing this is expression, it displays hints per element)

Footnotes

1. When we say lives in Modules, what we actually mean, is that Platform mustn't directly access Modules state. Even though technically it's possible, since Platform imports all reducers of Modules and puts them in itself, so it actually hosts state of Modules ↩