From a1f37502c9d0a470319f23391b2269fece2090f7 Mon Sep 17 00:00:00 2001 From: tinycarol Date: Thu, 28 Oct 2021 18:05:25 +0200 Subject: [PATCH 1/2] docs(guidelines): add namespacing guidelines for DXP --- guidelines/dxp/namespacing.md | 57 +++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 guidelines/dxp/namespacing.md diff --git a/guidelines/dxp/namespacing.md b/guidelines/dxp/namespacing.md new file mode 100644 index 0000000000..a787b55415 --- /dev/null +++ b/guidelines/dxp/namespacing.md @@ -0,0 +1,57 @@ +# Namespacing guidelines + +To promote consistency, we have established the following rule of thumb for namespacing in DXP: + +* Unique attributes, such as `id`s, should *not* be namespaced +* Non-unique attributes, such as `name`, should be namespaced +* Fallback: if `id` is not passed, default to using `name` as `id` + +## Reasoning + +The purpose of the `id` attribute is to define something unique to the whole page. By following this approach, we ensure that these attributes can be used in methods such as `document.getElementById` as is, without juggling namespaces. + +Other attributes, such as `name`, only need to be unique for some internal mechanism, such as in a `form` element. By namespacing them internally we ensure that, in case they end up being used under the hood as `id`s, they won't bleed into other components and cause duplicate issues. + +## Examples + +### Unique attributes + +Take the following snippet: + +```html + + + +``` + +The `clay:headless-data-set-display` element receives the `id` of its wrapping form as a `formId` attribute. This `id` **doesn't include the namespace**, and should not be namespaced inside the form taglib. The `clay:headless-data-set-display` component can now internally use `document.getElementById(formId)` to interact with the form when necessary, without adding the `namespace` before it, because the resulting HTML for the `form` would be as follows: + +```html +
+ ... +
+``` + +### Non-unique attributes + +Take this other example: + +```html + + + +``` + +In this case, the `form` tag has a `name` attribute, which **will be namespaced under the hood**. Since we aren't passing an `id` prop, the component must use the fallback case and use the `name` as an `id`, resulting in the following HTML: + +```html +
+ ... +
+``` + +In this case, for the `clay:headless-data-set-display`, we are passing the `formName` prop instead of `id`. The component must namespace the `formName` attribute to find the element on the page, as such: + +```js +const formElement = document.getElementById(`${namespace}${formName}`); +``` From c7d4bcbf5bc3c89cee34a06156b84443ead60c52 Mon Sep 17 00:00:00 2001 From: tinycarol Date: Thu, 28 Oct 2021 18:16:12 +0200 Subject: [PATCH 2/2] fix: format --- guidelines/dxp/namespacing.md | 20 ++++++++------------ 1 file changed, 8 insertions(+), 12 deletions(-) diff --git a/guidelines/dxp/namespacing.md b/guidelines/dxp/namespacing.md index a787b55415..02517ea05c 100644 --- a/guidelines/dxp/namespacing.md +++ b/guidelines/dxp/namespacing.md @@ -2,13 +2,13 @@ To promote consistency, we have established the following rule of thumb for namespacing in DXP: -* Unique attributes, such as `id`s, should *not* be namespaced -* Non-unique attributes, such as `name`, should be namespaced -* Fallback: if `id` is not passed, default to using `name` as `id` +- Unique attributes, such as `id`s, should _not_ be namespaced +- Non-unique attributes, such as `name`, should be namespaced +- Fallback: if `id` is not passed, default to using `name` as `id` ## Reasoning -The purpose of the `id` attribute is to define something unique to the whole page. By following this approach, we ensure that these attributes can be used in methods such as `document.getElementById` as is, without juggling namespaces. +The purpose of the `id` attribute is to define something unique to the whole page. By following this approach, we ensure that these attributes can be used in methods such as `document.getElementById` as is, without juggling namespaces. Other attributes, such as `name`, only need to be unique for some internal mechanism, such as in a `form` element. By namespacing them internally we ensure that, in case they end up being used under the hood as `id`s, they won't bleed into other components and cause duplicate issues. @@ -20,16 +20,14 @@ Take the following snippet: ```html - + ``` The `clay:headless-data-set-display` element receives the `id` of its wrapping form as a `formId` attribute. This `id` **doesn't include the namespace**, and should not be namespaced inside the form taglib. The `clay:headless-data-set-display` component can now internally use `document.getElementById(formId)` to interact with the form when necessary, without adding the `namespace` before it, because the resulting HTML for the `form` would be as follows: ```html -
- ... -
+
...
``` ### Non-unique attributes @@ -38,16 +36,14 @@ Take this other example: ```html - + ``` In this case, the `form` tag has a `name` attribute, which **will be namespaced under the hood**. Since we aren't passing an `id` prop, the component must use the fallback case and use the `name` as an `id`, resulting in the following HTML: ```html -
- ... -
+
...
``` In this case, for the `clay:headless-data-set-display`, we are passing the `formName` prop instead of `id`. The component must namespace the `formName` attribute to find the element on the page, as such: