@dosgato/templating 0.0.1

package/.eslintrc.json

@@ -0,0 +1,15 @@
+{
+  "extends": "standard-with-typescript",
+  "parserOptions": {
+      "project": "./tsconfig.eslint.json"
+  },
+  "rules": {
+    "@typescript-eslint/explicit-function-return-type": "off", // useless boilerplate
+    "@typescript-eslint/array-type": "off", // forces you to use Array<CustomType> instead of CustomType[], silly
+    "@typescript-eslint/no-non-null-assertion": "off", // disables using ! to mark something as non-null,
+                                                       // generally not avoidable without wasting cpu cycles on a check
+    "@typescript-eslint/no-unused-vars": "off", // typescript already reports this and VSCode darkens the variable
+    "@typescript-eslint/return-await": ["error", "always"], // allows you to accidentally break async stacktraces in node 14+
+    "@typescript-eslint/strict-boolean-expressions": "off" // we know how truthiness works, annoying to have to avoid
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Texas State ETC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,8 @@
+# dosgato-templating
+A library to support building templates for dosgato CMS.
+
+This library provides types and classes necessary to provide structure to the
+process of building a new template. The rendering server, API, and Admin UI will depend
+on this structure to accomplish their work.
+
+For now, see the code for comments on how it all works.

package/dist-esm/index.js

@@ -0,0 +1,5 @@
+import all from '../dist/index.js'
+
+export const ResourceProvider = all.ResourceProvider
+export const Component = all.Component
+export const Page = all.Page

package/dist-esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@dosgato/templating",
+  "version": "0.0.1",
+  "description": "A library to support building templates for dosgato CMS.",
+  "exports": {
+    "require": "./dist/index.js",
+    "import": "./dist-esm/index.js"
+  },
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "prepublishOnly": "npm run build",
+    "build": "rm -rf dist && tsc"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "eslint-config-standard-with-typescript": "^21.0.1",
+    "typescript": "^4.4.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/txstate-etc/dosgato-templating.git"
+  },
+  "keywords": [
+    "cms",
+    "component",
+    "template"
+  ],
+  "author": "Nick Wing",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/txstate-etc/dosgato-templating/issues"
+  },
+  "homepage": "https://github.com/txstate-etc/dosgato-templating#readme"
+}

package/src/component.ts

@@ -0,0 +1,167 @@
+import { Page } from './page'
+import { ResourceProvider } from './provider'
+
+/**
+ * This is the primary templating class to build your templates. Subclass it and provide
+ * at least a render function.
+ *
+ * During rendering, it will be "hydrated" - placed into a full page structure with its
+ * parent and child components linked.
+ */
+export abstract class Component<DataType extends ComponentData = any, FetchedType = any, RenderContextType extends ContextBase = any> extends ResourceProvider {
+  // properties each template should provide
+  static templateKey: string
+  static templateName: string
+
+  // properties for use during hydration, you do not have to provide these when
+  // building a template, but you can use them in the functions you do provide
+  areas = new Map<string, Component[]>()
+  data: Omit<DataType, 'areas'>
+  fetched!: FetchedType
+  renderCtx!: RenderContextType
+  path: string
+  parent?: Component
+  page?: Page
+  hadError: boolean
+
+  /**
+   * The first phase of rendering a component is the fetch phase. Each component may
+   * provide a fetch method that looks up data it needs from external sources. This step
+   * is FLAT - it will be executed concurrently for all the components on the page for
+   * maximum speed.
+   *
+   * Note that this.page will be available, along with its ancestors property containing
+   * all the data from ancestor pages, in case there is a need for inheritance. It is
+   * recommended to copy any needed data into the return object, as future phases will not
+   * want to resolve the inheritance again.
+   */
+  async fetch (editMode: boolean) {
+    return undefined as unknown as FetchedType
+  }
+
+  /**
+   * The second phase of rendering a component is the context phase. This step is TOP-DOWN,
+   * each component will receive the parent component's context, modify it as desired,
+   * and then pass context to its children.
+   *
+   * This is useful for rendering logic that is sensitive to where the component exists in
+   * the hierarchy of the page. For instance, if a parent component has used an h2 header
+   * already, it will want to inform its children so that they can use h3 next, and they inform
+   * their children that h4 is next, and so on. (Header level tracking is actually required in
+   * dosgato CMS.)
+   *
+   * This function may return a promise in case you need to do something asynchronous based on
+   * the context received from the parent, but use it sparingly since it will stall the process.
+   * Try to do all asynchronous work in the fetch phase.
+   */
+  setContext (renderCtxFromParent: RenderContextType, editMode: boolean): RenderContextType|Promise<RenderContextType> {
+    return renderCtxFromParent
+  }
+
+  /**
+   * The final phase of rendering a component is the render phase. This step is BOTTOM-UP -
+   * components at the bottom of the hierarchy will be rendered first, and the result of the
+   * render will be passed to parent components so that the HTML can be included during the
+   * render of the parent component.
+   */
+  abstract render (renderedAreas: Map<string, string[]>, editMode: boolean): string
+
+  /**
+   * Sometimes pages are requested with an alternate extension like .rss or .ics. In these
+   * situations, each component should consider whether it should output anything. For
+   * instance, if the extension is .rss and a component represents an article, it should
+   * probably output an RSS item. If you don't recognize the extension, just return
+   * super.renderVariation(extension, renderedAreas) to give your child components a chance to
+   * respond, or return empty string if you want your child components to be silent in all
+   * cases.
+   *
+   * This function will be run after the fetch phase. The context and html rendering phases
+   * will be skipped.
+   */
+  renderVariation (extension: string, renderedAreas: Map<string, string>) {
+    return Array.from(renderedAreas.values()).join('')
+  }
+
+  // the constructor is part of the recursive hydration mechanism: constructing
+  // a Component will also construct/hydrate all its child components
+  constructor (data: DataType, path: string, parent: Component|undefined) {
+    super()
+    this.parent = parent
+    const { areas, ...ownData } = data
+    this.data = ownData
+    this.path = path
+    this.hadError = false
+    let tmpParent = this.parent ?? this
+    while (!(tmpParent instanceof Page) && tmpParent.parent) tmpParent = tmpParent.parent
+    if (!(tmpParent instanceof Page)) throw new Error('Hydration failed, could not map component back to its page.')
+    this.page = tmpParent
+  }
+
+  /**
+   * For logging errors during rendering without crashing the render. If your fetch, setContext,
+   * render, or renderVariation functions throw, the error will be logged but the page render will
+   * continue. You generally do not need to use this function, just throw when appropriate.
+   */
+  logError (e: Error) {
+    this.hadError = true
+    this.parent?.passError(e, this.path)
+  }
+
+  // helper function for recursively passing the error up until it reaches the page
+  protected passError (e: Error, path: string) {
+    this.parent?.passError(e, path)
+  }
+
+  /**
+   * During rendering, each component should determine the CSS blocks that it needs. This may
+   * change depending on the data. For instance, if you need some CSS to style up an image, but
+   * only when the editor uploaded an image, you can check whether the image is present during
+   * the execution of this function.
+   *
+   * This is evaluated after the fetch and context phases but before the rendering phase. If you
+   * need any async data to make this determination, be sure to fetch it during the fetch phase.
+   */
+  cssBlocks (): string[] {
+    return (this.constructor as any).cssBlocks().keys()
+  }
+
+  /**
+   * Same as cssBlocks() but for javascript.
+   */
+  jsBlocks (): string[] {
+    return (this.constructor as any).jsBlocks().keys()
+  }
+}
+
+export interface PageRecord<DataType extends PageData = PageData> {
+  id: string
+  linkId: string
+  path: string
+  data: DataType
+}
+
+export interface PageWithAncestors<DataType extends PageData = PageData> extends PageRecord<DataType> {
+  ancestors: PageRecord<PageData>[]
+}
+
+export interface ComponentData {
+  templateKey: string
+  areas: Record<string, ComponentData[]>
+}
+
+export interface PageData extends ComponentData {
+  savedAtVersion: Date
+}
+
+export interface ContextBase {
+  /**
+   * For accessibility, every component should consider whether it is creating headers
+   * using h1-h6 tags, and set the context for its children so that they will use the
+   * next higher number. For example, a page component might use h1 for the page title,
+   * in which case it should set headerLevel: 2 so that its child components will use
+   * h2 next. Those components in turn can increment headerLevel for their children.
+   *
+   * This way every page will have a perfect header tree and avoid complaints from WAVE.
+   */
+  headerLevel: number
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './component'
+export * from './links'
+export * from './page'
+export * from './provider'
+export * from './template'

package/src/links.ts

@@ -0,0 +1,72 @@
+/**
+ * This is what an AssetLink should look like when stored in component data. It includes
+ * lots of information so if the asset gets moved or recreated it may be possible to find
+ * the link target anyway.
+ */
+export interface AssetLink {
+  type: 'asset'
+  source: string
+  id: string // the asset's dataId
+  siteId: string
+  path: string
+  checksum: string
+}
+
+/**
+ * Some components (e.g. document list) can point at a folder instead of individual
+ * assets, so we will want to track asset folders through moves, renames, and copies.
+ * This link format supports all that.
+ */
+export interface AssetFolderLink {
+  type: 'assetfolder'
+  id: string // the asset folder's guid
+  siteId: string
+  path: string
+}
+
+/**
+ * A page link always points at the same pagetree as the page the link is on.
+ */
+export interface PageLink {
+  type: 'page'
+  linkId: string
+  siteId: string
+  path: string
+}
+
+/**
+ * The link format for external webpages. This format seems a little extra since
+ * it's just a URL string. Why does it need to be an object with a type? However,
+ * components will often simply ask editors for a link, which could be a page, asset,
+ * or external URL. Having them all in the same object format makes interpreting
+ * the data a lot easier.
+ */
+export interface WebLink {
+  type: 'url'
+  url: string
+}
+
+/**
+ * Many components will point at data records. That's the whole idea. Site id is
+ * required for all data links, it just might be null when the data being pointed at is
+ * global data.
+ */
+export interface DataLink {
+  type: 'data'
+  id: string // the data item's dataId
+  siteId: string|null // null if global data
+  path: string
+}
+
+/**
+ * Just like with asset folders, we may have components that point at data folders. We
+ * would like to keep the links working through moves, renames, and copies.
+ */
+export interface DataFolderLink {
+  type: 'datafolder'
+  id: string // the asset folder's guid
+  siteId?: string // null if global data
+  path: string
+}
+
+export type LinkDefinition = AssetLink | AssetFolderLink | PageLink | WebLink | DataLink | DataFolderLink

package/src/page.ts

@@ -0,0 +1,23 @@
+import { PageData, ContextBase, Component, PageRecord, PageWithAncestors } from './component'
+
+export abstract class Page<DataType extends PageData = any, FetchedType = any, RenderContextType extends ContextBase = any> extends Component<DataType, FetchedType, RenderContextType> {
+  pagePath: string
+  ancestors: PageRecord[]
+
+  /**
+   * we will fill this before rendering, stuff that dosgato knows needs to be added to
+   * the <head> element
+   * the page's render function must include it
+   */
+  headContent!: string
+
+  protected passError (e: Error, path: string) {
+    console.warn(`Recoverable issue occured during render of ${this.pagePath}. Component at ${path} threw the following error:`, e)
+  }
+
+  constructor (page: PageWithAncestors<DataType>) {
+    super(page.data, '/', undefined)
+    this.pagePath = page.path
+    this.ancestors = page.ancestors
+  }
+}

package/src/provider.ts

@@ -0,0 +1,72 @@
+/* eslint-disable @typescript-eslint/no-extraneous-class */
+
+/**
+ * This class is a parent class for Component, but it can also be used as a standalone
+ * if you are creating a set of templates with shared resources. This will be fairly
+ * typical for each entity running an instance and creating their own local templates. You'll
+ * probably want one place to set up very common resources like fontawesome or jquery, instead
+ * of having each and every component template provide them again and again.
+ *
+ * If you do this, don't forget to register the provider along with your templates!
+ */
+export abstract class ResourceProvider {
+  /**
+   * Each template should provide a map of CSS blocks where the map key is the unique name for
+   * the CSS and the value is the CSS itself. For instance, if a template needs CSS from a
+   * standard library like jquery-ui, it could include the full CSS for jquery-ui with 'jquery-ui'
+   * as the key. Other templates that depend on jquery-ui would also provide the CSS, but
+   * a page with both components would only include the CSS once, because they both called it
+   * 'jquery-ui'.
+   *
+   * A version string (e.g. '1.2.5') may be provided for each block. The block with the highest
+   * version number of any given name will be used. Other versions of that name will be ignored.
+   *
+   * For convenience you can either provide the `css` property with the CSS as a string, or the
+   * `path` property with the full server path to a CSS file (node's __dirname function will
+   * help you determine it). You MUST provide one or the other.
+   */
+  static cssBlocks: Map<string, { css?: string, path?: string, version?: string }> = new Map()
+
+  /**
+   * Same as cssBlocks() but for javascript.
+   */
+  static jsBlocks: Map<string, { js?: string, path?: string, version?: string }> = new Map()
+
+  /**
+   * If your template needs to serve any files, like fonts or images, you can provide
+   * a filesystem path in this static property and the files will be served by the rendering
+   * server. Use the provided `webpaths` map to obtain the proper resource URLs. They will be
+   * available as soon as your template has been registered to the rendering server's templateRegistry.
+   *
+   * Typically you will set this to something like `${__dirname}/static` so that the path will be relative
+   * to where you are writing your template class.
+   *
+   * The map name you pick should be globally unique and only collide with other templates as
+   * intended. For instance, the fontawesome font only needs to be provided once, even though
+   * several templates might depend on it. Setting the name as 'fontawesome5' on all three
+   * templates would ensure that the file would only be served once. Including the major version
+   * number is a good idea only if the major versions can coexist.
+   *
+   * Include a version number if applicable for the file you've included with your source. If
+   * multiple templates have a common file, the one that provides the highest version number will
+   * have its file served, while the others will be ignored.
+   *
+   * DO NOT change the mime type without changing the name. Other templates could end up with
+   * the wrong file extension.
+   */
+  static files: Map<string, { path: string, version?: string, mime: string }> = new Map()
+
+  /**
+   * Template code will need to generate HTML and CSS that points at the static files
+   * provided above. In order to do so, we need information from the template registry (since
+   * we have to deduplicate with other registered templates at startup time).
+   *
+   * In order to avoid an ES6 dependency on the registry, we will have the registry write
+   * back to this map as templates are registered.
+   *
+   * Now when a template needs a web path to a resource to put into its HTML, it can do
+   * `<img src="${TemplateClass.webpath('keyname')}">`
+   */
+  static webpaths: Map<string, string> = new Map()
+  static webpath (name: string) { return this.webpaths.get(name) }
+}

package/src/template.ts

@@ -0,0 +1,88 @@
+import { PageWithAncestors, ComponentData } from './component'
+import { LinkDefinition } from './links'
+
+export type TemplateType = 'page'|'component'|'data'
+
+/**
+ * This interface lays out the structure the API needs for each template in the system.
+ */
+export interface Template {
+  type: TemplateType
+
+  /**
+   * A unique string to globally identify this template across installations. Namespacing like
+   * edu.txstate.RichTextEditor could be useful but no special format is required.
+   */
+  templateKey: string
+
+  /**
+   * Each template must declare its areas and the template keys of components that will be
+   * permitted inside each area. The list of allowed component templates can be updated beyond
+   * the list provided here. See templateRegistry.addAvailableComponent's comment for info on why.
+   */
+  areas: Record<string, string[]>
+
+  /**
+   * Each template must provide a list of migrations for upgrading the data schema over time.
+   * Typically this will start as an empty array and migrations will be added as the template
+   * gets refactored.
+   */
+  migrations: Migration[]
+
+  /**
+   * Each template must provide a function that returns links from its data so that they
+   * can be indexed. Only fields that are links need to be returned. Links inside rich editor
+   * text will be extracted automatically from any text returned by getFulltext (see below)
+   */
+  getLinks: LinkGatheringFn
+
+  /**
+   * Each template must provide the text from any text or rich editor data it possesses, so that
+   * the text can be decomposed into words and indexed for fulltext searches. Any text returned
+   * by this function will also be scanned for links.
+   */
+  getFulltext: FulltextGatheringFn
+
+  /**
+   * Each template must provide a validation function so that the API can enforce its data is
+   * shaped properly. If there are no issues, it should return an empty object {}, otherwise it
+   * should return an object with keys that reference the path to the error and values that
+   * are an array of error messages pertaining to that path.
+   *
+   * For instance, if name is required and the user didn't provide one, you would return:
+   * { name: ['A name is required.'] }
+   *
+   * This method is async so that you can do things like look in the database for conflicting
+   * names.
+   */
+  validate: (data: any) => Promise<Record<string, string[]>>
+}
+
+/**
+ * In dosgato CMS, the data in the database is not altered except during user activity. This
+ * means that older records could have been saved when the schema expected by component
+ * rendering code was different than the date it's being rendered. To handle this, each
+ * page and component template is required to provide migrations responsible for
+ * transforming the data to the needed schema version.
+ *
+ * In order to support backwards compatibility, each API client will specify the date
+ * when the code was written, so that their assumptions about the schema will be
+ * frozen in time. This system means that migrations need to run backward as well as forward
+ * in time.
+ *
+ * The `up` method is for changing data from an older schema to a newer one. The
+ * `down` method is for changing data back from the newer schema to the older one.
+ * If a `down` method cannot be provided, the migration is considered to be a breaking
+ * change and anyone asking to rewind time to before the migration will receive an error.
+ *
+ * Your `up` and `down` methods will be applied to components in bottom-up fashion, so you
+ * can assume that any components inside one of your areas has already been processed.
+ */
+export interface Migration {
+  createdAt: Date
+  up: (data: ComponentData, page: PageWithAncestors) => ComponentData|Promise<ComponentData>
+  down: (data: ComponentData, page: PageWithAncestors) => ComponentData|Promise<ComponentData>
+}
+
+export type LinkGatheringFn = (data: any) => LinkDefinition[]
+export type FulltextGatheringFn = (data: any) => string[]

package/tsconfig.eslint.json

@@ -0,0 +1,7 @@
+{
+  "extends": "./tsconfig.json",
+  "include": [
+    "src/**/*.ts",
+    "test/**/*.ts"
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "es2019",
+    "module": "commonjs",
+    "declaration": true,
+    "outDir": "./dist",
+    "strict": true,
+    "esModuleInterop": true
+  },
+  "include": ["src"]
+}