@dosgato/templating 0.0.39 → 0.0.42

package/dist/apitemplate.d.ts

@@ -188,11 +188,6 @@ export declare type AnyMigration = ComponentMigration | PageMigration | DataMigr
 export declare type LinkGatheringFn = (data: any) => LinkDefinition[];
 export declare type FulltextGatheringFn = (data: any) => string[];
 export declare type GraphQLQueryFn = <T>(query: string, variables?: any) => Promise<T>;
-/**
- * This function is used by API template definitions to help them identify links inside large blocks
- * of text and return them for indexing.
- */
-export declare function extractLinksFromText(text: string | undefined): LinkDefinition[];
 /**
  * This function is used by API template definitions to help them identify all the searchable
  * words in a large block of text and return them for indexing.

package/dist/apitemplate.js

@@ -5,16 +5,6 @@ export var ValidationMessageType;
     ValidationMessageType["WARNING"] = "warning";
     ValidationMessageType["SUCCESS"] = "success";
 })(ValidationMessageType || (ValidationMessageType = {}));
-/**
- * This function is used by API template definitions to help them identify links inside large blocks
- * of text and return them for indexing.
- */
-export function extractLinksFromText(text) {
-    if (!text)
-        return [];
-    const matches = text.matchAll(/{.*"type"\s?:\s+"\w+".*?}/gi);
-    return Array.from(matches).map(m => JSON.parse(m[0]));
-}
 /**
  * This function is used by API template definitions to help them identify all the searchable
  * words in a large block of text and return them for indexing.

package/dist/component.d.ts

@@ -1,4 +1,3 @@
-import { EditBarOpts } from './editbar.js';
 import { ResourceProvider } from './provider.js';
 import { APIClient } from './render.js';
 /**
@@ -9,22 +8,10 @@ import { APIClient } from './render.js';
  * parent and child components linked.
  */
 export declare abstract class Component<DataType extends ComponentData = any, FetchedType = any, RenderContextType extends ContextBase = any> extends ResourceProvider {
-    static templateKey: string;
-    static templateName: string;
-    areas: Map<string, Component<any, any, any>[]>;
-    data: Omit<DataType, 'areas'>;
-    fetched: FetchedType;
-    renderCtx: RenderContextType;
-    path: string;
-    parent?: Component;
-    page?: Page;
-    hadError: boolean;
     /**
-     * This property will be set during page render and you may refer to it at any time to
-     * determine whether you are doing your work in edit mode or regular rendering mode.
-     * The editBar and newBar methods will automatically use it to blank out the editing UI.
+     * Provide this when you create a template to identify what you are defining.
      */
-    editMode: boolean;
+    static templateKey: string;
     /**
      * The rendering server will provide an instance of the APIClient interface so that
      * you can run any API GraphQL query you like in your `fetch` function. There are also
@@ -36,25 +23,23 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      */
     api: APIClient;
     /**
-     * Retrieve the data for the root page of the page this component is on. Useful for
-     * implementing inheritance schemes.
-     *
-     * This function will be provided by the rendering service.
-     *
-     * Do NOT mutate the data returned by this function, as it may be cached and given to
-     * other Component instances.
+     * This property will be set during page render and you may refer to it at any time to
+     * determine whether you are doing your work in edit mode or regular rendering mode.
+     * The editBar and newBar methods will automatically use it to blank out the editing UI.
      */
-    getRootPageData: () => Promise<PageData>;
+    editMode: boolean;
     /**
-     * Retrieve the data for all ancestor pages of the page this component is on. Useful
-     * for implementing inheritance schemes.
+     * When hydrating an inherited component, the renderer will set this to the id of the page it
+     * came from. You may use this information in any of the phases to alter your behavior if needed.
      *
-     * This function will be provided by the rendering service.
+     * For instance, you may decide that your fetch function needs some extra information from the
+     * originating page instead of the page you're being inherited into (your `this.page` will
+     * be the page currently being rendered, NOT the page the inheritable component came from).
      *
-     * Do NOT mutate the data returned by this function, as it may be cached and given to
-     * other Component instances.
+     * This property is also used to alter the edit bar. Inherited components may never be edited
+     * except on their original page, so the edit bar will render with a link to the original page.
      */
-    getAncestorPageData: () => Promise<PageData[]>;
+    inheritedFrom?: string;
     /**
      * 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
@@ -64,12 +49,27 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      * Place any needed data into the return object, and it will be available to you as `this.fetched`
      * during the rendering phase.
      *
-     * Note that this.page will be available, and getRootPageData and getAncestorPageData are
-     * available in case there is a need for inheritance. If you need to inherit entire components,
-     * you may add them to your this.areas map, e.g.
-     * `this.areas.get('myarea').push(new Component(inheritedData, this.path + '/myarea/inherit1', this))`
+     * Note that `this.page` will be available, and `this.api` has dataloaded methods for retrieving
+     * data from the API if, for instance, you need to inherit information from a parent or root
+     * page. If you need to inherit and render entire components from ancestor pages,
+     * you must register them. See the comment for `this.registerInherited`
+     *
+     * Try to minimize the number of round trips you make here, make use of Promise.all and such;
+     * remember that the api functions are mostly dataloaded so calling them simultaneously is
+     * advantageous where possible.
      */
     fetch(): Promise<FetchedType>;
+    /**
+     * Some components may be inheritable to subpages within the same site. For instance, a site's
+     * social media links may appear on every page's footer. To accomplish this in your template,
+     * you need to fetch ancestor page data in your fetch phase, identify the component data you want
+     * to inherit, and then call this function within your fetch to let the renderer know it needs to
+     * process those components (hydrate them, call their fetch functions, and include them in the render).
+     *
+     * The inherited components will be added to the appropriate area's array in the renderedAreas
+     * parameter of your render function.
+     */
+    registerInherited: (area: string, components: ComponentData[], top?: true) => void;
     /**
      * The second phase of rendering a component is the context phase. This step is TOP-DOWN and
      * NON-MUTATING. Each component will receive the parent component's context and then pass a
@@ -92,7 +92,7 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      * 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[]>): string;
+    abstract render(renderedAreas: Map<string, RenderedComponent[]>): 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
@@ -106,14 +106,9 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      * will be skipped.
      */
     renderVariation(extension: string, renderedAreas: Map<string, string>): string;
-    constructor(data: DataType, path: string, parent: Component | undefined, editMode: boolean);
-    /**
-     * 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): void;
-    protected passError(e: Error, path: string): void;
+    renderComponents(components?: RenderedComponent[], opts?: {
+        hideInheritBars?: boolean;
+    }): string;
     /**
      * 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
@@ -122,6 +117,8 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      *
      * 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.
+     *
+     * You should check `this.editMode` if you need to load CSS that alters edit bars.
      */
     cssBlocks(): string[];
     /**
@@ -130,11 +127,11 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
     jsBlocks(): string[];
     /**
      * Components may override this function to give their edit bars a custom
-     * label instead of using the templateName property
+     * label instead of using the template name
      *
      * For instance, you could return this.data.title
      */
-    editLabel(): string;
+    editLabel(): undefined;
     /**
      * Components may override this function to give their edit bars a custom
      * CSS class
@@ -147,7 +144,7 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      * For instance, an area that only accepts 'layout' components could
      * return "Add Layout"
      */
-    newLabel(areaName: string): string;
+    newLabel(areaName: string): undefined;
     /**
      * Components may override this function to give their new bars a custom
      * CSS class
@@ -165,6 +162,31 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      * Generally should not be overridden - override newLabel and newClass instead
      */
     newBar(areaName: string, opts?: EditBarOpts): string;
+    /**
+     * These functions will be provided by the rendering server to assist in the
+     * rendering process.
+     */
+    static editBar: (path: string, opts: EditBarOpts) => string;
+    static newBar: (path: string, opts: EditBarOpts) => string;
+    static repairHTML: (html: string) => string;
+    constructor(data: DataType, path: string, parent: Component | undefined, editMode: boolean);
+    areas: Map<string, Component<any, any, any>[]>;
+    data: Omit<DataType, 'areas'>;
+    fetched: FetchedType;
+    renderCtx: RenderContextType;
+    path: string;
+    parent?: Component;
+    page?: Page;
+    hadError: boolean;
+    autoLabel: string;
+    autoNewLabel: string;
+    /**
+     * 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): void;
+    protected passError(e: Error, path: string): void;
 }
 export interface PageRecord<DataType extends PageData = PageData> {
     id: string;
@@ -195,12 +217,31 @@ export interface ContextBase {
      */
     headerLevel: number;
 }
+export interface EditBarOpts {
+    extraClass?: string;
+    label?: string;
+    editMode?: boolean;
+    inheritedFrom?: string;
+}
+export interface RenderedComponent<C extends Component = Component> {
+    component: C;
+    html: string;
+}
 export declare abstract class Page<DataType extends PageData = any, FetchedType = any, RenderContextType extends ContextBase = any> extends Component<DataType, FetchedType, RenderContextType> {
     pagePath: string;
     /**
-     * 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
+     * This will be filled by the rendering server. The template properties are described
+     * over in apitemplate.ts in the comment for APIPageTemplate.templateProperties.
+     *
+     * The properties will appear in the GraphQL API and the rendering server will automatically
+     * download them and provide them here so all you need to do as a template developer is
+     * reference the values in your fetch/setContext/render functions.
+     */
+    templateProperties: any;
+    /**
+     * This is a bunch of javascript and CSS and meta tags managed by the DosGato engine. It will
+     * be filled by the rendering server and your render function for your page template
+     * should place include it in the <head> element
      */
     headContent: string;
     protected passError(e: Error, path: string): void;

package/dist/component.js

@@ -1,5 +1,4 @@
 import { isNotBlank } from 'txstate-utils';
-import { editBar, newBar } from './editbar.js';
 import { ResourceProvider } from './provider.js';
 /**
  * This is the primary templating class to build your templates. Subclass it and provide
@@ -13,9 +12,9 @@ export class Component extends ResourceProvider {
     // a Component will also construct/hydrate all its child components
     constructor(data, path, parent, editMode) {
         super();
-        // properties for use during hydration, you do not have to provide these when
+        // Properties provided during the rendering process. You do not have to provide these when
         // building a template, but you can use them in the functions you do provide
-        this.areas = new Map();
+        this.areas = new Map(); // a Map of area names and the array of hydrated components in each
         this.editMode = editMode;
         this.parent = parent;
         const { areas, ...ownData } = data;
@@ -38,10 +37,14 @@ export class Component extends ResourceProvider {
      * Place any needed data into the return object, and it will be available to you as `this.fetched`
      * during the rendering phase.
      *
-     * Note that this.page will be available, and getRootPageData and getAncestorPageData are
-     * available in case there is a need for inheritance. If you need to inherit entire components,
-     * you may add them to your this.areas map, e.g.
-     * `this.areas.get('myarea').push(new Component(inheritedData, this.path + '/myarea/inherit1', this))`
+     * Note that `this.page` will be available, and `this.api` has dataloaded methods for retrieving
+     * data from the API if, for instance, you need to inherit information from a parent or root
+     * page. If you need to inherit and render entire components from ancestor pages,
+     * you must register them. See the comment for `this.registerInherited`
+     *
+     * Try to minimize the number of round trips you make here, make use of Promise.all and such;
+     * remember that the api functions are mostly dataloaded so calling them simultaneously is
+     * advantageous where possible.
      */
     async fetch() {
         return undefined;
@@ -79,18 +82,10 @@ export class Component extends ResourceProvider {
     renderVariation(extension, renderedAreas) {
         return Array.from(renderedAreas.values()).join('');
     }
-    /**
-     * 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) {
-        this.hadError = true;
-        this.passError(e, this.path);
-    }
-    // helper function for recursively passing the error up until it reaches the page
-    passError(e, path) {
-        this.parent?.passError(e, path);
+    // helper function to help you print an area, but you can also override this if you
+    // need to do something advanced like wrap each component in a div
+    renderComponents(components = [], opts) {
+        return components.flatMap(c => c.component.inheritedFrom && opts?.hideInheritBars ? [c.html] : [c.component.editBar(), c.html]).join('');
     }
     /**
      * During rendering, each component should determine the CSS blocks that it needs. This may
@@ -100,6 +95,8 @@ export class Component extends ResourceProvider {
      *
      * 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.
+     *
+     * You should check `this.editMode` if you need to load CSS that alters edit bars.
      */
     cssBlocks() {
         return Array.from(this.constructor.cssBlocks.keys());
@@ -112,21 +109,16 @@ export class Component extends ResourceProvider {
     }
     /**
      * Components may override this function to give their edit bars a custom
-     * label instead of using the templateName property
+     * label instead of using the template name
      *
      * For instance, you could return this.data.title
      */
-    editLabel() {
-        const This = this.constructor;
-        return This.templateName;
-    }
+    editLabel() { return undefined; }
     /**
      * Components may override this function to give their edit bars a custom
      * CSS class
      */
-    editClass() {
-        return undefined;
-    }
+    editClass() { return undefined; }
     /**
      * Components may override this function to give their new bars a custom
      * label
@@ -134,26 +126,23 @@ export class Component extends ResourceProvider {
      * For instance, an area that only accepts 'layout' components could
      * return "Add Layout"
      */
-    newLabel(areaName) {
-        return 'Add Content';
-    }
+    newLabel(areaName) { return undefined; }
     /**
      * Components may override this function to give their new bars a custom
      * CSS class
      */
-    newClass(areaName) {
-        return undefined;
-    }
+    newClass(areaName) { return undefined; }
     /**
      * Components may override this function to provide a custom edit bar
      *
      * Generally should not be overridden - override editLabel and editClass instead
      */
     editBar(opts = {}) {
-        opts.label ?? (opts.label = this.editLabel());
+        opts.label ?? (opts.label = this.editLabel() ?? this.autoLabel);
         opts.extraClass ?? (opts.extraClass = this.editClass());
-        opts.editMode = this.editMode;
-        return editBar(this.path, opts);
+        opts.editMode ?? (opts.editMode = this.editMode);
+        opts.inheritedFrom ?? (opts.inheritedFrom = this.inheritedFrom);
+        return Component.editBar(this.path, opts);
     }
     /**
      * Components may override this function to provide a custom new bar
@@ -161,10 +150,24 @@ export class Component extends ResourceProvider {
      * Generally should not be overridden - override newLabel and newClass instead
      */
     newBar(areaName, opts = {}) {
-        opts.label ?? (opts.label = this.newLabel(areaName));
+        opts.label ?? (opts.label = this.newLabel(areaName) ?? this.autoNewLabel);
         opts.extraClass ?? (opts.extraClass = this.newClass(areaName));
-        opts.editMode = this.editMode;
-        return newBar([this.path, 'areas', areaName].filter(isNotBlank).join('.'), opts);
+        opts.editMode ?? (opts.editMode = this.editMode);
+        opts.inheritedFrom ?? (opts.inheritedFrom = this.inheritedFrom);
+        return Component.newBar([this.path, 'areas', areaName].filter(isNotBlank).join('.'), opts);
+    }
+    /**
+     * 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) {
+        this.hadError = true;
+        this.passError(e, this.path);
+    }
+    // helper function for recursively passing the error up until it reaches the page
+    passError(e, path) {
+        this.parent?.passError(e, path);
     }
 }
 export class Page extends Component {

package/dist/links.d.ts

@@ -63,3 +63,13 @@ export interface DataFolderLink {
     path: string;
 }
 export declare type LinkDefinition = AssetLink | AssetFolderLink | PageLink | WebLink | DataLink | DataFolderLink;
+/**
+ * This function is used by template definitions to help them identify links inside large blocks
+ * of text and return them for indexing, and by render definitions to help replace them with the actual URLs
+ */
+export declare function extractLinksFromText(text: string | undefined): LinkDefinition[];
+/**
+ * This function is used by render definitions to replace links in large blocks with the actual
+ * URLs they point to at render time.
+ */
+export declare function replaceLinksInText(text: string, resolved: Map<string, string>): string;

package/dist/links.js

@@ -1 +1,19 @@
-export {};
+const LinkRegex = /{.*"type"\s?:\s+"\w+".*?}/g;
+/**
+ * This function is used by template definitions to help them identify links inside large blocks
+ * of text and return them for indexing, and by render definitions to help replace them with the actual URLs
+ */
+export function extractLinksFromText(text) {
+    if (!text)
+        return [];
+    const matches = text.matchAll(LinkRegex);
+    return Array.from(matches).map(m => JSON.parse(m[0]));
+}
+/**
+ * This function is used by render definitions to replace links in large blocks with the actual
+ * URLs they point to at render time.
+ */
+export function replaceLinksInText(text, resolved) {
+    // TODO: figure out a broken link to use instead of '#', so it can be detected later
+    return text.replace(LinkRegex, m => resolved.get(m) ?? '#');
+}

package/dist/render.d.ts

@@ -1,4 +1,4 @@
-import { ContextBase, DataData, PageData } from './component.js';
+import { ContextBase, DataData, PageData, PageRecord } from './component.js';
 import { AssetLink, DataFolderLink, DataLink, LinkDefinition } from './links.js';
 export declare function printHeader(ctx: ContextBase, content: string): string;
 export declare function advanceHeader(ctx: ContextBase, content?: string): {
@@ -42,7 +42,7 @@ export interface APIClient {
      */
     query: <T = any>(query: string, variables?: any) => Promise<T>;
     /**
-     * This function will be provided by the rendering server and should be used inside your fetch,
+     * This function will be provided by the rendering server and should be used inside your fetch
      * method to convert a link, as input by a user, into a URL suitable for an href, or optionally
      * an absolute URL suitable for a backend http request or non-HTML document like an RSS feed.
      */
@@ -61,23 +61,40 @@ export interface APIClient {
      * The alt text it returns will be the default alternative text from the asset repository. Alt
      * text gathered from a template's dialog should generally take precedence (though the dialog may
      * preload the alt text field with the asset repository default).
+     *
+     * Will be dataloaded.
      */
     getImgAttributes: (link: string | AssetLink, absolute?: boolean) => Promise<PictureAttributes>;
-    /** Get the data for a specific page. Will be dataloaded. */
+    /** Get the data for a specific page.
+     *
+     * Will be dataloaded.
+     */
     getPageData: ({ id, path }: {
         id?: string;
         path?: string;
     }) => Promise<PageData>;
+    /** Get all ancestor pages of a specific page. First array element will be the pagetree root page. */
+    getAncestors: ({ id, path }: {
+        id?: string;
+        path?: string;
+    }) => Promise<PageRecord[]>;
+    /** Get the pagetree root page from which the specified page descends. */
+    getRootPageData: ({ id, path }: {
+        id?: string;
+        path?: string;
+    }) => Promise<PageData>;
     /**
-     * Get data items
+     * Get data entries by link or folder link
      *
      * Returns an array in case link is a DataFolderLink. If link is a DataLink, will return an
      * array with length <= 1.
      */
     getDataByLink: (link: string | DataLink | DataFolderLink) => Promise<DataData[]>;
     /**
-     * Get data by full path including site. Use '/global' for global data. If path refers
-     * to a specific data item, will return an array with length <= 1.
+     * Get data entries by full path including site
+     *
+     * Use '/global' for global data. If path refers to a specific data item, will return
+     * an array with length <= 1.
      */
     getDataByPath: (templateKey: string, path: string) => Promise<DataData[]>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dosgato/templating",
-  "version": "0.0.39",
+  "version": "0.0.42",
   "description": "A library to support building templates for dosgato CMS.",
   "type": "module",
   "exports": {
@@ -15,10 +15,10 @@
   "dependencies": {
     "@iconify/svelte": "^2.2.1",
     "svelte": "^3.48.0",
-    "txstate-utils": "^1.7.1"
+    "txstate-utils": "^1.7.4"
   },
   "devDependencies": {
-    "eslint-config-standard-with-typescript": "^21.0.1",
+    "eslint-config-standard-with-typescript": "^22.0.0",
     "typescript": "^4.4.2"
   },
   "repository": {

package/dist/editbar.d.ts

@@ -1,11 +0,0 @@
-export interface EditBarOpts {
-    extraClass?: string;
-    label?: string;
-    editMode?: boolean;
-}
-export declare function editBar(path: string, opts: EditBarOpts & {
-    label: string;
-}): string;
-export declare function newBar(path: string, opts: EditBarOpts & {
-    label: string;
-}): string;

package/dist/editbar.js

@@ -1,23 +0,0 @@
-import { htmlEncode, randomid } from 'txstate-utils';
-export function editBar(path, opts) {
-    if (!opts.editMode)
-        return '';
-    const id = randomid();
-    return `
-<div class="dg-edit-bar ${opts.extraClass ?? ''}" data-path="${htmlEncode(path)}" draggable="true" ondragstart="window.dgEditing.drag(event)" ondragover="window.dgEditing.over(event)" ondragend="window.dgEditing.drop(event)">
-  <span id="${id}" class="dg-edit-bar-label">${htmlEncode(opts.label)}</span>
-  <button onclick="window.dgEditing.edit(event)" aria-describedby="${id}">Edit</button>
-  <button onclick="window.dgEditing.move(event)" aria-describedby="${id}">Move</button>
-  <button onclick="window.dgEditing.del(event)" aria-describedby="${id}">Trash</button>
-</div>
-  `.trim();
-}
-export function newBar(path, opts) {
-    if (!opts.editMode)
-        return '';
-    return `
-<div role="button" onclick="window.dgEditing.create(event)" class="dg-new-bar ${opts.extraClass ?? ''}" data-path="${htmlEncode(path)}">
-  ${htmlEncode(opts.label)}
-</div>
-  `.trim();
-}