@dosgato/templating - npm Package Compare versions

Comparing version 0.0.41 to 0.0.42

dist/apitemplate.d.ts

@@ -192,7 +192,2 @@ import { ComponentData, DataData, PageData } from './component.js';
 /**
- * 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
@@ -199,0 +194,0 @@ * words in a large block of text and return them for indexing.

dist/apitemplate.js

@@ -9,12 +9,2 @@ import { stopwords } from './stopwords.js';
 /**
- * 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
@@ -21,0 +11,0 @@ * words in a large block of text and return them for indexing.

dist/component.d.ts

@@ -16,35 +16,2 @@ import { ResourceProvider } from './provider.js';
     /**
-     * These functions will be provided by the rendering server
-     */
-    static editBar: (path: string, opts: EditBarOpts) => string;
-    static newBar: (path: string, opts: EditBarOpts) => string;
-    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;
-    /**
-     * 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.
-     *
-     * 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).
-     *
-     * 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.
-     */
-    inheritedFrom?: string;
-    /**
-     * 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.
-     */
-    editMode: boolean;
-    /**
      * The rendering server will provide an instance of the APIClient interface so that
@@ -60,29 +27,20 @@ * you can run any API GraphQL query you like in your `fetch` function. There are also
     /**
-     * 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;
     /**
-     * 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 the data in your fetch phase and then call this function within your fetch
-     * to let the renderer know it needs to hydrate them and include them in the render.
-     */
-    registerInherited: (area: string, components: ComponentData[], top?: true) => void;
-    /**
      * The first phase of rendering a component is the fetch phase. Each component may
@@ -96,9 +54,24 @@ * provide a fetch method that looks up data it needs from external sources. This step
      *
-     * 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
@@ -139,10 +112,2 @@ * NON-MUTATING. Each component will receive the parent component's context and then pass a
     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?: {
@@ -159,2 +124,4 @@ hideInheritBars?: boolean;
      * 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.
      */
@@ -203,2 +170,27 @@ cssBlocks(): string[];
     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;
 }
@@ -247,6 +239,15 @@ export interface PageRecord<DataType extends PageData = PageData> {
     /**
-     * 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;
@@ -253,0 +254,0 @@ protected passError(e: Error, path: string): void;

dist/component.js

@@ -15,5 +15,5 @@ import { isNotBlank } from 'txstate-utils';
         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;
@@ -41,6 +41,10 @@ this.parent = parent;
      *
-     * 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.
      */
@@ -83,15 +87,2 @@ async fetch() {
     }
-    /**
-     * 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
@@ -110,2 +101,4 @@ // need to do something advanced like wrap each component in a div
      * 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.
      */
@@ -127,5 +120,3 @@ cssBlocks() {
      */
-    editLabel() {
-        return undefined;
-    }
+    editLabel() { return undefined; }
     /**
@@ -135,5 +126,3 @@ * Components may override this function to give their edit bars a custom
      */
-    editClass() {
-        return undefined;
-    }
+    editClass() { return undefined; }
     /**
@@ -146,5 +135,3 @@ * Components may override this function to give their new bars a custom
      */
-    newLabel(areaName) {
-        return undefined;
-    }
+    newLabel(areaName) { return undefined; }
     /**
@@ -154,5 +141,3 @@ * Components may override this function to give their new bars a custom
      */
-    newClass(areaName) {
-        return undefined;
-    }
+    newClass(areaName) { return undefined; }
     /**
@@ -164,3 +149,3 @@ * Components may override this function to provide a custom edit bar
     editBar(opts = {}) {
-        opts.label ?? (opts.label = this.editLabel() ?? this.autoLabel());
+        opts.label ?? (opts.label = this.editLabel() ?? this.autoLabel);
         opts.extraClass ?? (opts.extraClass = this.editClass());
@@ -177,3 +162,3 @@ opts.editMode ?? (opts.editMode = this.editMode);
     newBar(areaName, opts = {}) {
-        opts.label ?? (opts.label = this.newLabel(areaName) ?? this.autoNewLabel());
+        opts.label ?? (opts.label = this.newLabel(areaName) ?? this.autoNewLabel);
         opts.extraClass ?? (opts.extraClass = this.newClass(areaName));
@@ -184,2 +169,15 @@ opts.editMode ?? (opts.editMode = this.editMode);
     }
+    /**
+     * 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);
+    }
 }
@@ -186,0 +184,0 @@ export class Page extends Component {

dist/links.d.ts

@@ -66,1 +66,11 @@ /**
 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;

dist/links.js

@@ -1,1 +0,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) ?? '#');
+}

dist/render.d.ts

@@ -1,2 +0,2 @@
-import { ContextBase, DataData, PageData } from './component.js';
+import { ContextBase, DataData, PageData, PageRecord } from './component.js';
 import { AssetLink, DataFolderLink, DataLink, LinkDefinition } from './links.js';
@@ -45,3 +45,3 @@ export declare function printHeader(ctx: ContextBase, content: string): string;
     /**
-     * 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
@@ -65,5 +65,10 @@ * an absolute URL suitable for a backend http request or non-HTML document like an RSS feed.
      * 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 }: {
@@ -73,4 +78,14 @@ id?: 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
      *
@@ -82,6 +97,8 @@ * Returns an array in case link is a DataFolderLink. If link is a DataLink, will return an
     /**
-     * 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.json

 {
   "name": "@dosgato/templating",
-  "version": "0.0.41",
+  "version": "0.0.42",
   "description": "A library to support building templates for dosgato CMS.",
@@ -18,3 +18,3 @@ "type": "module",
     "svelte": "^3.48.0",
-    "txstate-utils": "^1.7.1"
+    "txstate-utils": "^1.7.4"
   },
@@ -21,0 +21,0 @@ "devDependencies": {

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

54185

increased by3.97%

Lines of code

1207

increased by2.46%

Dependency changes

• Updatedtxstate-utils@^1.7.4