@dosgato/templating 0.0.94 → 0.0.96

package/dist/apitemplate.d.ts

@@ -185,8 +185,8 @@ export declare type ComponentMigration<DataType extends ComponentData = Componen
 export declare type PageMigration<DataType extends PageData = PageData> = Migration<DataType, PageExtras>;
 export declare type DataMigration<DataType extends DataData = DataData> = Migration<DataType, DataExtras>;
 export declare type AnyMigration = ComponentMigration | PageMigration | DataMigration;
-export declare type LinkGatheringFn<DataType> = (data: DataType) => LinkDefinition[];
-export declare type FulltextGatheringFn<DataType> = (data: DataType) => string[];
+export declare type LinkGatheringFn<DataType> = (data: DataType) => (LinkDefinition | string | undefined)[];
+export declare type FulltextGatheringFn<DataType> = (data: DataType) => (string | undefined)[];
 export declare type GraphQLQueryFn = <T>(query: string, variables?: any) => Promise<T>;
 /**
  * This function is used by API template definitions to help them identify all the searchable

package/dist/component.d.ts

@@ -32,6 +32,12 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      * The editBar and newBar methods will automatically use it to blank out the editing UI.
      */
     editMode: boolean;
+    /**
+     * The extension of the variation currently being rendered.
+     *
+     * See 'renderVariation' and 'variationsToFetch' for more discussion of variations.
+     */
+    extension: 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.
@@ -61,8 +67,29 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      * 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() may be run while rendering a non-HTML variation of a page. If you need to do different
+     * work in those cases, remember this.extension is available.
      */
     fetch(): Promise<FetchedType>;
+    /**
+     * Only run fetch for specific variations.
+     *
+     * Sometimes pages are requested with an alternate extension like .rss or .ics. See 'renderVariation'
+     * method for more discussion on this.
+     *
+     * When rendering variations, many components will not need to fetch anything, because they are not
+     * going to render anything. For instance, if we are rendering an '.ics' variation and this component
+     * is not an event, it will not be participating and we'd like to avoid doing the work in the fetch().
+     *
+     * This variable is an array of extensions where we SHOULD run fetch(). The default is only run fetch
+     * on 'html'. Components that support other variations should override this method and opt in to more
+     * extensions.
+     *
+     * The extensions listed should NOT include the preceding dot. In the case of an extended extension like
+     * '.js.map', you should provide 'js.map'.
+     */
+    static variationsToFetch: 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,
@@ -141,7 +168,7 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      * method to prepare editor-provided HTML for later rendering. It will do things like find and
      * resolve link definitions in the internal dosgato format.
      */
-    fetchRichText: (text: string) => Promise<void>;
+    fetchRichText: (html: string | undefined) => Promise<void>;
     /**
      * This function will be provided by the rendering server and should be used during the render
      * phase to clean up editor-provided HTML. It will do things like clean up tags that were accidentally
@@ -166,7 +193,7 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      * If this.data.title is non-blank, the rich text will be balanced below it, but if it is blank,
      * it will be balanced at the level the title would have had.
      */
-    renderRichText: (html: string, opts?: {
+    renderRichText: (html: string | undefined, opts?: {
         headerLevel?: number;
         advanceHeader?: string;
     }) => string;
@@ -186,6 +213,9 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      * respond, or return empty string if you want your child components to be silent in all
      * cases.
      *
+     * The extension will NOT include the preceding dot. In the case of an extended extension like
+     * '.js.map', you will receive 'js.map'.
+     *
      * This function will be run after the fetch phase. The context and html rendering phases
      * will be skipped.
      */
@@ -272,7 +302,7 @@ export declare abstract class Component<DataType extends ComponentData = any, Fe
      */
     static editBar: (path: string, opts: EditBarOpts) => string;
     static newBar: (path: string, opts: NewBarOpts) => string;
-    constructor(data: DataType, path: string, parent: Component | undefined, editMode: boolean);
+    constructor(data: DataType, path: string, parent: Component | undefined, editMode: boolean, extension: string);
     areas: Map<string, Component<any, any, ContextBase>[]>;
     data: Omit<DataType, 'areas'>;
     fetched: FetchedType;
@@ -385,6 +415,10 @@ export interface RenderComponentsWrapParams {
      *
      * If you use this, make sure to also use the bar parameter or else
      * you'll never print the edit bar and your components will be uneditable.
+     *
+     * This will be an empty string for new bars and when being rendered with skipContent
+     * set to true. If you need to determine whether you're wrapping a new bar,
+     * check component == null instead of checking this.
      */
     content: string;
     /**
@@ -392,9 +426,9 @@ export interface RenderComponentsWrapParams {
      *
      * Use this if you want to wrap the bar separately from the component content.
      *
-     * Will be blank in edit mode or when skipBars was set to true on the renderArea
-     * and/or renderComponents call. You probably want to check if it's blank before
-     * wrapping or you'll end up with an empty wrapper element.
+     * Will be empty string when not in edit mode or when skipBars was set to true on
+     * the renderArea and/or renderComponents call. You probably want to check if it's
+     * blank before wrapping or you'll end up with an empty wrapper element.
      */
     bar: string;
     /**
@@ -540,6 +574,6 @@ export declare abstract class Page<DataType extends PageData = any, FetchedType
      */
     addHeader: (key: string, value: string | undefined) => void;
     protected passError(e: Error, path: string): void;
-    constructor(page: PageRecord<DataType>, editMode: boolean);
+    constructor(page: PageRecord<DataType>, editMode: boolean, extension: string);
 }
 export {};

package/dist/component.js

@@ -11,7 +11,7 @@ function defaultWrap(info) { return info.output; }
 export class Component extends ResourceProvider {
     // the constructor is part of the recursive hydration mechanism: constructing
     // a Component will also construct/hydrate all its child components
-    constructor(data, path, parent, editMode) {
+    constructor(data, path, parent, editMode, extension) {
         super();
         /**
          * Override with `true` to indicate that this template never accepts data from editors
@@ -23,6 +23,7 @@ export class Component extends ResourceProvider {
         // building a template, but you can use them in the functions you do provide
         this.areas = new Map(); // a Map of area names and the array of hydrated components in each
         this.editMode = editMode;
+        this.extension = extension;
         this.parent = parent;
         const { areas, ...ownData } = data;
         this.data = ownData;
@@ -52,6 +53,9 @@ export class Component extends ResourceProvider {
      * 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() may be run while rendering a non-HTML variation of a page. If you need to do different
+     * work in those cases, remember this.extension is available.
      */
     async fetch() {
         return undefined;
@@ -99,6 +103,9 @@ export class Component extends ResourceProvider {
      * respond, or return empty string if you want your child components to be silent in all
      * cases.
      *
+     * The extension will NOT include the preceding dot. In the case of an extended extension like
+     * '.js.map', you will receive 'js.map'.
+     *
      * This function will be run after the fetch phase. The context and html rendering phases
      * will be skipped.
      */
@@ -126,7 +133,8 @@ export class Component extends ResourceProvider {
                     label: typeof opts?.editBarOpts?.label === 'function' ? opts.editBarOpts.label(c.component) : opts?.editBarOpts?.label,
                     extraClass: typeof opts?.editBarOpts?.extraClass === 'function' ? opts.editBarOpts.extraClass(c.component) : opts?.editBarOpts?.extraClass
                 });
-                return wrap({ output: bar + c.output, content: c.output, bar, component: c.component, indexInArea });
+                const content = opts?.skipContent ? '' : c.output;
+                return wrap({ output: bar + content, content, bar, component: c.component, indexInArea });
             }
         }).join('');
     }
@@ -247,9 +255,27 @@ export class Component extends ResourceProvider {
         this.parent?.passError(e, path);
     }
 }
+/**
+ * Only run fetch for specific variations.
+ *
+ * Sometimes pages are requested with an alternate extension like .rss or .ics. See 'renderVariation'
+ * method for more discussion on this.
+ *
+ * When rendering variations, many components will not need to fetch anything, because they are not
+ * going to render anything. For instance, if we are rendering an '.ics' variation and this component
+ * is not an event, it will not be participating and we'd like to avoid doing the work in the fetch().
+ *
+ * This variable is an array of extensions where we SHOULD run fetch(). The default is only run fetch
+ * on 'html'. Components that support other variations should override this method and opt in to more
+ * extensions.
+ *
+ * The extensions listed should NOT include the preceding dot. In the case of an extended extension like
+ * '.js.map', you should provide 'js.map'.
+ */
+Component.variationsToFetch = ['html'];
 export class Page extends Component {
-    constructor(page, editMode) {
-        super(page.data, '', undefined, editMode);
+    constructor(page, editMode, extension) {
+        super(page.data, '', undefined, editMode, extension);
         this.id = page.id;
         this.pageInfo = page;
     }

package/package.json

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