lexxy-variables 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b3aad3f3ce716d523463e8bc65d14d4d7e1b87fbe166b3c2a240e52632e8c4f
-  data.tar.gz: 5837750469a552f3758ad187a0d8087b935cba24983df189e70132ddcab396b7
+  metadata.gz: 20e1253a50b9ac063ff88624785d48c6103842a46c07256ab867db405497f38a
+  data.tar.gz: 6c9097c35bd39c7a81b204de9f68599c56be4fcd319ec660cbcfb5aaa4432f85
 SHA512:
-  metadata.gz: f850a1474ddd89b9652a0a76a670b039246fe8db766168c3acb8df93708b331e59a7586cca403f3ae49bea97dd180007a9c60893c64a6174776cf959d9d593d2
-  data.tar.gz: 1b246e2ab7e6eb75fa3814e018fb826de38a294e68efe5df05854c14d83882690a5c7e82635995350bd0d87a8bde67290c2212972e73cde95cba5f54dcdde08d
+  metadata.gz: c6d6291c6770026b75e2b167262f39d3419fdcb23ba255969391f3a96adce42abb2c3a2f7e73cd775855832483fc7158ab9dd655b481caf80042791262638931
+  data.tar.gz: 343e6f7cc524a95b4c5aca8a0230d091acf16a3ef7147cc2324172fc545ca3bc1db91bae1907ef344b6d06fd255874c741b770393d609ee7c4a3124c0f59dbf9

data/README.md

@@ -44,8 +44,8 @@ in your entrypoint:
 
 ```js
 // app/javascript/application.js
+import * as Lexxy from "lexxy"
 import VariableExtension from "lexxy-variables"
-import * as Lexxy from "@37signals/lexxy"
 
 Lexxy.configure({ global: { extensions: [ VariableExtension ] } })
 ```
@@ -54,16 +54,25 @@ Lexxy.configure({ global: { extensions: [ VariableExtension ] } })
 npm package. Install it alongside Lexxy:
 
 ```sh
-yarn add lexxy-variables @37signals/lexxy
+yarn add @37signals/lexxy lexxy-variables
 ```
 
-and register the extension with the same snippet as above.
+and register the extension in your JavaScript.
+
+```js
+// app/javascript/application.js
+import * as Lexxy from "@37signals/lexxy"
+import VariableExtension from "lexxy-variables"
+
+Lexxy.configure({ global: { extensions: [ VariableExtension ] } })
+```
 
 ## Minimal configuration
 
 `catalog` is the list users pick from in the editor. `assigns` is the lookup that
 turns a key into a value at render time. `catalog` is required and `assigns` is
-optional. Leave it out and the gem reads `value` straight off the catalog item.
+optional. Leave it out and the gem reads `value` straight off the catalog item,
+or supply values per render (see [Examples](#examples)).
 
 Put the `configure` block in an initializer, e.g. `config/initializers/lexxy_variables.rb`:
 
@@ -101,7 +110,7 @@ On the **display page** (where the saved content is shown to readers), resolve
 the stored rich text. This is what swaps each variable chip for its value:
 
 ```erb
-<%= render_lexxy_content(@record.body) %>
+<%= render_variable_content(@record.body) %>
 ```
 
 Each chip resolves to its value, so the reader sees finished text:
@@ -113,11 +122,99 @@ Each chip resolves to its value, so the reader sees finished text:
 `@record` and `:body` are placeholders. Use whatever model and Action Text
 attribute hold your content.
 
+## Examples
+
+### Simple replacement from a model
+
+First and last name variables, with the values supplied at render time. No Liquid needed. The `catalog` lists the two variables so they appear in the editor:
+
+```ruby
+# config/initializers/lexxy_variables.rb
+LexxyVariables.configure do |c|
+  c.catalog = [
+    { key: "first_name", name: "First name" },
+    { key: "last_name",  name: "Last name" }
+  ]
+end
+```
+
+Editor page:
+
+```erb
+<%= form_with model: @message do |form| %>
+  <%= form.rich_text_area :body do %>
+    <%= lexxy_variables_prompt %>
+  <% end %>
+  <%= form.submit %>
+<% end %>
+```
+
+Display page:
+
+```erb
+<%= render_variable_content(@message.body,
+      first_name: @user.first_name,
+      last_name:  @user.last_name) %>
+```
+
+The catalog entries have no `value` because it's supplied at render time, so the same saved content renders differently per user. The default renderer escapes the values automatically. When a variable name would collide with `context:` or `locale:`, use an `assigns:` hash instead (see [Helper options](#helper-options)).
+
+### Static values from config
+
+When a value is the same for everyone, it can live on the catalog item itself. With no `assigns` set, the gem reads `value` off the catalog and the helper takes no extra arguments:
+
+```ruby
+LexxyVariables.configure do |c|
+  c.catalog = [ { key: "company", name: "Company", value: "Acme" } ]
+end
+```
+
+```erb
+<%= render_variable_content(@message.body) %>
+```
+
+### Liquid drops and dotted access
+
+Liquid enables dotted access like `{{ user.first_name }}`, filters, and drops that expose a whole object. A drop is a small class that defines which methods Liquid can call, and escapes what it returns:
+
+```ruby
+# app/drops/user_drop.rb
+# Liquid output is emitted html_safe after sanitization,
+# so a drop must escape its own values.
+class UserDrop < Liquid::Drop
+  def initialize(user) = @user = user
+
+  def first_name = ERB::Util.html_escape(@user.first_name).to_s
+  def full_name  = ERB::Util.html_escape(@user.full_name).to_s
+  def email      = ERB::Util.html_escape(@user.email).to_s
+end
+```
+
+The dotted keys go in the catalog so they can be inserted, the Liquid renderer is switched on, and `assigns` returns the drop under the name the keys use (`user`):
+
+```ruby
+LexxyVariables.configure do |c|
+  c.catalog = [
+    { key: "user.first_name", name: "First name" },
+    { key: "user.full_name",  name: "Full name" },
+    { key: "user.email",      name: "Email" }
+  ]
+
+  c.renderer = LexxyVariables::Renderers::Liquid.new
+
+  c.assigns = ->(_used_keys) { { "user" => UserDrop.new(Current.user) } }
+end
+```
+
+```erb
+<%= render_variable_content(@message.body) %>
+```
+
+A `user.first_name` chip becomes `{{ user.first_name }}`, which Liquid runs through the drop. Only the methods defined on the drop are reachable, not arbitrary attributes on the user. Liquid doesn't escape output the way the default renderer does, so the drop escapes its own values. The same goes for any plain string returned from `assigns` or passed inline.
+
 ## Full configuration
 
-`context` is yours to define. The gem passes it untouched to your catalog,
-assigns, and resolve callables, so put whatever they need in it. That might be a
-tenant, `nil`, or any object.
+`context` is yours to define. The gem passes it untouched to your catalog, assigns, and resolve callables, so put whatever they need in it. That might be a tenant, `nil`, or any object.
 
 ```ruby
 LexxyVariables.configure do |c|
@@ -145,7 +242,7 @@ end
 | Option | Default | What it does |
 | --- | --- | --- |
 | `catalog` | `[]` | The insertable items shown in the `{{` prompt and the toolbar dropdown. A list, a zero-arg lambda, or a `->(context)` lambda. Items respond to `#key` and `#name`, and optionally `#value` and `#attachable_sgid`. |
-| `assigns` | reads `#value` off catalog items | The render-time lookup. A `->(context, used_keys)` or `->(used_keys)` lambda that receives only the keys used in the content being rendered and returns a `{ key => value }` hash. |
+| `assigns` | reads `#value` off catalog items | The render-time lookup. A `->(context, used_keys)` or `->(used_keys)` lambda that receives only the keys used in the content being rendered and returns a `{ key => value }` hash. Per-render values can also be passed straight to `render_variable_content` (see [Helper options](#helper-options)). |
 | `renderer` | `Renderers::Substitution.new` | How placeholders become values. The default is plain, escaped string substitution with no template engine. Swap in `Renderers::Liquid.new` for dotted access, drops, and filters. |
 | `sort` | `:name` | How the catalog is ordered in the prompt and dropdown. `:name` (case-insensitive alphabetical), `:key`, `false` to keep the catalog's given order, or a lambda (a `->(item)` sort key or a `->(a, b)` comparator). |
 | `max_fragment_depth` | `1` | How many levels of `renders_as: :html` chips expand. The default resolves the variables inside a snippet but drops a snippet nested inside another snippet. Raise it to allow deeper nesting. |
@@ -156,15 +253,31 @@ end
 
 Both view helpers take `context:` (see [Multi-tenancy](#multi-tenancy)). Beyond
 that, `lexxy_variables_prompt` lets you change the trigger characters and the
-empty state, and `render_lexxy_content` can render under a specific locale by
+empty state, and `render_variable_content` can render under a specific locale by
 wrapping the whole pass in `I18n.with_locale`.
 
 ```erb
 <%= lexxy_variables_prompt(trigger: "%%", empty_results: t(".no_variables")) %>
 
-<%= render_lexxy_content(@record.body, locale: recipient.locale) %>
+<%= render_variable_content(@record.body, locale: recipient.locale) %>
+```
+
+You can also pass a variable's value straight to `render_variable_content`, as
+keyword arguments or an `assigns:` hash. These win over whatever the configured
+`assigns` returns, and a value for a key that isn't used in the content is just
+ignored:
+
+```erb
+<%# keyword arguments %>
+<%= render_variable_content(@record.body, first_name: @user.first_name) %>
+
+<%# same thing, for a name that would clash with context: or locale: %>
+<%= render_variable_content(@record.body, assigns: { first_name: @user.first_name }) %>
 ```
 
+The default renderer escapes these values for you. Liquid doesn't, so escape
+them yourself or pass a drop.
+
 ## Multi-tenancy
 
 Tenancy is optional. If your app is multi-tenant, pass the tenant through as
@@ -188,7 +301,7 @@ Both view helpers take the same `context:`. Pass the tenant on the editor page:
 and again on the display page:
 
 ```erb
-<%= render_lexxy_content(@record.body, context: ActsAsTenant.current_tenant) %>
+<%= render_variable_content(@record.body, context: ActsAsTenant.current_tenant) %>
 ```
 
 Or skip `context` entirely and rely on acts_as_tenant scoping queries to the

data/lib/lexxy_variables/helper.rb

@@ -2,8 +2,19 @@ module LexxyVariables
   # Mixed into Action View by the engine. `context` is opaque to the gem and is
   # passed straight through to the host's catalog/assigns/resolve callables.
   module Helper
-    def render_lexxy_content(rich_text, context: nil, locale: I18n.locale)
-      LexxyVariables::Pipeline.new(self).call(rich_text, context: context, locale: locale)
+    # `assigns:` (and any extra keyword args) are per-render values merged on top
+    # of the configured `assigns`, so a caller can supply a key's value inline:
+    #
+    #   render_variable_content(@record.body, first_name: @user.first_name)
+    #
+    # Inline values win over the configured assigns. Keys not used by any chip in
+    # the body are ignored. Under the default renderer inline values are
+    # HTML-escaped; under Liquid they are emitted as-is, so pre-escape them or
+    # pass a drop.
+    def render_variable_content(rich_text, context: nil, locale: I18n.locale, assigns: {}, **inline_assigns)
+      LexxyVariables::Pipeline.new(self).call(
+        rich_text, context: context, locale: locale, assigns: assigns.merge(inline_assigns)
+      )
     end
 
     # Renders the <lexxy-prompt> the editor extension reads, built from the

data/lib/lexxy_variables/pipeline.rb

@@ -18,7 +18,7 @@ module LexxyVariables
       @config = config
     end
 
-    def call(rich_text, context: nil, locale: I18n.locale)
+    def call(rich_text, context: nil, locale: I18n.locale, assigns: {})
       body = rich_text&.body
       return "".html_safe if body.blank?
 
@@ -32,8 +32,9 @@ module LexxyVariables
           ActionText::Content.new(fragment.to_html, canonicalize: false)
         )
 
-        assigns = @config.resolve_assigns(@context, @used_keys.uniq)
-        rendered = @config.renderer.render(html, nonce: @nonce, assigns: assigns)
+        resolved = @config.resolve_assigns(@context, @used_keys.uniq)
+        resolved = resolved.merge(assigns.transform_keys(&:to_s)) if assigns.any?
+        rendered = @config.renderer.render(html, nonce: @nonce, assigns: resolved)
 
         @view.render(layout: @config.content_layout) { rendered.html_safe }
       end

data/lib/lexxy_variables/version.rb

@@ -1,3 +1,3 @@
 module LexxyVariables
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lexxy-variables
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Andrew Quinn