Skip to content

Architecture

Jump to bottom
Arne Westphal edited this page Nov 8, 2018 · 1 revision

Architecture

In this chapter the internal components are explained. All relative links to .ts files are within the src folder.

API

API Diagram

These are the classes actively exported in the main.ts with their public methods. You might be able to use other classes of this module when using it as dependency, but those are not meant to be used outside of the actual package.

The converters as well as the objects are described in the Conversion page, the ExtensionManager in Extension Detection and Export Assets and the FileExtractor in Extract Linked Files.

Converters

Converter

The converters implement an interface IConverter. This defines the basic methods which have to be implemented by all converters. The interface might be extended by more specific classes, like a PdfSettingsObject in setOptions. The converters are internally implemented through a template with an abstract AConverter. The AConverter implement as much methods as possible given in the interface.

As stated in the Conversion page there is a difference between general converter options more often referred to as settings and conversion options. The latter has to be given on every toHtml or toFile call and is meant to be more case dependent. Converter options or settings are meant to be based on the users preference and independent of the actual file being converted.

So the markdown conversion generates the specific elearn.js code, extensions are needed. Those are implemented in the ShowdownExtensionManager. Everything regarding the actual markdown to html process is contained in this class. For an explanation on Showdown extensions check https://github.com/showdownjs/showdown/wiki/extensions. Right now the Wiki is incomplete and does not state the listener type. Check the source code of ShowdownExtensionManager for implemented examples.

Because the type declaration files should contain as few external classes as possible, the necessary methods of a Showdown.Converter are wrapped in the IShowdownConverter interface. This is not as easy possible for Puppeteer objects, thus those are included as they are and only extended by a few fields in the IBrowser interface. The IBrowser interface is used to store minor values used in the PdfConverter in a simple way.

Objects

Objects

The objects are pretty straight forward. Check the Conversion page for information on the fields.

The objects are separated into export options or conversion options as export and the converter options or settings as settings.

Export

  • ExtensionObject includes only information on inclusion of the elearn.js extensions
  • InclusionObject extends this by the language used, bundling all information necessary for elearn.js
  • ConversionObject extends this by options not regarding elearn.js directly
  • HtmlExportOptionObject and PdfExportOptionObject are specific options only used in the toFile (or toBuffer) method. These are options not needed for the markdown to html conversion but for additional processes

Settings

The settings are separated. The ConverterSettingsObject contains all general options which can be set in all converters. The PdfSettingsObject extends those by specific options only used by a PdfConverter. The HtmlConverter has no specific settings at the moment.

ExtensionManager

The ExtensionManager is pretty simple. It checks for certain expressions in the generated Html code for each included extension. The scanFor... methods allow specific scanning or scanning for everything at once. The scanMarkdownForAll method will convert the markdown first and then use scanHtmlForAll.

The get...AssetStrings are mainly used within the package to generate the Html head. Those will simply return a string containing Html elements to import everything necessary.

Also the ExtensionManager can export the extensions to a specific location with exportAssets. This will simply copy the bundled files to the output location.

FileExtractor

The FileExtractor generally works in two steps.

Step 1 is replaceAllLinks. It scans the Html and stores all linked files and where they have to be moved into a FileMoveObject[]. Also it updates the paths in the Html. Both will be returned in the FileExtractorObject.

Step 2 is extractAll. This actually copies all the files to the output directory.

To find the supported links and only those specific regular expressions where defined for the Html elements img, script, link and source. Only http links are ignored in this process.

Clone this wiki locally