58 documentation for boilerplate

README.md

@@ -1,26 +1,66 @@
-# Your Project's Title...
-Your project's description...
+# Boilerplate for AEM Edge Delivery Services
+This is our Edge Delivery Services boilerplate.
+
+## Table of Contents
+- [Environments](#environments)
+- [Getting started](#getting-started)
+  - [Prerequisites](#prerequisites)
+  - [Installation](#installation)
+- [Linting](#linting)
+- [Documentation](#documentation)
 
 ## Environments
 - Preview: [https://main--eds-editorial--ifahrentholz.hlx.page/](https://main--eds-editorial--ifahrentholz.hlx.page/)
 - Live: [https://main--eds-editorial--ifahrentholz.hlx.live/](https://main--eds-editorial--ifahrentholz.hlx.live/)
 
-## Installation
+### Prerequisites
 
-```sh
-npm i
-```
+- GitHub account
+- Google or Microsoft account
+- npm
+  ```sh
+  npm i
+  ```
+
+### Installation
+
+1. Create your repository using the Boilerplate GitHub repository as a template:
+    https://github.com/divae/boilerplate
+
+2. Add the AEM Code Sync GitHub App to the repository: 
+    https://github.com/apps/aem-code-sync/installations/new
+
+    - Select `Only select Repositories` (not `All Repositories`).
+
+3. Link content source (Google Drive or Microsoft Sharepoint)
+    - Create a folder in Google Drive/Sharepoint and share the folder with the Adobe Experience Manager user (`[email protected]`).
+    - Change the reference in `fstab.yaml` in your GitHub repo to the Google Drive/Sharepoint folder URL and commit the changes.
+
+4. Install the Sidekick Chrome extension:
+    https://chromewebstore.google.com/detail/aem-sidekick/ccfggkjabjahcjoljmgmklhpaccedipo?pli=1
+
+    - Go to the Google Drive/Sharepoint folder, click on the extension icon in the browser toolbar and select `Add this project`.
+    - To preview and publish content, select a file in Google Drive/Sharepoint, click on the extension icon to open the new Sidekick Toolbar and click `preview` or `publish`.
+
+5. Start development
+    - Install the AEM Command Line Interface (CLI) and clone your repo locally.
+    ```
+      npm install -g @adobe/aem-cli
+      git clone https://github.com/<owner>/<repo>
+    ```
+    - Change into project folder and start your local dev environment. `npm start` initializes a build as well as runs the `aem up` command.
+    ```
+      cd <repo>
+      npm start
+    ```
+    - Use Git to push code changes to your preview (https://<branch>--<repo>--<owner>.hlx.page/) and production (https://<branch>--<repo>--<owner>.hlx.live/) sites.
 
 ## Linting
 
 ```sh
 npm run lint
 ```
 
-## Local development
+## Documentation
 
-1. Create a new repository based on the `aem-boilerplate` template and add a mountpoint in the `fstab.yaml`
-1. Add the [AEM Code Sync GitHub App](https://github.com/apps/aem-code-sync) to the repository
-1. Install the [AEM CLI](https://github.com/adobe/aem-cli): `npm install -g @adobe/aem-cli`
-1. Start AEM Proxy: `aem up` (opens your browser at `http://localhost:3000`)
-1. Open the `{repo}` directory in your favorite IDE and start coding :)
+For more information, please refer to the <a href="https://github.com/ifahrentholz/eds-editorial/wiki">documentation</a>.

documentation.md

@@ -0,0 +1,279 @@
+# Documentation
+<details><summary>src/directives</summary>
+
+## :wrench: Constants
+
+- [getSidekickLibraryId](#gear-getsidekicklibraryid)
+
+### :gear: getSidekickLibraryId
+
+| Constant | Type |
+| ---------- | ---------- |
+| `getSidekickLibraryId` | `(sidekickElement: SidekickElement) => DirectiveResult<typeof SidekickLibraryId>` |
+
+
+
+
+</details>
+
+<details><summary>src/utils</summary>
+
+## :toolbox: Functions
+
+- [toClassName](#gear-toclassname)
+- [addClasses](#gear-addclasses)
+- [createOptimizedPicture](#gear-createoptimizedpicture)
+- [getMetadata](#gear-getmetadata)
+- [replaceBySpecifier](#gear-replacebyspecifier)
+- [toCamelCase](#gear-tocamelcase)
+- [undefinedOnEmpty](#gear-undefinedonempty)
+- [wrap](#gear-wrap)
+
+### :gear: toClassName
+
+Converts a string into a valid CSS class name.
+
+| Function | Type |
+| ---------- | ---------- |
+| `toClassName` | `(name: string) => string` |
+
+Parameters:
+
+* `name`: - The string to convert into a CSS class name.
+
+
+### :gear: addClasses
+
+Adds CSS classes to an HTML element.
+
+| Function | Type |
+| ---------- | ---------- |
+| `addClasses` | `(element: HTMLElement, classes: string) => void` |
+
+Parameters:
+
+* `element`: - The HTML element to which classes will be added.
+* `classes`: - A string containing CSS classes separated by commas.
+
+
+### :gear: createOptimizedPicture
+
+Creates an optimized HTML picture element with responsive image sources and a fallback image.
+
+| Function | Type |
+| ---------- | ---------- |
+| `createOptimizedPicture` | `(createOptimizedPictureArgs: CreateOptimizedPictureArgs) => HTMLPictureElement or undefined` |
+
+Parameters:
+
+* `createOptimizedPictureArgs`: - The arguments for creating the picture element.
+
+
+### :gear: getMetadata
+
+Retrieves the content of a specified metadata tag from the document head.
+
+| Function | Type |
+| ---------- | ---------- |
+| `getMetadata` | `(value: string, doc?: Document) => string` |
+
+Parameters:
+
+* `value`: - The name or property attribute value of the metadata tag.
+* `doc`: - The document to search for the metadata tag (default is the current document).
+
+
+### :gear: replaceBySpecifier
+
+Replaces occurrences of a specified specifier in a string with an HTML tag.
+
+| Function | Type |
+| ---------- | ---------- |
+| `replaceBySpecifier` | `({ input, specifier, htmlTag }: ReplaceBySpecifier) => string` |
+
+Parameters:
+
+* `param`: - An object containing input string, specifier, and HTML tag.
+* `param.input`: - The input string where replacements will be made.
+* `param.specifier`: - The specifier string to search for in the input.
+* `param.htmlTag`: - The HTML tag to wrap around the parts matched by the specifier.
+
+
+### :gear: toCamelCase
+
+Sanitizes a string for use as a JavaScript property name.
+
+| Function | Type |
+| ---------- | ---------- |
+| `toCamelCase` | `(name: string) => string` |
+
+Parameters:
+
+* `name`: - The unsanitized string.
+
+
+### :gear: undefinedOnEmpty
+
+Returns undefined if the value is an empty string, otherwise returns the value itself.
+
+| Function | Type |
+| ---------- | ---------- |
+| `undefinedOnEmpty` | `(value: string) => string or undefined` |
+
+Parameters:
+
+* `value`: - The value to check.
+
+
+### :gear: wrap
+
+Wraps an HTML element with another HTML element.
+
+| Function | Type |
+| ---------- | ---------- |
+| `wrap` | `(element: HTMLElement, wrapper: HTMLElement) => void` |
+
+Parameters:
+
+* `element`: - The HTML element to wrap.
+* `wrapper`: - The HTML element to use as a wrapper.
+
+
+
+## :factory: RuntimeCache
+
+### Methods
+
+- [get](#gear-get)
+- [set](#gear-set)
+- [has](#gear-has)
+- [delete](#gear-delete)
+
+#### :gear: get
+
+| Method | Type |
+| ---------- | ---------- |
+| `get` | `<T>(key: string) => T or undefined` |
+
+#### :gear: set
+
+| Method | Type |
+| ---------- | ---------- |
+| `set` | `<T>(key: string, value: T) => void` |
+
+#### :gear: has
+
+| Method | Type |
+| ---------- | ---------- |
+| `has` | `(key: string) => boolean` |
+
+#### :gear: delete
+
+| Method | Type |
+| ---------- | ---------- |
+| `delete` | `(key: string) => void` |
+
+
+## :tropical_drink: Interfaces
+
+- [CreateOptimizedPictureArgs](#gear-createoptimizedpictureargs)
+
+### :gear: CreateOptimizedPictureArgs
+
+Represents the arguments for creating an optimized picture element.
+
+| Property | Type | Description |
+| ---------- | ---------- | ---------- |
+| `src` | `string` |  |
+| `alt` | `string` |  |
+| `width` | `number` |  |
+| `height` | `number` |  |
+| `eager` | `boolean or undefined` |  |
+| `breakpoints` | `BreakPoint[] or undefined` |  |
+
+
+
+</details>
+
+<details><summary>src/helpers/sidekick</summary>
+
+## :toolbox: Functions
+
+- [isSidekickLibraryActive](#gear-issidekicklibraryactive)
+- [extractSidekickLibraryId](#gear-extractsidekicklibraryid)
+- [getHref](#gear-gethref)
+- [getLocation](#gear-getlocation)
+- [getOrigin](#gear-getorigin)
+
+### :gear: isSidekickLibraryActive
+
+Verifies if the Sidekick Library Plugin is in use by checking if the page is running in an iframe with srcdoc
+and if the main element has the sidekick-library class.
+
+| Function | Type |
+| ---------- | ---------- |
+| `isSidekickLibraryActive` | `() => boolean` |
+
+### :gear: extractSidekickLibraryId
+
+Extracts the innerHTML, the href attribute (if defined) and
+the data-library-id attribute (if the Sidekick Library Plugin is active) of a given HTML element.
+
+| Function | Type |
+| ---------- | ---------- |
+| `extractSidekickLibraryId` | `(element?: HTMLElement or HTMLAnchorElement or null or undefined) => SidekickElement` |
+
+Parameters:
+
+* `element`: - The original HTMLElement or HTMLAnchorElement.
+
+
+### :gear: getHref
+
+Returns the true origin of the current page in the browser.
+If the page is running in an iframe with srcdoc, the ancestor origin + the path query param is returned.
+
+| Function | Type |
+| ---------- | ---------- |
+| `getHref` | `() => string` |
+
+### :gear: getLocation
+
+Returns the true origin of the current page in the browser.
+If the page is running in an iframe with srcdoc, the query param is returned.
+
+| Function | Type |
+| ---------- | ---------- |
+| `getLocation` | `() => Location` |
+
+### :gear: getOrigin
+
+Returns the true origin of the current page in the browser.
+If the page is running in an iframe with srcdoc, the ancestor origin is returned.
+
+| Function | Type |
+| ---------- | ---------- |
+| `getOrigin` | `() => string` |
+
+
+
+## :cocktail: Types
+
+- [SidekickElement](#gear-sidekickelement)
+
+### :gear: SidekickElement
+
+Represents the constructed Element.
+
+| Type | Type |
+| ---------- | ---------- |
+| `SidekickElement` | `{
+  dataLibraryId?: string;
+  innerHTML: string;
+  href?: string;
+}` |
+
+
+
+</details>
+