feat: BaseController - An extendable controller that provides common …

…useful behaviours and properties for all controllers that use it as a base
Sub-Xaero · Apr 24, 2021 · a12b101 · a12b101
1 parent 5c62e02
commit a12b101
Show file tree

Hide file tree

Showing 16 changed files with 101 additions and 10 deletions.
diff --git a/dist/index.d.ts b/dist/index.d.ts
@@ -1,3 +1,4 @@
+export { BaseController } from "./utilities/base_controller";
 export { AnchorSpyController } from "./controllers/anchor_spy_controller";
 export { AppearanceController } from "./controllers/utility/appearance_controller";
 export { AsyncBlockController } from "./controllers/async_block_controller";

diff --git a/dist/index.d.ts.map b/dist/index.d.ts.map
diff --git a/dist/stimulus-library.js b/dist/stimulus-library.js
diff --git a/dist/stimulus-library.js.map b/dist/stimulus-library.js.map
diff --git a/dist/stimulus-library.modern.js b/dist/stimulus-library.modern.js
diff --git a/dist/stimulus-library.modern.js.map b/dist/stimulus-library.modern.js.map
diff --git a/dist/stimulus-library.module.js b/dist/stimulus-library.module.js
diff --git a/dist/stimulus-library.module.js.map b/dist/stimulus-library.module.js.map
diff --git a/dist/stimulus-library.umd.js b/dist/stimulus-library.umd.js
diff --git a/dist/stimulus-library.umd.js.map b/dist/stimulus-library.umd.js.map
diff --git a/dist/utilities/base_controller.d.ts b/dist/utilities/base_controller.d.ts
@@ -2,6 +2,10 @@ import { Context, Controller } from "stimulus";
 export declare class BaseController extends Controller {
     constructor(context: Context);
     get el(): HTMLElement;
+    get isTurboPreview(): boolean;
+    get isTurbolinksPreview(): boolean;
+    get csrfToken(): string | null;
+    metaValue(name: string): string | null;
     dispatch(element: HTMLElement, eventName: string, options?: CustomEventInit): void;
     log(functionName: string, args?: {}): void;
     logEvent(eventName: string, event: CustomEvent, element: HTMLElement): void;

diff --git a/dist/utilities/base_controller.d.ts.map b/dist/utilities/base_controller.d.ts.map
diff --git a/docs/docs/controllers/base_controller.mdx b/docs/docs/controllers/base_controller.mdx
@@ -0,0 +1,60 @@
+---
+id: BaseController
+title: BaseController
+---
+
+
+## Purpose
+
+Provide common utilities and base functionality for all Stimulus controllers that extend this controller.
+
+
+## Properties
+
+This controller provides the following properties to sub-classes.
+
+| Name | Purpose | Return Value |
+| --- | --- | --- |
+| `el` | For Typescript projects, provides a wrapper around `this.element` typecast to `HTMLElement` so that type-hinting correctly works for all DOM APIs | The controller root element, as an `HTMLElement` |
+| `isTurboPreview` | Whether or not the document is currently displaying a preview from the Hotwire/Turbo cache https://turbo.hotwire.dev/handbook/building#detecting-when-a-preview-is-visible. Also works with legacy Turbolinks | `boolean` |
+| `isTurbolinksPreview` | Alias for `isTurboPreview`, both methods work for both Turbolinks and Hotwire | `boolean` |
+| `csrfToken` | The current Rails CSRF token, taken from the `<meta>` tag Rails inserts into the document head, if present. | `string` or `null` |
+
+## Methods
+
+This controller provides the following methods to sub-classes.
+
+| Name | Parameters | Purpose | Default |
+| --- | --- | --- | --- |
+| `dispatch` |  | Dispatch a custom event | |
+|  | `element` | The element to dispatch the event on | |
+|  | `eventName` | The fully qualified name of the event. Usually follows the format `controller-identifier:event` | |
+|  | `options` (Optional) | The options to initialize the event with. See the options `eventInit` accepts: https://developer.mozilla.org/en-US/docs/Web/API/Event/Event  | `{ bubbles: true, cancellable: true, details: { element: this.element } }` |
+
+| Name | Parameters | Purpose | Return value |
+| --- | --- | --- | --- |
+| `metaValue` |  | Fetch a value from a `<meta>` tag in the `<head>` of the document. | `string` or `null` |
+|  | `name` | The `name` attribute of the `meta` tag to fetch the value of | |
+
+
+## Side Effects / Inherited Behaviour
+
+If [debug mode](/docs/debugging) is enabled, any controller that extends BaseController controller will automatically log calls to any actions or methods, and events dispatched with `this.dispatch`.
+
+If there are any getters, setters, methods or properties that should not be logged, you should name them with an underscore prefix i.e. `_foo() {}`, or `_bar = "baz"` to indicate that they are private methods.
+
+
+## How to Use
+
+```typescript
+import {BaseController} from "stimulus-library";
+
+export default class extends BaseController {
+  // ...
+
+ foo() {
+   this.dispatch( this.el, "my-controller:something-happened", { bubbles: true, cancellable: true, detail: { element: this.el, data: 'thing' } } )
+ }
+
+}
+```
diff --git a/docs/sidebars.js b/docs/sidebars.js
@@ -12,6 +12,11 @@ module.exports = {
           "controllers/LazyBlockController",
           "controllers/TeleportController",
           "controllers/ToggleClassController",
+        ],
+      },
+      {
+        "Extendable Controllers": [
+          "controllers/BaseController",
         ]
       },
       {

diff --git a/src/index.ts b/src/index.ts
@@ -1,3 +1,7 @@
+// Utilities
+export {BaseController} from "./utilities/base_controller";
+
+// Controllers
 export {AnchorSpyController} from "./controllers/anchor_spy_controller";
 export {AppearanceController} from "./controllers/utility/appearance_controller";
 export {AsyncBlockController} from "./controllers/async_block_controller";

diff --git a/src/utilities/base_controller.ts b/src/utilities/base_controller.ts
@@ -31,6 +31,23 @@ export class BaseController extends Controller {
     return this.element as HTMLElement;
   }
 
+  get isTurboPreview(): boolean {
+    return document.documentElement.hasAttribute('data-turbo-preview') || document.documentElement.hasAttribute('data-turbolinks-preview');
+  }
+
+  get isTurbolinksPreview(): boolean {
+    return this.isTurboPreview;
+  }
+
+  get csrfToken(): string | null {
+    return this.metaValue('csrf-token');
+  }
+
+  metaValue(name: string): string | null {
+    const element = document.head.querySelector(`meta[name="${name}"]`);
+    return element?.getAttribute('content') || null;
+  }
+
   dispatch(element: HTMLElement, eventName: string, options: CustomEventInit = {}) {
     let mergedOptions = Object.assign({}, {bubbles: true, cancelable: true, detail: {target: element}}, options);
     if (!!mergedOptions.detail.target) {