Merge pull request #136 from TeselaGen/feature/ap/plugin-blog

Extends Plugins Framework blog

website/docs/software/plugins/exporter.md

@@ -0,0 +1,37 @@
+---
+title: 'Exporter Plugin'
+sidebar_position: 3
+slug: /software/plugins/exporter
+---
+
+# Exporter Plugin
+
+The FSML Plugin Framework provides the [Exporter Interface](/software/plugins/exporter#exporter-interface) which defines the structure the plugin package must export.
+
+## Structure
+- **name** (string): An identifier for plugin.
+- **type** (string): Type of the plugin. these must be one of the [Plugin Types](/software/plugins#plugin-types) provided by the FSML SDK.
+- **run** (function): Main function of the module which takes in an FSML manifest and returns one or many data objects along with optional files.
+
+
+## Exporter Interface
+
+The Exporter Interface extends the [Plugin Interface](/software/plugins#plugin-interface). Notice how the **run** function in an Exporter Plugin, extends the one from the Plugin interface into a specific set of input and output arguments.
+
+The input to the **run** function is an FSML manifest object and the output is one or many data objects or files with the contents of the FSML manifest in some other format.
+
+```typescript
+interface IExporter extends IPlugin {
+  /** Any arbitrary name */
+  name: "exporterName",
+  /** Must be of type PluginTypes.EXPORTER */
+  type: PluginTypes.EXPORTER,
+  /**
+   * Receives an fsml manifest and returns a
+   * file and data object of some unknown type (e.g, json, yaml, etc.).
+   */
+  run: (
+    manifest: TManifest,
+  ) => Promise<{ filepath: string; data: unknown }[]>;
+}
+```

website/docs/software/plugins/index.md

@@ -6,4 +6,45 @@ slug: /software/plugins/
 
 # Plugin Framework
 
-The Plugin Framework is part of the core features of the FSML SDK Library. It implements an interface that allows the community to develop programming packages that can leverage the SDK's functionalities and implement any custom logic requried by the user's use cases.
+The Plugin Framework is part of the core features of the FSML SDK Library. It implements an interface that allows the community to develop programming packages that can leverage the SDK's functionalities and implement any custom logic required by the user's use cases.
+
+## Plugin Types
+The FSML SDK supports a specific set of different types of Plugins, although generic plugins can also be implemented with any custom specific scope.
+
+- [Parser](/software/plugins/parser)
+- [Exporter](/software/plugins/parser)
+- [Generic](/software/plugins/parser)
+
+```typescript
+enum PluginTypes {
+  /**
+   * Any plugin used for transforming experimental
+   * data into an FSML manifest.
+   */
+  PARSER = "parser",
+  /**
+   * Any plugin used for exporting an FSML manifest
+   * into some other format.
+   */
+  EXPORTER = "exporter",
+  /**
+   * Any plugin used for other purposes. Keep in mind these type of plugins
+   * will not necessarily work with all of the FSML SDK modules.
+   */
+  GENERIC = "generic",
+}
+```
+
+## Plugin Interface
+All Plugins must extend this interface in order interact and integrate with the FSML SDK.
+
+```typescript
+interface IPlugin {
+    /** String identifier for plugin. */
+    name: string;
+    /** Type of the Plugin */
+    type: PluginTypes;
+    /** Generic main function */
+    run: (...args: any[]) => Promise<any>;
+}
+```

website/docs/software/plugins/parser.md

@@ -0,0 +1,81 @@
+---
+title: 'Parser Plugin'
+sidebar_position: 2
+slug: /software/plugins/parser
+---
+
+# Parser Plugin
+
+The FSML Plugin Framework provides the [Parser Interface](/software/plugins/parser#parser-interface) which defines the structure the plugin package must export.
+
+## Structure
+- **name** (string): An identifier for plugin.
+- **type** (string): Type of the plugin. these must be one of the [Plugin Types](/software/plugins#plugin-types) provided by the FSML SDK.
+- **run** (function): Main function of the module which takes in a file or a filepath and returns an FSML Manifest.
+- **isApplicable** (function): Secondary function used to determine whether the input file has the correct format or properties to be correctly parsed by this module. It is essentially a validation function whose main utility is to prevent any attempt at parsing a file not suited for the parser.
+
+## Parser Interface
+
+The Parser Interface extends the [Plugin Interface](/software/plugins#plugin-interface). Notice how the **run** function in a Parser Plugin, extends the one from the Plugin interface into a specific set of input and output arguments, plus the additional isApplicable validation function.
+
+The input to the **run** function can be either a filepath or a file data buffer or both, depending on the developer needs. For example, usually when working with the FSML CLI, the user will simply provide a filepath to where the input experimental data contents are located in the local file system. On the contrary, if the user/developer intends to leverage the FSML SDK within its own programming framework, she'll most likely benefit from passing in the data contents as a data buffer instead (e.g., from within a NodeRed Flow).
+
+```typescript
+interface IParser extends IPlugin {
+  /** Any arbitrary name */
+  name: "parserName",
+  /** Must be of type PluginTypes.PARSER */
+  type: PluginTypes.PARSER,
+  /**
+   * Receives a file as input and returns an FSML manifest (and optionally an output file).
+   */
+  run: (
+    /* Input File, either as a filepath (string) or as file data buffer (UintArray8) */
+    file: string | UintArray8,
+  ) => Promise<{
+      manifest: TManifest;
+      file?: string | UintArray8;
+    }>;
+  /* Input File, either as a filepath (string) or the file data buffer (UintArray8) */
+  isApplicable: (file: string | UintArray8) => Promise<boolean>;
+}
+```
+
+## Template
+
+Following the Plugins Framework interfaces described, we here show an example template of a Parser Plugin. that takes in a CSV file (either as a filepath or as a data buffer), parses it using any third-party npm csv reader packages and generates an FSML manifest.
+
+Note that the FSML SDK provides a set of handy utility functions that help the developer in many different ways. In this example the
+**createTemplateForType** function is leveraged, which generates an empty object (JSON) out of an FSML standard type imported from the FSML **standard** package.
+
+```typescript
+import fsml from "fsml"
+
+const templateParser: IParser = {
+  name: 'templateParser',
+  type: PluginTypes.PARSER,
+  run: async (file) => {
+    // If file is a filepath, read file's contents
+    const data: Uint8Array =
+      typeof file === 'string' ? fs.readFileSync(file) : file;
+
+    /**
+     * The FSML SDK provides the 'createTemplateForType' util function
+     * which creates an empty object FSML Manifest object.
+     */
+    const manifest: TManifest = fsml.utils.createTemplateForType(fsml.standard.Manifest);
+
+    /** The data is then feed into a common npm csv parser package which returns a JSON array of the csv rows. */
+    const rows = csvParser(data)
+
+    /** Finally, some custom function can be used to take those rows and format them as required by FSML standard. */
+    manifest.SupplementalData.data[0].rows = jsonRowsToFsml(rows)
+
+    return await Promise.resolve({ manifest });
+  },
+  isApplicable: async (file) => {
+    /** Custom validation logic should be implemented here */
+    return Promise.resolve(true)
+  },
+};
+```