decidim-toggle 0.1.3

data/website/docs/integrate/customize-views.md

@@ -0,0 +1,62 @@
+---
+sidebar_position: 6
+title: Customize views
+description: form_layout_partial for custom settings tab layouts
+---
+
+# Customize views
+
+Without `form_layout_partial:`, decidim-toggle renders every form attribute through the default shell (`all_fields` + submit). For custom markup, provide a full tab layout partial.
+
+## Default vs custom
+
+| | Default | `form_layout_partial:` |
+|---|---------|------------------------|
+| When | Simple JSON-backed settings | Tables, fieldsets, reused decidim-system partials, mixed markup |
+| Locals | — | `tab`, `organization` |
+| You render | Nothing — toggle uses `all_fields` | Entire tab inside `decidim_toggle_settings_tab_form` |
+
+Built-in examples: `lib/decidim/toggle/organization_settings_tabs.rb` and `app/views/decidim_toggle/system/organizations/tabs/`.
+
+## Custom tab layout
+
+```erb
+<%# app/views/decidim/my_module/admin/_organization_settings_tab.html.erb %>
+<%= decidim_toggle_settings_tab_form(organization, tab) do |tf| %>
+  <fieldset>
+    <legend class="form-legend">My module</legend>
+    <%= tf.fields_for_names(:enabled) %>
+  </fieldset>
+<% end %>
+```
+
+```ruby
+tabs.add_tab :my_module,
+             "My module",
+             form: MyModule::AdminConfigForm,
+             command: Decidim::Toggle::UpdateModuleConfigCommand,
+             module_name: :my_module,
+             form_layout_partial: "decidim/my_module/admin/organization_settings_tab"
+```
+
+`decidim_toggle_settings_tab_form` provides the PATCH form, hidden active-tab field, informative callouts, and save/cancel buttons. Do not drop the hidden `decidim_toggle_active_tab` field.
+
+Use `tf` (`Decidim::Toggle::SettingsFormBuilder`) for fields — `tf.all_fields`, `tf.fields_for_names(:enabled)`, or pass `f: tf` to existing partials.
+
+## Reuse decidim-system partials
+
+```erb
+<%= decidim_toggle_settings_tab_form(organization, tab) do |tf| %>
+  <%= render "decidim/system/organizations/smtp_settings", f: tf %>
+<% end %>
+```
+
+See `tabs/_emails_tab.html.erb` and `tabs/_file_upload_tab.html.erb` in this gem.
+
+## See also
+
+- [Attributes](./attributes.md) — `fields_for_names`, helptext
+- [Informative callouts](./informative_callout.md)
+- [Add a settings tab](./quickstart.md)
+- [JavaScript](./javascript.md)
+- [View customization (contributor)](../developer/view-customization.md) — internal gem views

data/website/docs/integrate/index.md

@@ -0,0 +1,38 @@
+---
+sidebar_position: 1
+title: Integrate
+description: Add organization settings from your Decidim module
+---
+
+# Integrate your module
+Three steps to ship a settings tab: register the tab, declare form attributes, optionally customize the view.
+
+## 1. Add a tab
+
+Register a form and command in your engine after `decidim_toggle.organization_settings_tabs`.
+
+→ [Add a settings tab](./quickstart.md)
+
+## 2. Define attributes and validation
+
+Declare fields on your `Decidim::Form` — booleans, collections, translatable fields. Field labels live under `decidim_toggle.system.<module_config_name>` — see [Labels](./labels.md).
+
+→ [Attributes](./attributes.md) · [Labels](./labels.md) · [Informative callouts](./informative_callout.md) (optional)
+
+## 3. Customize the form view (optional)
+
+Default rendering uses `all_fields`. Override with `form_layout_partial:` when you need custom markup.
+
+→ [Customize views](./customize-views.md)
+
+## Optional: JavaScript exposure
+
+Expose selected settings to `window.DecidimToggle` on the participant and admin frontends.
+
+→ [JavaScript](./javascript.md)
+
+## See also
+
+- [Overview](../index.md)
+- [Contribute](../developer/contribute.md) — hacking the gem itself
+- [GitLab issues](https://git.octree.ch/decidim/vocacity/decidim-modules/decidim-toggle/-/issues)

data/website/docs/integrate/informative_callout.md

@@ -0,0 +1,80 @@
+---
+sidebar_position: 5
+title: Informative callouts
+description: info, warning, and danger callouts on settings tab forms
+---
+
+# Informative callouts
+
+Show info, warning, or danger banners **above** the tab field body, inside the shared form shell (submit + active-tab field unchanged).
+
+![Informative Callouts](/img/screenshot_informative_callouts.png)
+
+## Setup
+
+Include `Decidim::Toggle::TabForm` (recommended) or `Decidim::Toggle::InformativeCallouts` on the form class:
+
+```ruby
+module MyModule
+  class AdminConfigForm < Decidim::Form
+    include Decidim::Toggle::TabForm
+    include Decidim::Toggle::ModuleConfigForm
+
+    self.module_config_name = "my_module"
+    mimic :organization
+
+    attribute :enabled, :boolean
+
+    info :defaults_callout
+
+    info :installed_modules_callout,
+         if_predicate: ->(form) { form.missing_modules.any? }
+
+    warning :disable_warning_callout,
+            if_predicate: ->(form) { form.enabled == false }
+
+    danger :other_gem_required_callout,
+           if_predicate: ->(*) { Decidim::Toggle.gem_present?("decidim-other") }
+
+    def defaults_callout
+      "Defaults apply to new organizations only."
+    end
+
+    def installed_modules_callout
+      I18n.t("my_module.admin.missing_modules", missing: missing_modules.join(", "))
+    end
+
+    def disable_warning_callout
+      "Disabling removes public access to #{module_label}."
+    end
+
+    def other_gem_required_callout
+      "Requires decidim-other in the Gemfile."
+    end
+  end
+end
+```
+
+## Macros
+
+| Macro | Style | When to use |
+|-------|-------|-------------|
+| `info :method_name` | Info (blue) | Context from a form instance method (HTML allowed) |
+| `warning :method_name, if_predicate:` | Warning (yellow) | Reversible caution before save |
+| `danger :method_name, if_predicate:` | Alert (red) | Strong caution, destructive or risky change |
+
+The first argument is a **Symbol** naming a method on the form (`form.public_send(symbol)`).
+
+`if_predicate` receives the form instance; omit it to always show the callout.
+
+## Rendering
+
+Callouts render via `SettingsFormBuilder#informative_callouts` inside `decidim_toggle_settings_tab_form` — **above** the field body.
+
+They appear in `form_layout_partial:` tabs when you wrap fields with `decidim_toggle_settings_tab_form`.
+
+## See also
+
+- [Attributes](./attributes.md)
+- [Customize views](./customize-views.md)
+- [Add a settings tab](./quickstart.md)

data/website/docs/integrate/javascript.md

@@ -0,0 +1,84 @@
+---
+sidebar_position: 7
+title: JavaScript
+description: Expose organization settings to window.DecidimToggle
+---
+
+# JavaScript
+
+Opt in per attribute to expose config on `window.DecidimToggle`. By default, settings stay server-side (`Decidim::Toggle.config_for`).
+
+## Opt in on the form
+
+Include `Decidim::Toggle::ExposeAttributesToJs` and list attributes explicitly — secrets are **not** exposed unless you add them.
+
+```ruby
+module MyModule
+  class AdminConfigForm < Decidim::Form
+    include Decidim::Toggle::TabForm
+    include Decidim::Toggle::ModuleConfigForm
+    include Decidim::Toggle::ExposeAttributesToJs
+
+    self.module_config_name = "my_module"
+    mimic :organization
+
+    attribute :enabled, :boolean
+    attribute :search_bar, :boolean
+    attribute :api_key, :string
+
+    expose_to_javascript :enabled, :search_bar
+    # api_key is intentionally omitted
+  end
+end
+```
+
+| Macro | Role |
+|-------|------|
+| `expose_to_javascript :attr, ...` | Registers attribute names for the current organization's config |
+
+The tab must be registered with `module_name:` matching `module_config_name` so `config_for` can resolve values.
+
+## Key format
+
+Flat string keys: `"<module_config_name>.<attribute_name>"`.
+
+```js
+if (window.DecidimToggle["my_module.enabled"]) {
+  document.querySelector(".search-bar")?.classList.remove("hidden");
+}
+```
+
+## Supported value types
+
+Serialized into JSON-safe values:
+
+| Type | Exposed as |
+|------|------------|
+| boolean | `true` / `false` |
+| string, integer, float | scalar |
+| array | JSON array (elements stringified when needed) |
+| hash | plain object (keys stringified) |
+| translatable attribute | raw locale hash (`{ "en": "...", "ca": "..." }`) |
+
+Unsupported types are skipped (development/test may log a warning via `ExposeAttributesToJsValidator`).
+
+## Server-side read
+
+Browser and server use the same underlying config:
+
+```ruby
+Decidim::Toggle.config_for(organization, :my_module)[:enabled]
+Decidim::Toggle.javascript_config_for(organization) # => { "my_module.enabled" => true, ... }
+```
+
+`javascript_config_for` aggregates every registered form that includes `ExposeAttributesToJs`.
+
+## How it reaches the page
+
+Deface overrides insert `layouts/decidim/toggle/javascript_config` into decidim-core layouts.
+
+## See also
+
+- [Attributes](./attributes.md)
+- [Add a settings tab](./quickstart.md)
+- [Deface usage](../developer/deface-usage.md)

data/website/docs/integrate/labels.md

@@ -0,0 +1,91 @@
+---
+sidebar_position: 4
+title: Labels
+description: Field labels and helptext for module config tabs
+---
+
+# Labels
+
+Forms that include `Decidim::Toggle::ModuleConfigForm` resolve **field labels**, **helptext**, and the **tab title** from `decidim_toggle.system.<module_name>`.
+
+## Module name
+
+Define one constant in your module and reuse it everywhere:
+
+```ruby
+# lib/decidim/my_module.rb
+module Decidim
+  module MyModule
+    MODULE_NAME = "my_module"
+  end
+end
+```
+
+```ruby
+# app/forms/my_module/admin_config_form.rb
+self.module_config_name = Decidim::MyModule::MODULE_NAME
+
+# lib/decidim/my_module/engine.rb
+tabs.add_tab :my_module,
+             I18n.t("decidim_toggle.system.#{Decidim::MyModule::MODULE_NAME}.tab"),
+             form: MyModule::AdminConfigForm,
+             command: Decidim::Toggle::UpdateModuleConfigCommand,
+             module_name: Decidim::MyModule::MODULE_NAME
+```
+
+`module_config_name`, `module_name:` on `add_tab`, and the locale path must all match.
+
+## Locale files
+
+Keep toggle strings in dedicated files — one per locale:
+
+```
+config/locales/decidim_toggle.en.yml
+config/locales/decidim_toggle.fr.yml
+```
+
+```yaml
+# config/locales/decidim_toggle.en.yml
+en:
+  decidim_toggle:
+    system:
+      my_module:
+        tab: My module
+        enabled: Enable my module
+        helptext:
+          enabled: Applies to this organization only.
+```
+
+| Key | Use |
+|-----|-----|
+| `tab` | Tab button label (`I18n.t("decidim_toggle.system.<module_name>.tab")`) |
+| `<attribute>` | Field label (via `ModuleConfigForm`) |
+| `helptext.<attribute>` | Optional help copy under a field |
+
+Field labels use:
+
+`decidim_toggle.system.<module_name>.<attribute>`
+
+## Helptext
+
+Optional copy under a field uses a `helptext` sub-key in the same module scope:
+
+`decidim_toggle.system.<module_name>.helptext.<attribute>`
+
+## Custom labels
+
+Override only when you need an exception:
+
+```ruby
+def self.human_attribute_name(attr, options = {})
+  return "Special case" if attr == :legacy_flag
+
+  super
+end
+```
+
+## See also
+
+- [Add a settings tab](./quickstart.md)
+- [Attributes](./attributes.md)
+- [Customize views](./customize-views.md)

data/website/docs/integrate/quickstart.md

@@ -0,0 +1,77 @@
+---
+sidebar_position: 2
+title: Add a settings tab
+description: Form, engine registration, verify
+---
+
+# Add a settings tab
+
+Register a form and command, then verify persistence.
+
+## 1. Form
+
+```ruby
+# app/forms/my_module/admin_config_form.rb
+module MyModule
+  class AdminConfigForm < Decidim::Form
+    include Decidim::Toggle::ModuleConfigForm
+
+    self.module_config_name = Decidim::MyModule::MODULE_NAME
+
+    mimic :organization
+
+    attribute :enabled, :boolean
+  end
+end
+```
+
+## 2. Register tab
+
+In your module engine, **after** `decidim_toggle.organization_settings_tabs`:
+
+```ruby
+# lib/decidim/my_module/engine.rb
+initializer "decidim_my_module.organization_settings_tab", after: "decidim_toggle.organization_settings_tabs" do
+  Decidim::Toggle.settings_tabs :organization_settings do |tabs|
+    tabs.add_tab :my_module,
+                 I18n.t("decidim_toggle.system.#{Decidim::MyModule::MODULE_NAME}.tab"),
+                 form: MyModule::AdminConfigForm,
+                 command: Decidim::Toggle::UpdateModuleConfigCommand,
+                 module_name: Decidim::MyModule::MODULE_NAME,
+                 position: 10
+  end
+end
+```
+
+| Option | Role |
+|--------|------|
+| `module_name:` | JSON row key; must match `module_config_name` on the form |
+| `position:` | Tab order (default: append) |
+| `open:` | Open this panel by default |
+| `if:` | Hide tab when false |
+| `form_layout_partial:` | Custom tab layout — [Customize views](./customize-views.md) |
+
+## 3. Verify
+
+1. Boot the host app.
+2. **System → Organizations → Edit** → open **My module**.
+3. Toggle **enabled**, save.
+4. Console: `Decidim::Toggle.config_for(organization, :my_module)[:enabled]`
+
+## Read / write config
+
+```ruby
+Decidim::Toggle.config_for(organization, :my_module)
+Decidim::Toggle.save_config!(organization, :my_module, { "enabled" => true })
+```
+
+## Organization columns
+
+When settings live on `Decidim::Organization` (SMTP, host, locales, …), use a custom `Decidim::Form` + custom `Decidim::Command` with the same `add_tab` contract. See built-in tabs in `lib/decidim/toggle/organization_settings_tabs.rb`.
+
+## See also
+
+- [Integrate](./index.md)
+- [Attributes](./attributes.md)
+- [Informative callouts](./informative_callout.md)
+- [Customize views](./customize-views.md)

data/website/docusaurus.config.ts

@@ -0,0 +1,100 @@
+import {themes as prismThemes} from 'prism-react-renderer';
+import type {Config} from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const config: Config = {
+  title: 'Decidim Toggle',
+  tagline: 'Tabbed System administration — register org settings from your Decidim module',
+  favicon: 'img/logo.svg',
+
+  url: 'https://octree.ch',
+  baseUrl: '/decidim-toggle/',
+  trailingSlash: false,
+
+  organizationName: 'octree-gva',
+  projectName: 'decidim-toggle',
+
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          sidebarPath: './sidebars.ts',
+          routeBasePath: '/',
+        },
+        theme: {
+          customCss: './src/css/custom.css',
+        },
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  themeConfig: {
+    navbar: {
+      title: 'Decidim Toggle',
+      items: [
+        {
+          type: 'docSidebar',
+          sidebarId: 'tutorialSidebar',
+          position: 'left',
+          label: 'Documentation',
+        },
+        {
+          href: 'https://git.octree.ch/decidim/vocacity/decidim-modules/decidim-toggle',
+          label: 'GitLab',
+          position: 'right',
+        },
+      ],
+    },
+    footer: {
+      style: 'dark',
+      links: [
+        {
+          title: 'Docs',
+          items: [
+            {
+              label: 'Overview',
+              to: '/',
+            },
+            {
+              label: 'Integrate',
+              to: '/integrate',
+            },
+            {
+              label: 'Contribute',
+              to: '/contributing',
+            },
+            {
+              label: 'Code of conduct',
+              to: '/code-of-conduct',
+            },
+          ],
+        },
+        {
+          title: 'More',
+          items: [
+            {
+              label: 'GitLab',
+              href: 'https://git.octree.ch/decidim/vocacity/decidim-modules/decidim-toggle',
+            },
+          ],
+        },
+      ],
+      copyright: 'Built with Docusaurus. Powered by <a href="https://voca.city">Voca</a>.',
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+    },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;

data/website/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "decidim-toggle-website",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "clear": "docusaurus clear",
+    "serve": "docusaurus serve",
+    "typecheck": "tsc"
+  },
+  "dependencies": {
+    "@docusaurus/core": "3.5.2",
+    "@docusaurus/preset-classic": "3.5.2",
+    "@mdx-js/react": "^3.0.0",
+    "clsx": "^2.0.0",
+    "prism-react-renderer": "^2.3.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "3.5.2",
+    "@docusaurus/tsconfig": "3.5.2",
+    "@docusaurus/types": "3.5.2",
+    "typescript": "~5.5.2"
+  },
+  "engines": {
+    "node": ">=18.0"
+  }
+}

data/website/sidebars.ts

@@ -0,0 +1,7 @@
+import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+
+const sidebars: SidebarsConfig = {
+  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
+};
+
+export default sidebars;

data/website/src/css/custom.css

@@ -0,0 +1,37 @@
+/**
+ * Any CSS included here will be global. The classic template
+ * bundles Infima by default. Infima is a CSS framework designed to
+ * work well for content-centric websites.
+ */
+
+/* You can override the default Infima variables here. */
+:root {
+  --ifm-color-primary: #2e8555;
+  --ifm-color-primary-dark: #29784c;
+  --ifm-color-primary-darker: #277148;
+  --ifm-color-primary-darkest: #205d3b;
+  --ifm-color-primary-light: #33925d;
+  --ifm-color-primary-lighter: #359962;
+  --ifm-color-primary-lightest: #3cad6e;
+  --ifm-code-font-size: 95%;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
+}
+
+/* For readability concerns, you should choose a lighter palette in dark mode. */
+[data-theme='dark'] {
+  --ifm-color-primary: #25c2a0;
+  --ifm-color-primary-dark: #21af90;
+  --ifm-color-primary-darker: #1fa588;
+  --ifm-color-primary-darkest: #1a8870;
+  --ifm-color-primary-light: #29d5b0;
+  --ifm-color-primary-lighter: #32d8b4;
+  --ifm-color-primary-lightest: #4fddbf;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
+}
+
+img{
+  max-width:520px; 
+}
+.full > p > img {
+  max-width: 100%;;
+}

data/website/static/img/logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="currentColor"><path d="M8.00008 6V9H5.00008V6H8.00008ZM3.00008 4V11H10.0001V4H3.00008ZM13.0001 4H21.0001V6H13.0001V4ZM13.0001 11H21.0001V13H13.0001V11ZM13.0001 18H21.0001V20H13.0001V18ZM10.7072 16.2071L9.29297 14.7929L6.00008 18.0858L4.20718 16.2929L2.79297 17.7071L6.00008 20.9142L10.7072 16.2071Z"></path></svg>

data/website/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@docusaurus/tsconfig",
+  "compilerOptions": {
+    "baseUrl": "."
+  }
+}