@dosgato/templating 0.0.57 → 0.0.59

package/dist/component.d.ts

@@ -233,6 +233,15 @@ export interface RenderedComponent<C extends Component = Component> {
     output: string;
 }
 export declare abstract class Page<DataType extends PageData = any, FetchedType = any, RenderContextType extends ContextBase = any> extends Component<DataType, FetchedType, RenderContextType> {
+    /**
+     * The page id in case you need to pass it to the API, e.g. this.api.getRootPage(this.id)
+     * in a page template or this.api.getRootPage(this.page.id) in a component template.
+     */
+    id: string;
+    /**
+     * The page path, can also be used to figure out where the page is, but you'll likely prefer
+     * using the page id in API queries
+     */
     pagePath: string;
     /**
      * This will be filled by the rendering server. The template properties are described

package/dist/component.js

@@ -176,6 +176,7 @@ export class Page extends Component {
     constructor(page, editMode) {
         super(page.data, '', undefined, editMode);
         this.pagePath = page.path;
+        this.id = page.id;
     }
     passError(e, path) {
         console.warn(`Recoverable issue occured during render of ${this.pagePath}. Component at ${path} threw the following error:`, e);

package/dist/provider.d.ts

@@ -5,6 +5,10 @@ export interface CSSBlock {
     css?: string;
     /**
      * A file path to the CSS. The rendering server will read the file on startup.
+     *
+     * Typically you will set this with import.meta.url so that the path will be relative
+     * to the javascript code where you are writing your template class:
+     * path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../static/mystyles.css')
      */
     path?: string;
     /**
@@ -35,6 +39,11 @@ export interface JSBlock {
     js?: string;
     /**
      * A file path to the javascript. The rendering server will read the file on startup.
+     *
+     * Typically you will set this with import.meta.url so that the path will be relative
+     * to the javascript code where you are writing your template class:
+     * path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../static/myscript.js')
+  
      */
     path?: string;
     /**
@@ -60,6 +69,10 @@ export interface JSBlock {
 export interface FileDeclaration {
     /**
      * The path to the file.
+     *
+     * Typically you will set this with import.meta.url so that the path will be relative
+     * to the javascript code where you are writing your template class:
+     * path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../static/myfont.ttf')
      */
     path: string;
     /**
@@ -75,6 +88,27 @@ export interface FileDeclaration {
      */
     mime?: string;
 }
+export interface SCSSInclude {
+    /**
+     * The SASS code as a string. This SCSS should generally only include functions
+     * and mixins. Regular CSS should be included as its own block so it can be de-duplicated.
+     *
+     * Variables don't make much sense because we only have one version of a block every
+     * time it's used, whereas variables usually change from page template to page template.
+     * Use CSS variables instead.
+     */
+    scss?: string;
+    /**
+     * A file path to the SASS code.
+     */
+    path?: string;
+    /**
+     * A version string following SEMVER. If multiple blocks are provided with the same name,
+     * the one with the highest version number will be chosen. If blocks of different major
+     * versions are provided, an alert will appear in the log.
+     */
+    version?: string;
+}
 /**
  * This class is a parent class for Component, but it can also be used as a standalone
  * if you are creating a set of templates with shared resources. This will be fairly
@@ -106,6 +140,19 @@ export declare abstract class ResourceProvider {
      * and the user has clicked something.
      */
     static cssBlocks: Map<string, CSSBlock>;
+    /**
+     * A template can provide SASS mixins and functions for use by other SASS-based CSS
+     * blocks.
+     *
+     * These includes can be utilized by other SASS with the SASS `@use` and `@include`
+     * commands, e.g.
+     * ```
+     * @use 'my-mixin-name' as mx;
+     * .someclass { @include mx.somemixin(); }
+     * ```
+     * In this case `my-mixin-name` is the key used for this Map.
+     */
+    static scssIncludes: Map<string, SCSSInclude>;
     /**
      * Same as cssBlocks() but for javascript.
      *
@@ -120,9 +167,6 @@ export declare abstract class ResourceProvider {
      * server. Use the provided `webpaths` map to obtain the proper resource URLs. They will be
      * available as soon as your template has been registered to the rendering server's templateRegistry.
      *
-     * Typically you will set this to something like `${__dirname}/static` so that the path will be relative
-     * to where you are writing your template class.
-     *
      * The map name you pick should be globally unique and only collide with other templates as
      * intended. For instance, the fontawesome font only needs to be provided once, even though
      * several templates might depend on it. Setting the name as 'fontawesome5' on all three

package/dist/provider.js

@@ -32,6 +32,19 @@ export class ResourceProvider {
  * and the user has clicked something.
  */
 ResourceProvider.cssBlocks = new Map();
+/**
+ * A template can provide SASS mixins and functions for use by other SASS-based CSS
+ * blocks.
+ *
+ * These includes can be utilized by other SASS with the SASS `@use` and `@include`
+ * commands, e.g.
+ * ```
+ * @use 'my-mixin-name' as mx;
+ * .someclass { @include mx.somemixin(); }
+ * ```
+ * In this case `my-mixin-name` is the key used for this Map.
+ */
+ResourceProvider.scssIncludes = new Map();
 /**
  * Same as cssBlocks() but for javascript.
  *
@@ -46,9 +59,6 @@ ResourceProvider.jsBlocks = new Map();
  * server. Use the provided `webpaths` map to obtain the proper resource URLs. They will be
  * available as soon as your template has been registered to the rendering server's templateRegistry.
  *
- * Typically you will set this to something like `${__dirname}/static` so that the path will be relative
- * to where you are writing your template class.
- *
  * The map name you pick should be globally unique and only collide with other templates as
  * intended. For instance, the fontawesome font only needs to be provided once, even though
  * several templates might depend on it. Setting the name as 'fontawesome5' on all three

package/dist/render.d.ts

@@ -50,6 +50,14 @@ export interface APIClient {
         absolute?: boolean;
         extension?: string;
     }) => Promise<string>;
+    /**
+     * Get a link href for a page
+     *
+     * By default this will generate relative links based on the page currently being rendered. Set
+     * absolute: true to generate a full URL suitable for a backend http request or non-HTML document
+     * like an RSS feed.
+     */
+    getHref: (page: PageRecord, absolute?: boolean) => 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

package/package.json

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