Merge branch 'master' into feature/24734-mr-environments

docs/panel/Plugins/Custom-links.md

@@ -6,27 +6,35 @@ Thanks to this link, you will be able to get easy access to the preview of where
 
 ## Installing the Custom Links plugin
 
-Open up your profile menu and select `Plugins`.
+Find in the right sidebar panel `Plugins` and select.
 
-![Flotiq plugins](images/profile-plugins.png){: .center .width25 .border}
+![Flotiq plugins](images/sidebar-plugins.png){: .center .width25 .border}
 
-On the next screen, click on the `Add to your plugins` button next to `Custom Links`.
+On the next screen, click the plus icon next to `Custom Links` to install and enable the plugin.
 
-![Adding Custom Links plugin to Flotiq](images/plugins-custom-links-1.png){: .center .width75 .border}
+![Install Custom Links plugin](images/custom-links/install.png){: .center .width75 .border}
 
-Next - fill in the details and click `Save changes` to finish your plugin setup.
+Once the plugin is enabled, click `Manage` to open the modal with the form.
 
-![Setting up Custom Links in Flotiq](images/plugins-custom-links-2.png){: .center .width75 .border}
+![Manage Custom Links](images/custom-links/manage.png){: .center .width75 .border}
 
-* URL Template - It's a place to enter the link template, e.g. `https://my-blog/post/{slug}`, where `slug` is the name of the content field of the type selected below. Instead of `{slug}`, you can use any field of a given content type, it is also possible to use nesting, e.g. `{internal.createdAt}`. However, the use of list type fields is not supported.
+After the modal is opened, click `Add item`.
 
-* Displayed Name Template - Any name that will be displayed on the link button.
+![Add Custom Link](images/custom-links/add.png){: .center .width75 .border}
 
-* Content Type Definition - Select the content type to display the button only for the specified content type. If the content type is not selected, the button will be shown when editing each content object.
+Next, fill in the details and click `Save changes` to complete your plugin setup.
 
-You're done. Now you will see `Link to current post` in Content Objects forms, the button  `https://my-blog/post/first-post`.
+![Setting up Custom Links in Flotiq](images/custom-links/simple-link.png){: .center .width75 .border}
 
-![Custom links button in Flotiq editor](images/plugins-custom-links-3.png){: .center .width50 .border}
+* URL template - It's a place to enter the link template, e.g. `https://my-blog/post/{slug}`, where `slug` is the name of the content field of the type selected below. Instead of `{slug}`, you can use any field of a given content type, it is also possible to use nesting, e.g. `{internal.createdAt}`. You can also use list fields: `{addresses[0].city}`.
+
+* Link name template - Any name that will be displayed on the link button.
+
+* Content types - Select the content types to display the button only for the specified content types. If the content types are not selected, the button will be shown when editing each content object.
+
+You're done. Now you will see `Example page` in Content Objects forms with `http://example.com/` link.
+
+![Custom links button in Flotiq editor](images/custom-links/simple-link-co-form.png){: .center .width100 .border}
 
 
 ## Examples
@@ -35,16 +43,22 @@ You're done. Now you will see `Link to current post` in Content Objects forms, t
 
 One of the most common use cases for using this plugin is to add a direct link to a preview/staging environment  directly from the editor. Here's how you could set that up:
 
-![Custom links plugin configuration for linking to a preview environment](images/plugins-custom-links-4.png){: .center .width50 .border}
+![Custom links plugin configuration for linking to a preview environment](images/custom-links/simple-routing.png){: .center .width75 .border}
+
+if you use this configuration with an object similar to this
+
+![Content object with category and slug](images/custom-links/simple-routing-co-form.png){: .center .width100 .border}
+
+you will see the `first-page` link that will lead you to `https://my-blog/post/first-page`.
 
 ### Creating links to pages using complex routing
 
 Here's a bit more complex example, where the page routing requires to provide a URL with the name of a category *and* a slug of the current page:
 
-![Custom links plugin with a more complex routing](images/plugins-custom-links-5.png){: .center .width50 .border}
+![Custom links plugin with a more complex routing](images/custom-links/complex-routing.png){: .center .width75 .border}
 
 if you use this configuration with an object similar to this
 
-![Content object with category and slug](images/plugins-custom-links-6.png){: .center .width50 .border}
+![Content object with category and slug](images/custom-links/complex-routing-co-form.png){: .center .width100 .border}
 
-you will see a preview link that will lead you to `https://staging.site.com/office/best-office-chair`.
+you will see a preview link that will lead you to `https://my-site.com/office/best-office-chair`.

docs/panel/Plugins/Slug.md

@@ -0,0 +1,38 @@
+title: Slug | Flotiq documentation
+description: This plugin simplifies the process of creating slugs for your Content Object.
+
+# Slug generation plugin
+
+This plugin simplifies the process of creating slugs for your Content Object. It’s particularly useful when you want to generate slugs automatically based on existing data within a Content Object (e.g. the title of a blog post).
+
+## Installing the Slug plugin
+
+Find in the right sidebar panel `Plugins` and select.
+
+![Flotiq plugins](images/sidebar-plugins.png){: .center .width25 .border}
+
+On the next screen, click the plus icon next to `Slug` to install and enable the plugin.
+
+![Install Slug plugin](images/slug/install.png){: .center .width75 .border}
+
+Once the plugin is enabled, click `Manage` to open the modal with the form.
+
+![Manage Slug](images/slug/manage.png){: .center .width75 .border}
+
+After the modal is opened, click `Add`.
+
+![Add Slug](images/slug/add.png){: .center .width75 .border}
+
+Next, fill in the details and click `Save changes` to complete your plugin setup.
+
+![Setting up Slug in Flotiq](images/slug/settings.png){: .center .width75 .border}
+
+* Content Type - Defines the type of objects for which the slug will be generated.
+
+* Slug source field - Determines the field on which the slug will be based.
+
+* Target field - Specifies the field to which the slug will be entered.
+
+You're done. Now you will see the refresh icon next to the slug field in the Content Object form. If you’re creating a new object and the field is currently empty, it will be auto-filled. If you’re editing an existing object or the field contains data, click the refresh icon to regenerate the slug.
+
+![Slug outcome](images/slug/outcome.png){: .center .width75 .border}

docs/panel/PluginsDevelopment/plugin-examples.md

@@ -186,21 +186,19 @@ FlotiqPlugins.add(
     handler.on(
       `flotiq.grid.cell::render`,
       ({ data, contentType, accessor }) => {
-        if (contentType.name !== 'blogpost') return;
-        if (accessor === 'title') {
-          const titleSpan = document.createElement('span');
-          titleSpan.textContent = data;
+        if (contentType.name !== 'blogpost' || accessor !== 'title') return;
 
-          titleSpan.addEventListener('flotiq.attached', () => {
-            const parentWidth = Math.round(
-              titleSpan.parentElement.getBoundingClientRect().width,
-            );
+        const titleSpan = document.createElement('span');
+        titleSpan.textContent = data;
 
-            titleSpan.innerHTML = `${data} <span style="font-size: 0.9em; color: gray;">(${parentWidth} px)</span>`;
-          });
-          return titleSpan;
-        }
-        return null;
+        titleSpan.addEventListener('flotiq.attached', () => {
+          const parentWidth = Math.round(
+            titleSpan.parentElement.getBoundingClientRect().width,
+          );
+
+          titleSpan.innerHTML = `${data} <span style="font-size: 0.9em; color: gray;">(${parentWidth} px)</span>`;
+        });
+        return titleSpan;
       },
     );
   },
@@ -212,6 +210,47 @@ Result:
 
 ![Title width added to the object data table](img/title-width-plugin.png)
 
+## Clear global counter after element is detached
+
+In some cases, you may need to know when element is detached from the DOM tree. To be able to act immediately after the element is detached, you can use `flotiq.detached` html event. 
+
+Here we clear the global counter after element is detached:
+
+```javascript
+let counter = 0;
+
+FlotiqPlugins.add(
+  {
+    id: 'mycompany.click-counter',
+    name: `Count clicks on the blog post titles`,
+    version: `1.0.0`,
+  },
+  function (handler) {
+    handler.on(
+      `flotiq.grid.cell::render`,
+      ({ data, contentType, accessor }) => {
+        if (contentType.name !== 'blogpost' || accessor !== 'title') return;
+
+        const button = document.createElement('button');
+        button.textContent = `${data} (${counter})`;
+
+        button.addEventListener('click', () => {
+          counter++;
+          button.textContent = `${data} (${counter})`;
+        });
+
+        button.addEventListener('flotiq.detached', () => {
+          counter = 0;
+        });
+
+        return button;
+      },
+    );
+  },
+);
+```
+{ data-search-exclude }
+
 ## Open custom modal 
  
 Open the modal by clicking on the grid ID cell.

docs/panel/PluginsDevelopment/plugins.md

@@ -293,6 +293,24 @@ return element;
 ```
 { data-search-exclude }
 
+### Acting when an element is detached from the DOM tree
+
+If you want to do something after detaching an element from the DOM tree (e.g. clear the element cache), you can use `flotiq.detached` DOM event.
+
+**Important**: This event is only fired on the root element returned by the plugin. Elements inside will not receive this event.
+
+```javascript
+const element = document.createElement('span');
+element.addEventListener('flotiq.detached', () => { 
+  console.log('element removed'); // will be fired after element is detached
+});
+return element;
+```
+{ data-search-exclude }
+
+!!! note "Multiple attaches/detaches"
+    Your HTML element may be attached and detached multiple times, depending on the view and place being rendered. Be prepared to handle those situations accordingly. E.g. if you keep your elements in a cache across multiple renders, consider waiting at least 50ms before the element is removed from the cache.
+
 ## Plugin Installation
 
 Once you have your plugin written, you have several options to install it into Flotiq UI. Multiple instances of the plugin with the same `id` will override each other, so you can easily update your plugin as needed.

mkdocs.yml

@@ -159,6 +159,7 @@ nav:
       - 'Gatsby Cloud': panel/Plugins/Gatsby-cloud-integration.md
       - 'Netlify': panel/Plugins/Netlify-integration.md
       - 'Custom Links': panel/Plugins/Custom-links.md
+      - 'Slug': panel/Plugins/Slug.md
     - UI Plugins Development:
       - 'Getting started': panel/PluginsDevelopment/plugins.md
       - 'Examples': panel/PluginsDevelopment/plugin-examples.md