formblocks 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2b04f8207b4d1d2916bf97d98dc73087aac5362d5062595e8db6825f7be7e7e
-  data.tar.gz: 0b865be55ddc3b825e4a514fac4978d7f097c6ec92aa93802578cc07ea08a5e1
+  metadata.gz: 58b538400d1acd9446a373f91ad583583492ac7c5d332c93c7f590ef05a11532
+  data.tar.gz: c8754c9251ef9da026d6ef89a4be9fdc7f849a17c363e17a84bffd0f01106564
 SHA512:
-  metadata.gz: f4fd405a7e97b459806ad8ee1dea28ad19ef55775bac6b12d46516caa1c745b6577a7b774f894cc5de5ea0853b1dec6b0fd0fe7c7e24e4a4a93de7cb4eb923aa
-  data.tar.gz: dfe1386a1db2f2b62271c0ba003366cc8a9c8e700528deb619c979c1703b2068c235e90240f63fd039c8afe38f69f58e72777b53afab016549968333060b96f8
+  metadata.gz: 3945e16fda92efb229e3c1f202263c3d0e94660793b73298ec1638dc66428eccfaf3395d237459895356a7778b1ab236e67df55ef2923b1a925deb4042c48f6d
+  data.tar.gz: 242d28a57564446c31c3d485a7863a86254f5bd972b8a4f6f7327c3cb8f5cc7adb1092c403564caa2cdbcf52e98d2786affcb399042e900e377bad3bacc94759

data/AGENTS.md

@@ -26,6 +26,12 @@ Reach the admin at the mount path and published forms at
 `formblocks_form_path(slug)`; the engine's own helpers are under the
 `formblocks` route proxy (`formblocks.root_path`).
 
+To link to a form with fields filled in advance, hidden or visible, pass the
+answers by key through `Formblocks.prefill`:
+`formblocks_form_path(slug, Formblocks.prefill(slug, user_id: user.id))`. The
+URL then carries each field's opaque ID, not its key. Do not hard-code IDs
+copied from the builder into host code — they differ per database.
+
 ## Working on the gem
 
 - `bin/rails server` runs the dummy app in `test/dummy` (admin at

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.2 — 2026-09-18
+
+- Prefill for every input, not only hidden fields: a query parameter on the
+  public URL fills a text, email, textarea, radio group or checkbox the same
+  way it fills a hidden field.
+- Field IDs: every input has a short opaque ID (`Block#public_id`), and
+  `?<id>=value` fills it, so a link no longer has to show what its fields are
+  called. **Copy ID** on a block in the builder copies it. The plain key
+  (`?utm_source=newsletter`) keeps working.
+- `Formblocks.prefill(slug, key: value)` turns keys into IDs for a link built
+  in a host view: `formblocks_form_path(slug, Formblocks.prefill(slug, …))`.
+- The builder shows **Field name** (the key) on every input, not only on
+  hidden fields, and it can be renamed there.
+- Fixed: a hidden field whose key matched a route parameter (`slug`) was
+  filled with that parameter. Only the query string is read now.
+
 ## 0.1.1 — 2026-09-15
 
 - Responses: a URL answer that points at an image (an image file extension, or

data/README.md

@@ -77,6 +77,7 @@ any app that bundles it.
 | **Multi-page**   | Every form has at least one step and a thank-you page; add steps as you like      |
 | **Templates**    | Blank, contact, lead capture, feedback — or your own hashes. Duplicate any form    |
 | **Public page**  | One step at a time, browser validation, server validation with inline errors      |
+| **Prefill**      | Fill any field from the link, hidden or visible, under opaque field IDs — the URL never says what a field is called |
 | **Responses**    | A dashboard per form, one response in full, CSV export, an `on_submit` hook       |
 | **Branding**     | Logo, primary color, button text color — per form, inherited from global settings |
 | **Deps**         | Rails, `turbo-rails`, `stimulus-rails`. No asset pipeline, no bundler, no build step |
@@ -197,13 +198,14 @@ inheritance, so `Email < Text < Input < Block`:
 | `image` | — | An upload; `label` is the alt text |
 | `name`, `email`, `phone`, `url`, `text` | a string | Single-line inputs with the right `type` and `autocomplete`; email and URL are validated |
 | `textarea` | a string | Multi-line |
-| `hidden` | a string | `key` is the field name, `content` the default; `?key=value` on the public URL overrides it |
+| `hidden` | a string | `key` is the field name, `content` the default; the link to the form can override it — see [Filling fields from the URL](#filling-fields-from-the-url) |
 | `checkbox` | `true`/`false` | Required means it must be ticked |
 | `radio_group` | one of `options` | One option per line in the builder |
 
 Every input has a **key** — from its label when it is created ("Work email"
 → `work_email`), unique within the form, and stable afterwards even if the
-label changes. Answers are stored under it: `response.answers["work_email"]`.
+label changes; **Field name** in the builder renames it. Answers are stored
+under it: `response.answers["work_email"]`.
 
 <details>
 <summary><b>Your own block</b></summary>
@@ -282,6 +284,43 @@ required fields, email and URL formats, radio options, required checkboxes —
 and re-rendered with an error under each field. The slug is yours to set in
 the form's settings; it is generated from the title otherwise.
 
+### Filling fields from the URL
+
+A link can carry answers with it: who is asking, which plan they are on, the
+email you already know. Every input — hidden or visible — has an **ID**, a
+short opaque string, and a query parameter with that name fills the field:
+
+```
+/f/feedback?515e541fe571=7&d42b3cfb4220=ada%40example.com
+```
+
+The visitor sees the values, not what they are stored as. **Copy ID** on a
+block in the builder gives you its ID; it stays the same for the life of the
+block, whatever its label and field name become.
+
+From your own views, write the keys and let the gem look the IDs up:
+
+```erb
+<%= link_to "Request an integration",
+      formblocks_form_path("request-for-integration",
+        Formblocks.prefill("request-for-integration",
+          user_id: Current.user.id, account_id: Current.account.id,
+          role: Current.account.role, email: Current.user.email)),
+      target: "_blank" %>
+```
+
+`Formblocks.prefill(slug, answers)` is one query and returns `{ id => value }`.
+A key the form does not have is left out, so the link survives a field being
+renamed or removed. IDs belong to a database — the same form built in staging
+and in production has different ones — which is the other reason to use the
+helper rather than paste IDs into code.
+
+A field also answers to its plain key, `?utm_source=newsletter`, for the
+parameters whose names you do not choose. A radio group takes one of its
+options, a checkbox `1` or `0`. Anything in a URL can be edited by the
+visitor, so treat a prefilled answer like any other answer: it says what the
+link said, not who the visitor is.
+
 ### Spam and rate limiting
 
 Two defences, both on by default and neither visible to a person:

data/app/controllers/formblocks/public/forms_controller.rb

@@ -19,7 +19,8 @@ module Formblocks
       end
 
       def show
-        @response = @form.responses.new
+        # The query string only — never the path's own :slug.
+        @response = @form.responses.new.prefill(request.query_parameters)
         @referrer = clean_page_url(request.referer)
       end
 

data/app/models/formblocks/blocks/hidden.rb

@@ -3,8 +3,9 @@
 module Formblocks
   module Blocks
     # A field the visitor never sees. `key` is its name, `content` its default
-    # value; a query parameter with the same name on the public URL overrides
-    # the default, so ?utm_source=newsletter lands in the response.
+    # value; like any input it can be filled from the public URL's query
+    # string (see Response#prefill), so ?utm_source=newsletter lands in the
+    # response.
     class Hidden < Input
       def self.placeholder? = false
       def self.requirable? = false

data/app/models/formblocks/blocks/input.rb

@@ -31,6 +31,14 @@ module Formblocks
         true
       end
 
+      # The name this input answers to in the public URL's query string:
+      # opaque, so a link can fill the field in advance without showing what
+      # it is called (?3f9a1c2b7d4e=value). A digest of the id — stable for
+      # the life of the block, whatever its key and label become.
+      def public_id
+        Digest::SHA256.hexdigest("formblocks/block/#{id}").first(12) if persisted?
+      end
+
       # The submitted value as it is stored.
       def normalize_answer(value)
         value.to_s.strip

data/app/models/formblocks/response.rb

@@ -27,6 +27,19 @@ module Formblocks
       self
     end
 
+    # Answers given in advance: the public URL's query parameters, named by
+    # a block's opaque id (?3f9a1c2b7d4e=ada@example.com) or by its key
+    # (?utm_source=newsletter). Only the form's own inputs and only the ones
+    # given, so a hidden block without one keeps its default.
+    def prefill(given)
+      given = given.to_h.stringify_keys
+      form.input_blocks.each do |block|
+        value = given.fetch(block.public_id) { given[block.key] }
+        answers[block.key] = block.normalize_answer(value) if value.is_a?(String)
+      end
+      self
+    end
+
     def answer(block)
       answers.to_h[block.key]
     end

data/app/views/formblocks/blocks/_block.html.erb

@@ -1,11 +1,18 @@
 <% page = block.page %>
 <% form = page.form %>
-<article class="fb-block" id="<%= dom_id(block) %>" data-fb-sortable-target="item" data-id="<%= block.id %>">
+<article class="fb-block" id="<%= dom_id(block) %>" data-fb-sortable-target="item" data-id="<%= block.id %>"
+         data-controller="fb-clipboard" data-fb-clipboard-copied-value="<%= t('formblocks.actions.copied') %>">
   <header class="fb-block__header">
     <button type="button" class="fb-block__grip" data-fb-sortable-handle title="<%= t('formblocks.forms.edit.drag') %>"
             aria-label="<%= t('formblocks.forms.edit.drag') %>"><%= fb_icon(:grip) %></button>
     <span class="fb-block__type"><%= block.display_name %></span>
     <div class="fb-actions">
+      <% if block.input? %>
+        <button type="button" class="fb-btn fb-btn--sm fb-btn--ghost" data-action="fb-clipboard#copy"
+                title="<%= t('formblocks.actions.copy_id_hint') %>">
+          <%= fb_icon(:copy) %> <span data-fb-clipboard-target="label"><%= t('formblocks.actions.copy_id') %></span>
+        </button>
+      <% end %>
       <%= button_to move_form_page_block_path(form, page, block, direction: 'up'), method: :patch, class: 'fb-iconbtn',
                     title: t('formblocks.actions.move_up'), 'aria-label': t('formblocks.actions.move_up'),
                     form: { data: { turbo_action: 'replace' } } do %><%= fb_icon(:up) %><% end %>
@@ -63,19 +70,25 @@
           </div>
         <% end %>
       </div>
-      <% unless block.visible? %>
-        <div class="fb-grid">
-          <div class="fb-field">
-            <%= f.label :key, t('formblocks.fields.key'), class: 'fb-label' %>
-            <%= f.text_field :key, class: 'fb-input fb-input--mono', autocomplete: 'off', spellcheck: false %>
-            <p class="fb-hint"><%= t('formblocks.fields.key_hint') %></p>
-          </div>
-          <div class="fb-field">
+      <div class="fb-grid">
+        <div class="fb-field">
+          <%= f.label :key, t('formblocks.fields.key'), class: 'fb-label' %>
+          <%= f.text_field :key, class: 'fb-input fb-input--mono', autocomplete: 'off', spellcheck: false %>
+          <p class="fb-hint">
+            <%= t('formblocks.fields.key_hint') %>
+            <%= t('formblocks.fields.prefill_hint_html', id: tag.code(block.public_id, data: { fb_clipboard_target: 'source' })) %>
+          </p>
+        </div>
+        <div class="fb-field">
+          <% if block.visible? %>
+            <%= f.label :help_text, t('formblocks.fields.help_text'), class: 'fb-label' %>
+            <%= f.text_field :help_text, class: 'fb-input' %>
+          <% else %>
             <%= f.label :content, t('formblocks.fields.value'), class: 'fb-label' %>
             <%= f.text_field :content, class: 'fb-input' %>
-          </div>
+          <% end %>
         </div>
-      <% end %>
+      </div>
       <% if block.options? %>
         <div class="fb-field">
           <%= f.label :options_text, t('formblocks.fields.options'), class: 'fb-label' %>
@@ -83,12 +96,6 @@
           <p class="fb-hint"><%= t('formblocks.fields.options_hint') %></p>
         </div>
       <% end %>
-      <% if block.visible? %>
-        <div class="fb-field">
-          <%= f.label :help_text, t('formblocks.fields.help_text'), class: 'fb-label' %>
-          <%= f.text_field :help_text, class: 'fb-input' %>
-        </div>
-      <% end %>
       <% if block.requirable? %>
         <label class="fb-check"><%= f.check_box :required %> <%= t('formblocks.fields.required') %></label>
       <% end %>

data/app/views/formblocks/public/blocks/_hidden.html.erb

@@ -1,5 +1,3 @@
-<%# The stored answer on a re-render, else the URL's query parameter, else the block's default. %>
-<% value = if response&.answers&.key?(block.key) then response.answer(block)
-           elsif params[block.key].is_a?(String) then params[block.key]
-           else block.default_value end %>
+<%# The answer — submitted, or given in the URL's query string — else the block's default. %>
+<% value = response&.answers&.key?(block.key) ? response.answer(block) : block.default_value %>
 <%= hidden_field_tag "answers[#{block.key}]", value, id: nil %>

data/config/locales/formblocks.en.yml

@@ -16,6 +16,9 @@ en:
       delete_form: Delete this form
       duplicate: Duplicate
       back: Back
+      copy_id: Copy ID
+      copy_id_hint: The field's ID, for filling it in advance from the public URL
+      copied: Copied!
       move_up: Move up
       move_down: Move down
       confirm_delete: Delete this? This cannot be undone.
@@ -102,7 +105,8 @@ en:
       options: Options
       options_hint: One option per line.
       key: Field name
-      key_hint: The name the value is stored under. A matching query parameter on the public URL fills it (for example ?utm_source=…).
+      key_hint: The name the answer is stored under.
+      prefill_hint_html: "To fill this field in advance, add ?%{id}=… to the public URL."
       value: Default value
       image: Image
       alt_text: Alt text

data/lib/formblocks/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Formblocks
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
 end

data/lib/formblocks.rb

@@ -48,6 +48,21 @@ module Formblocks
       Form.for_tenant(tenant_key_for(record))
     end
 
+    # Query parameters that fill a form's fields in advance, each under the
+    # field's opaque id rather than its key, so the URL does not show what the
+    # fields are called:
+    #
+    #   formblocks_form_url('feedback', Formblocks.prefill('feedback', user_id: 7, email: 'ada@example.com'))
+    #   # => /f/feedback?3f9a1c2b7d4e=7&b04e8a61c7d2=ada%40example.com
+    #
+    # Keys the form does not have are dropped, so a link keeps working when a
+    # field is renamed or removed in the builder.
+    def prefill(slug, answers)
+      answers = answers.to_h.stringify_keys
+      Block.joins(page: :form).where(Form.table_name => { slug: slug.to_s }, key: answers.keys)
+           .to_h { |block| [block.public_id, answers[block.key]] }
+    end
+
     # The product name for titles and alt text: config.app_name, else the
     # Rails application's module name, verbatim ("Nusii", "SupeRails").
     def app_name

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: formblocks
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Michael Koper