@dosgato/templating 0.0.112 → 0.0.114

package/dist/apitemplate.d.ts

@@ -80,6 +80,17 @@ export interface APITemplate<DataType> {
      * by this function will also be scanned for links.
      */
     getFulltext?: FulltextGatheringFn<DataType>;
+    /**
+     * The available component list in the main content area can get very long, among others. Therefore, each
+     * template may set a displayCategory and any templates that share a displayCategory will be grouped together
+     * underneath one tab when a user is presented with a choice of template.
+     *
+     * If a displayCategory is not set, there will be a default category like 'Standard'. If only one category
+     * exists for a group of available components, the tabs will not be shown at all. This means you do not have
+     * to bother setting displayCategory for minor cases like different kinds of slides in a slider (until there
+     * are so many that it becomes a good idea!).
+     */
+    displayCategory?: string;
 }
 export interface APIComponentTemplate<DataType extends ComponentData = any> extends APITemplate<DataType> {
     type: 'component';
@@ -136,6 +147,20 @@ export interface APIPageTemplate<DataType extends PageData = any> extends APITem
      * Must be null for non-page templates.
      */
     templateProperties?: any;
+    /**
+     * Container components specify their own list of compatible templates for each of their areas,
+     * but it is possible that a sub-component could be compatible with its container while not really
+     * being compatible with the template as a whole. For instance, a special purpose template may want
+     * to allow containers but only a couple simple components inside those containers.
+     *
+     * Without this property, the only choice would be to re-make all your container components with a special
+     * templateKey just for this page template and their custom set of availableComponents. That's a lot to maintain,
+     * so this property is available to disallow sub-components at the page template level.
+     *
+     * Any template key you list here will be unavailable inside this page template, no matter how many
+     * nested containers are in between.
+     */
+    disallowComponents?: string[];
 }
 export interface APIDataTemplate<DataType extends DataData = any> extends APITemplate<DataType> {
     type: 'data';

package/dist/render.d.ts

@@ -1,5 +1,13 @@
 import { ContextBase, DataData, PageData, PageRecord, PageRecordOptionalData } from './component.js';
 import { AssetFolderLink, AssetLink, DataFolderLink, DataLink, LinkDefinition, PageLink } from './links.js';
+/**
+ * Safely encapsulates `content` in header tags based on the `ctx` context passed and adds any passed `attributes` to the header tagging.
+ * If the headerLevel passed through `ctx` is outside the range of 1..6 the header tag generated is normalized to the nearest value of 1 or 6.
+ * @returns An empty string if content is blank, undefined, or null - else an h<1..6> encapsulated content with attributes added to the encapsulating tag.
+ * @example ```
+ *   printHeader(this.renderCtx, htmlEncode(this.data.title), {class: 'some-extra-cssclass'})
+ *   // Renders: '<h1 class="some-extra-cssclass">Title</h1>'
+ * ``` */
 export declare function printHeader(ctx: ContextBase, content: string | undefined | null, attributes?: Record<string, string>): string;
 export declare function advanceHeader<T extends ContextBase>(ctx: T, content: string | undefined | null): T;
 export interface PictureResize {
@@ -150,17 +158,50 @@ export interface APIClient {
         path?: string;
     }) => Promise<PageRecord<PageData>>;
     /**
-     * Get a hierarchical tree of pages suitable for generating a navigation
-     * UI for your template.
+     * Get a hierarchical tree of pages suitable for generating a navigation UI for your template.
      *
-     * Returns the root page(s). Subpages are inside the `children` property.
-     */
+     * Each element in the array is recursive such that any subpage descendants can be found by
+     * traversing each element's respective `children` property.
+     *
+     * @param opts
+     * ```
+     *  { // Return pages beneath this path but not the page that is this path.
+          // If `undefined` you will get back a single element array that
+          // references the `PageForNaviation` of the root page of the pageTree.
+          beneath? string
+      
+          // Relative to `beneath` this controls how many levels deep to fetch past
+          // the top level set of results in the array. 0 returns the top level only
+          // while n > 0 traverses n levels of children deep past the top level
+          // results. Leave `undefined` to fetch all.
+          depth?: number
+          
+          // Set to true to filter for only pages that are published. Else the default
+          // of false will automatically not filter unpublished pages when in edit or
+          // preview mode but will filter if in published mode.
+          // WARNING:
+          // If none of the pages in the current pageTree have been published and this is
+          // set to `true` an error will be thrown as there will be no pages to return.
+          published?: boolean
+          
+          // Array of strings that specify dot-separated object paths describing page
+          // data not normally fetched within the PageForNavigation results. For example,
+          // ['hideInNav'] would append the page record hideInNav value to the
+          // `PageForNavigation.extra` property as its own sub-property `hideInNav` that
+          // would normally be excluded from the `PageForNavigation` properties.
+          extra?: string[]
+          
+          // Whether the href property in the returned records should be an absolute URL.
+          absolute?: boolean
+        }
+        ``` */
     getNavigation: (opts?: {
         /**
          * Return pages beneath this path
          *
          * For instance, if you set this to '/site1' you will get back ['/site1/about',
-         * '/site1/history', '/site1/history/traditions', ...etc]
+         * '/site1/history', '/site1/history/traditions', ...etc] but you will NOT get
+         * back the '/site1' page.
          *
          * If you do not set `beneath`, you will get back an array that contains only
          * the root page of the pagetree you are in.
@@ -193,8 +234,8 @@ export interface APIClient {
          * transfer, but if you need some of the data, you can specify an array of dot-separated
          * paths to retrieve from it.
          *
-         * For example, ['hideInNav'] would get you { extra: { hideInNav: tru } } in each returned
-         * page record.
+         * For example, ['hideInNav'] would get you the additional property `extra.hideInNav` in
+         * each returned page record.
          */
         extra?: string[];
         /**

package/dist/render.js

@@ -1,4 +1,12 @@
 import { htmlEncode, isBlank, isNotEmpty } from 'txstate-utils';
+/**
+ * Safely encapsulates `content` in header tags based on the `ctx` context passed and adds any passed `attributes` to the header tagging.
+ * If the headerLevel passed through `ctx` is outside the range of 1..6 the header tag generated is normalized to the nearest value of 1 or 6.
+ * @returns An empty string if content is blank, undefined, or null - else an h<1..6> encapsulated content with attributes added to the encapsulating tag.
+ * @example ```
+ *   printHeader(this.renderCtx, htmlEncode(this.data.title), {class: 'some-extra-cssclass'})
+ *   // Renders: '<h1 class="some-extra-cssclass">Title</h1>'
+ * ``` */
 export function printHeader(ctx, content, attributes) {
     if (isBlank(content))
         return '';

package/package.json

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