README English

CADL class and utilities

This package contains the CADL class used to process CADL objects in addition to utility functions used to validate the CADL YAML files.

To build the validation UI run the following:

//to install the dependencies
    npm i

//to build the bundle.js in the public directory
    npm run build

To run the CADL validation UI locally run the following command

    npm run start:val_ui

then navigate to https://localhost:5000/

Expect the following errors if a CADL Object is invalid

-InvalidDestination -when page jump destination is not a valid page -UnableToRetrieveYAML -when something goes wrong in retrieving the yaml file form S3 -UnableToParseYAML -if there is a parsing error

To run the CADL test page UI locally run the following command

    npm run start:test

To update the @aitmed/cadl package run

    git checkout master
    git pull origin master

    npm run publish:public

MAIN CADL/NOODL Documentation

CADL - Lvl 2.5 SDK.

This layer is connected to Lvl 2 SDK and noodl-ui-dom. The primary function of CADL is to parse and translate a noodl yaml file. CADL can resolve references in noodl file by replacing short-handed variables (marked by ., .., etc.) with values. It will then go through noodl file, parse it, and replace any functions with Lvl 2 API commands as appropriate.

CADL is created in the frontend web layer. On creation, its constructor will be provided with aspectRatio, cadlVersion, and configUrl as parameters. CADL will have access to a store, which is created using provided parameters of env and configUrl. This store will have access to Lvl 2 SDK, and implements Lvl 2 SDK's setters and getters. Inside of CADL constructor, several properties of store will be redirected, and store's noodlInstance will refer to the CADL.

An integral part of CADL is the root. When CADL is created, initRoot() function is called, and two things are attached to the empty root: an empty actions {} object, and an object of builtIn functions, which include things like createNewAccount, signIn, uploadDocument, etc. This process is completed within the CADL layer.

Implementation of CADL relies on a few important functions, which are supported by an array of helper functions. The important ones are:

CADL.init()

This function is called to initialize the CADL. This function can take three parameters (BaseDataModel, BaseCSS, and BasePage), but generally none are provided. A config variable is declared and assigned the variable retrieved from Lvl 2 SDK using loadConfig(), and config is destructured and assigned to the proper variables in CADL. From config, cadlBaseUrl is retrieved, and is used to locate cadlEndpointUrl. Using the cadlEndpointUrl we get cadlEndpoint, which contains baseUrl, assetsUrl, and preload. These are vital assets for parsing the noodl file.

The variable preload can be destructured to receive BasePage, BaseCSS, and BaseDataModel. These are the base elements in a noodl file; there are separate 'pages' in noodl that needs processing as well, such as SignIn, SignUp, and DocumentDetails, but these three serve as the base for other pages. For each of these pages, they are first retrieved using this.getPage() method, then processed down using this.processPopulate() method, and finally set into state using this.newDispatch() method. The key here is the processPopulate() method, which translates variables that start with ['.', '..', '=', '~'] into their fully expanded values using a recurssive algorithm. Once this process completes, these fully parsed objects/functions/variables are updated into root through state control dispatches.

After the above steps are completed, init() function checks for any items stored in local storage 'Global', and repeats the above parsing process. This process is not detected when the web first renders.

CADL.initPage()

This is another important method of CADL. Once the app starts, each page in noodl will need to be rendered separately, and that is the primary function of initPage(). This function is called in frontend code in src/index.js, and by createPreparePage() function. This function takes three parameters: pageName, an empty array denoted skip, and options. pageName variable is self-explanatory; skip[] can be used to include properties that are not to be "processed," e.g [edge] will lead to teh edge property of the noodl file to not be processed and will retain all variable references '..,.,=...etc'; the most notable thing about options is that once destructured, it contains a variable called evolve, and that must be true in order for the page to be rendered, otherwise the page will return. The evolve variable is invoked in frontend code, builtIn functions goto and goBack.

After the processing and evaluating are finished, initPage() then proceeds to process noodl page in a fashion similar to init(), using processPopulate(), but also dispatch method.

CADL.processPopulate()

This function is the primary function that handles the resolution of noodl files by processing references of variables in noodl files and replacing them with their fully extended form. This is specifically being done with the populateKeys() method, which recursively goes through the noodl file, find any symbols that signifies a referencing variable, and replace that variable with its fully extended form.

The function takes in five parameters: source, lookFor, skip, pageName, withFns. -source: the source page of noodl, written in object format -lookFor: an array of symbols to look out for, these symbols denote variables at current directory, parent directory, etc. that must be identified and have related variables resolved -skip: items to skip while parsing through source file -withFns: a boolean true or false that denotes whether or not to populate the functions -pageName: name of the noodl page

CADL.dispatch

This function handles the updating of the state(i.e noodl.root) as a result of return values from apis or builtIn fns.This function is bounded to the noodl/cadl instance and called within the builtIn fns and the object services (document, edges, vertexes). Within this function you will see the logic for 'eval-object.'

CADL.newDispatch

This is a lower level dispatch function that gets called to directly affect the state of the noodl.root through SET_VALUE, DELETE_VALUE, SET_ROOT_PROPERTIES, SET_LOCAL_PROPERTIES.

Methods That Can Be Accessed Through CADL/NOODL:

These functions can be accessed through builtInFns, which are attached to root as root.builtIn

Account Services

Document Services

Note Services

Note is analogous to Document. Any Note related functions are legacy code, with the exception of documentToNote, which is under src/services/Note/utils

Function: init Location: src/CADL/CADL.ts

throw new UnableToLoadConfig(
  `An error occured while trying to load the config. ` +
    `Config settings: ${JSON.stringify({
      apiHost: store.apiHost,
      apiProtocol: store.level2SDK.apiProtocol,
      apiVersion: store.level2SDK.apiVersion,
      configUrl: store.configUrl,
      env: store.env,
    })}`,
  err,
)

Function: builtIn Location: src/CADL/services/builtIn.ts

console.error(`Error occurred while invoking a builtIn function`, {
  apiObject,
  error: err,
  inputArgs: input,
  path: pathArr,
  pageName,
})

Function: sendRetrieveDocument Location: src/CADL/services/documents.ts

console.error(`Error occurred in the function "sendRetrieveDocument"`, {
  apiObject,
  cacheIndex,
  error,
  pageName,
  requestOptions,
})

throw error

Function: sendCreateDocument Location: src/CADL/services/documents.ts

console.error(`Error occurred in the function "sendCreateDocument"`, {
  apiObject,
  cacheIndex,
  error,
  pageName,
  requestOptions,
})
throw error

Function: sendCreateDocument Location: src/CADL/services/documents.ts

console.error(`Error occurred running the function Document.create`, {
  apiObject,
  data: populatedCurrentVal,
  error,
  pageName,
})
throw err

throw new UnableToLocateValue(
  `Missing reference ${targetEdgeID} in function "shareDocList"`,
)

console.error(`Error occurred in function "sendRetrieveEdge"`, {
  apiObject,
  cacheIndex,
  error: err,
  idList,
  requestOptions,
})

console.error(`Error occurred in function "sendCreateEdge"`, {
  apiObject,
  error: err,
  pageName,
  someObjectInTheFunction: obj,
})