@dosgato/templating 0.0.22 → 0.0.23

package/dist/component.d.ts

@@ -1,6 +1,6 @@
 import { EditBarOpts } from './editbar.js';
-import { LinkDefinition } from './links.js';
 import { ResourceProvider } from './provider.js';
+import { APIClient } from './render.js';
 /**
  * This is the primary templating class to build your templates. Subclass it and provide
  * at least a render function.
@@ -20,28 +20,48 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
     page?: Page;
     hadError: boolean;
     /**
-     * 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.
+     * 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
+     * some useful methods there like processRich to help you convert links in rich text
+     * strings.
+     *
+     * Do NOT mutate data received from the API as it may be cached and given to other
+     * Component instances that run the same type of query.
      */
-    resolveLink: (link: string | LinkDefinition, absolute?: boolean) => Promise<string>;
+    api: APIClient;
     /**
-     * This function will be provided by the rendering server and should be used inside your fetch
-     * method to prepare editor-provided HTML for rendering. It will do things like find and resolve
-     * link definitions in the internal dosgato format and clean up tags that were accidentally left
-     * open to protect overall page integrity.
+     * 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.
      */
-    processRich: (text: string) => Promise<string>;
+    getRootPageData: () => Promise<PageData>;
+    /**
+     * Retrieve the data for all ancestor pages 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.
+     */
+    getAncestorPageData: () => Promise<PageData[]>;
     /**
      * 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.
+     * 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))`
      */
     fetch(editMode: boolean): Promise<FetchedType>;
     /**
@@ -156,6 +176,10 @@ export interface ComponentData {
 export interface PageData extends ComponentData {
     savedAtVersion: Date;
 }
+export interface DataData {
+    templateKey: string;
+    savedAtVersion: Date;
+}
 export interface ContextBase {
     /**
      * For accessibility, every component should consider whether it is creating headers

package/dist/component.js

@@ -33,10 +33,13 @@ export class Component extends ResourceProvider {
      * 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.
+     * 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))`
      */
     async fetch(editMode) {
         return undefined;

package/dist/render.d.ts

@@ -1,5 +1,83 @@
-import { ContextBase } from './component.js';
+import { ContextBase, DataData, PageData } 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): {
     headerLevel: number;
 };
+export interface PictureResize {
+    /** the width of this particular resize */
+    width: number;
+    /** the URL to this particular resize, relative or absolute depends on options used */
+    src: string;
+}
+export interface PictureAttributes {
+    /** string appropriate for the src attribute of the default <img> tag */
+    src: string;
+    /** string appropriate for the srcset attribute of the default <img> tag, or use widths array to reconstruct */
+    srcset: string;
+    /** a list of available widths in case you want to filter some out and recreate the srcset */
+    widths: PictureResize[];
+    /** alternative text stored with the image in its asset repository, may be overridden by local alt text */
+    alt?: string;
+    /** the original intrinsic width of the image uploaded by the editor */
+    width: number;
+    /** the original intrinsic height of the image uploaded by the editor */
+    height: number;
+    /** a list of alternate formats like AVIF or WEBP and their resizes, useful for creating <source> tags */
+    alternates: {
+        /** the mime type of this alternate source, useful for the type attribute on a <source> tag */
+        mime: string;
+        /** the full srcset for the <source> tag, or use widths array to reconstruct */
+        srcset: string;
+        /** a list of available widths in case you want to filter some out and recreate the srcset */
+        widths: PictureResize[];
+    }[];
+}
+export interface APIClient {
+    /**
+     * Run any query against the API.
+     *
+     * Will be authenticated as appropriate - anonymous during published renders, as the editor
+     * during preview renders.
+     */
+    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,
+     * 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.
+     */
+    resolveLink: (link: string | LinkDefinition, absolute?: boolean) => Promise<string>;
+    /**
+     * This function will be provided by the rendering server and should be used inside your fetch
+     * method to prepare editor-provided HTML for rendering. It will do things like find and resolve
+     * link definitions in the internal dosgato format and clean up tags that were accidentally left
+     * open to protect overall page integrity.
+     */
+    processRich: (text: string) => Promise<string>;
+    /**
+     * This function will retrieve information about an image to help you construct responsive HTML
+     * for a <picture> element including the <img> and all <source> tags.
+     *
+     * 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).
+     */
+    getImgAttributes: (link: string | AssetLink, absolute?: boolean) => Promise<PictureAttributes>;
+    /** Get the data for a specific page. Will be dataloaded. */
+    getPageData: ({ id, path }: {
+        id?: string;
+        path?: string;
+    }) => Promise<PageData>;
+    /**
+     * Get data items
+     *
+     * 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.
+     */
+    getDataByPath: (templateKey: string, path: string) => Promise<DataData[]>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dosgato/templating",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "description": "A library to support building templates for dosgato CMS.",
   "type": "module",
   "exports": {