From fc2e44a9ef884e471684e336e6116bfe1ed5c183 Mon Sep 17 00:00:00 2001 From: Niklas Haeusele Date: Wed, 4 Dec 2024 01:20:02 +0100 Subject: [PATCH 1/7] Add optional prefix, improve readme --- README.md | 40 ++++++++++--------- .../javascript/custom_elements-rails.js | 5 +++ .../app/javascript/custom_elements/index.js | 2 +- 3 files changed, 27 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 444040c..efad288 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,9 @@ This gem adds a simple way to automatically register custom elements in your `importmap-rails` app. No build step required! +- Supports `importmap-rails` v1 and v2. +- Supports `rails` 7.0, 7.1 & 8.0. + ## Installation Add this line to your application's Gemfile: @@ -34,20 +37,22 @@ app/javascript └── index.js ``` -The `` custom element can be used in the views now. +The `` custom element can be used in views now. + +You can generate a new custom element `` with `rails generate custom_element demo`. -You can generate a new custom element with `rails g custom_element abc`. +### How It Works -## How it works +The `custom_elements-rails` gem uses `eagerDefineCustomElementsFrom` to automatically register [custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements) from the `custom_elements` folder. It reads the importmap from `importmap-rails` and registers elements using `customElements.define(...)`. -The setup will add a JS function call `eagerDefineCustomElementsFrom` that parses the importmap rendered by the `importmap-rails` gem. -It registers custom elements with `customElements.define(...)` in the browser's registry based on the filenames in the `custom_elements` folder automatically. +For example: ``` -custom_elements/hello_element.js // will register automatically +custom_elements/hello_element.js // Automatically registers ``` -Your `*_element.js` files have to `export default` custom elements for this to work properly. +> [!IMPORTANT] +> Make sure your `*_element.js` files use `export default` to define the custom elements. ### Naming Convention for Custom Elements @@ -55,21 +60,12 @@ When defining custom elements from files, their filenames are used to generate t #### Usage -Register all files in the `custom_elements` folder as custom elements using a prefix (e.g., `app`): +Register all files in the `custom_elements` folder as custom elements: ```js eagerDefineCustomElementsFrom("custom_elements", { prefix: "app" }); ``` -#### Conversion Rules - -- Filenames are transformed into kebab-case (lowercase with hyphens). -- Words are separated by underscores (`_`) or hyphens (`-`) in the filename. -- The folder structure is reflected in the name using double hyphens (`--`) to separate folder names from the file name. -- A prefix (e.g., `app`) is added to the beginning of each custom element name. - -#### Examples - | Filepath | Generated Custom Element Name | |-------------------------------------|--------------------------------| | `custom_elements/demo_element.js` | `` | @@ -77,6 +73,12 @@ eagerDefineCustomElementsFrom("custom_elements", { prefix: "app" }); | `custom_elements/foo_bar_element.js`| `` | | `custom_elements/folder/foo_bar_element.js` | `` | +#### Conversion Rules + +- Filenames are transformed into kebab-case (lowercase with hyphens). +- The folder structure is reflected in the name using double hyphens (`--`) to separate folder names from the file name. +- A [configurable prefix](#documentation) is added to the beginning of each custom element name. + ## Add a custom element with the built-in generator This gem adds a generator to generate new custom elements with: @@ -136,9 +138,9 @@ export default class extends HTMLElement { `eagerDefineCustomElementsFrom(under, options)` -Currently supported `options`: +Currently supported optional `options`: -* `prefix`: The custom elements namespace/prefix. +* `prefix`: The custom elements namespace. (default: "app") ## Contributing diff --git a/app/assets/javascript/custom_elements-rails.js b/app/assets/javascript/custom_elements-rails.js index 73dc1c7..dc35e88 100644 --- a/app/assets/javascript/custom_elements-rails.js +++ b/app/assets/javascript/custom_elements-rails.js @@ -1,4 +1,9 @@ export function eagerDefineCustomElementsFrom(namespace, options = {}) { + const defaultOptions = { + prefix: 'app' + } + + options = { ...defaultOptions, ...options } const pathToElementName = (path) => { const parts = path.split('/').map(p => p.replace(/_/g, '-')); return `${options.prefix}-${parts.slice(0, -1).join('--')}${parts.length > 1 ? '--' : ''}${parts.at(-1)}`; diff --git a/test/dummy/app/javascript/custom_elements/index.js b/test/dummy/app/javascript/custom_elements/index.js index d0f0e54..3839b82 100644 --- a/test/dummy/app/javascript/custom_elements/index.js +++ b/test/dummy/app/javascript/custom_elements/index.js @@ -1,3 +1,3 @@ import { eagerDefineCustomElementsFrom } from "custom_elements-rails" -eagerDefineCustomElementsFrom("custom_elements", { prefix: "app" }) +eagerDefineCustomElementsFrom("custom_elements") From d56b1ace2f8b91d481ae1ecfbfc18d67d2c31c8a Mon Sep 17 00:00:00 2001 From: Niklas Haeusele Date: Fri, 6 Dec 2024 23:03:15 +0100 Subject: [PATCH 2/7] improvements --- README.md | 38 +++++++++++++++++++++++++------------- 1 file changed, 25 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index efad288..c940aba 100644 --- a/README.md +++ b/README.md @@ -4,8 +4,24 @@ This gem adds a simple way to automatically register custom elements in your `importmap-rails` app. No build step required! -- Supports `importmap-rails` v1 and v2. -- Supports `rails` 7.0, 7.1 & 8.0. +## Table of Contents + +
+Click to expand + +- [Rails support](#rails-support) +- [Installation](#installation) +- [Generators](#generators) +- [Documentation](#documentation) +- [Contributing](#contributing) +- [License](#license) + +
+ +## Rails support + +* Supports Rails 7.0, 7.1, 7.2 & 8.0 +* Supports `importmap-rails` 1 and 2 ## Installation @@ -29,7 +45,7 @@ $ rails custom_elements:install This will setup and edit add the following files: -``` +```graphql app/javascript ├── application.js └── custom_elements @@ -43,13 +59,7 @@ You can generate a new custom element `` with `rails generate custom_e ### How It Works -The `custom_elements-rails` gem uses `eagerDefineCustomElementsFrom` to automatically register [custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements) from the `custom_elements` folder. It reads the importmap from `importmap-rails` and registers elements using `customElements.define(...)`. - -For example: - -``` -custom_elements/hello_element.js // Automatically registers -``` +The `custom_elements-rails` gem uses `eagerDefineCustomElementsFrom` to automatically register [custom elements](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements) in the `custom_elements` folder. It parses the importmap generated by `importmap-rails` and registers custom elements using the `customElements.define(...)` API. > [!IMPORTANT] > Make sure your `*_element.js` files use `export default` to define the custom elements. @@ -67,7 +77,7 @@ eagerDefineCustomElementsFrom("custom_elements", { prefix: "app" }); ``` | Filepath | Generated Custom Element Name | -|-------------------------------------|--------------------------------| +|:-----------------------------------:|:------------------------------:| | `custom_elements/demo_element.js` | `` | | `custom_elements/demo-element.js` | `` | | `custom_elements/foo_bar_element.js`| `` | @@ -79,7 +89,7 @@ eagerDefineCustomElementsFrom("custom_elements", { prefix: "app" }); - The folder structure is reflected in the name using double hyphens (`--`) to separate folder names from the file name. - A [configurable prefix](#documentation) is added to the beginning of each custom element name. -## Add a custom element with the built-in generator +## Generators This gem adds a generator to generate new custom elements with: @@ -144,7 +154,9 @@ Currently supported optional `options`: ## Contributing -TODO +1. Fork the repository. +2. Create a feature branch. +3. Submit a pull request with a detailed description of changes. ## License From 0eb8668e7e6a447b717487af0fa2169649c8c668 Mon Sep 17 00:00:00 2001 From: Niklas Haeusele Date: Fri, 6 Dec 2024 23:13:48 +0100 Subject: [PATCH 3/7] bash -> console --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index c940aba..31e98d9 100644 --- a/README.md +++ b/README.md @@ -33,13 +33,13 @@ gem "custom_elements-rails" Install the gem: -```bash +```console $ bundle install ``` Run the initial setup: -```bash +```console $ rails custom_elements:install ``` @@ -93,7 +93,7 @@ eagerDefineCustomElementsFrom("custom_elements", { prefix: "app" }); This gem adds a generator to generate new custom elements with: -```bash +```console $ rails generate custom_element test ``` @@ -114,13 +114,13 @@ export default class extends HTMLElement { which in turn will register a `` custom element automatically in your app. -```bash +```console $ rails generate custom_element test ``` To observe changes in your custom element's attributes, you need to set a static array of attribute names. The generator also supports setting those automatically: -```bash +```console $ rails generate custom_element test attribute1 ``` From 6459ab1f4aeb5fb085e930d89ea70b4291447ee0 Mon Sep 17 00:00:00 2001 From: Niklas Haeusele Date: Fri, 6 Dec 2024 23:20:53 +0100 Subject: [PATCH 4/7] table --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 31e98d9..5dba334 100644 --- a/README.md +++ b/README.md @@ -76,12 +76,12 @@ Register all files in the `custom_elements` folder as custom elements: eagerDefineCustomElementsFrom("custom_elements", { prefix: "app" }); ``` -| Filepath | Generated Custom Element Name | -|:-----------------------------------:|:------------------------------:| -| `custom_elements/demo_element.js` | `` | -| `custom_elements/demo-element.js` | `` | -| `custom_elements/foo_bar_element.js`| `` | -| `custom_elements/folder/foo_bar_element.js` | `` | +| Filepath | Generated Custom Element Name | +|:-------------------------------------------:|:-----------------------------:| +| `custom_elements/demo_element.js` | `` | +| `custom_elements/demo-element.js` | `` | +| `custom_elements/foo_bar_element.js` | `` | +| `custom_elements/folder/foo_bar_element.js` | `` | #### Conversion Rules From 2865d049b4dcaafa6a57eaea128885c4627302fb Mon Sep 17 00:00:00 2001 From: Niklas Haeusele Date: Fri, 6 Dec 2024 23:23:43 +0100 Subject: [PATCH 5/7] badges --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 5dba334..45cfba8 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # Custom Elements Rails -[![Tests](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml) +[![Rails 8.0](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml) +[![Rails 7.2](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml) +[![Rails 7.1](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml) This gem adds a simple way to automatically register custom elements in your `importmap-rails` app. No build step required! From 4472bcd6b2070a5168d458f80571952f2897056b Mon Sep 17 00:00:00 2001 From: Niklas Haeusele Date: Sat, 7 Dec 2024 10:28:16 +0100 Subject: [PATCH 6/7] alignment --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 45cfba8..80d6f5b 100644 --- a/README.md +++ b/README.md @@ -79,7 +79,7 @@ eagerDefineCustomElementsFrom("custom_elements", { prefix: "app" }); ``` | Filepath | Generated Custom Element Name | -|:-------------------------------------------:|:-----------------------------:| +|--------------------------------------------:|:------------------------------| | `custom_elements/demo_element.js` | `` | | `custom_elements/demo-element.js` | `` | | `custom_elements/foo_bar_element.js` | `` | From 16c6bbc79ecff3ed6a7befade4a2240538f0a586 Mon Sep 17 00:00:00 2001 From: Niklas Haeusele Date: Sat, 7 Dec 2024 10:30:36 +0100 Subject: [PATCH 7/7] fixup --- README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/README.md b/README.md index 80d6f5b..b6cb2cf 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,6 @@ # Custom Elements Rails -[![Rails 8.0](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml) -[![Rails 7.2](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml) -[![Rails 7.1](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml) +[![Tests](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml/badge.svg?branch=main)](https://github.com/codergeek121/custom_elements-rails/actions/workflows/ruby.yml) This gem adds a simple way to automatically register custom elements in your `importmap-rails` app. No build step required!