phlexible 3.2.0 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba0c7764b691fdb2ea92f5d8ef9389e1eb31bd97483f210e1b5e8f7c9fcd0c09
-  data.tar.gz: 80b397992cf20e11e9e971d744f6a7cea5bfa56a1b1186c4a629ec04bb836624
+  metadata.gz: 7d77a1775f2cf5e96455ca326a6589a00bb0400f5bf4f01f0af1268c01579e0b
+  data.tar.gz: b68f67d1bcc7c913177efdb1aec44fe866cde16d30fdc6215dc9760cb7ac1c3d
 SHA512:
-  metadata.gz: 375b7283fa50d41cf9e94bdc131f5faa469d73f67c8f2f8fdf34badb6c722edf193c9d9d64ffb7fee6f565d7d2a7a853a91f2d3f4ffed901e8d8b4421b967e9b
-  data.tar.gz: b5fba4880d3a63faca0e67fe09a422a34b12b322ae6dd73ebca5b3a4b0137db0b80f177df306f18b27942a9d57fcd1501da6a2b8d9bafc5c3f6899fa729f4b90
+  metadata.gz: 83a9a3082006f0ec7fcaa46fd7d492a09928c07419639ff15da929b3fb27bec5ec0576c6e2a20b3e29666899820882029b798df9d88ed6865bacc77fd80a2cf6
+  data.tar.gz: b615b0e6f37147e44868398f6e5180fa2f095b39300ad9f8d97d0e1f58e5981ceae1df444d6b446885c3d06f1387a1ce31b1c0522dd6e50dce149d5b445f0bc1

data/README.md

@@ -2,6 +2,27 @@
 
 A bunch of helpers and goodies intended to make life with [Phlex](https://phlex.fun) even easier!
 
+## Table of Contents
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [AliasView](#aliasview)
+  - [Callbacks](#callbacks)
+  - [ElementVariants](#elementvariants)
+  - [PageTitle](#pagetitle)
+  - [ProcessAttributes](#processattributes)
+  - [Rails::ActionController::ImplicitRender](#railsactioncontrollerimplicitrender)
+  - [Rails::ControllerVariables](#railscontrollervariables)
+  - [Rails::AutoLayout](#railsautolayout)
+  - [Rails::AElement](#railsaelement)
+  - [Rails::ButtonTo](#railsbuttonto)
+  - [Rails::MetaTags](#railsmetatags)
+  - [Rails::Responder](#railsresponder)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Code of Conduct](#code-of-conduct)
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -14,6 +35,182 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
 ## Usage
 
+### `AliasView`
+
+Create an alias at a given `element`, to the given view class.
+
+So instead of:
+
+```ruby
+class MyView < Phlex::HTML
+  def view_template
+    div do
+      render My::Awesome::Component.new
+    end
+  end
+end
+```
+
+You can instead do:
+
+```ruby
+class MyView < Phlex::HTML
+  extend Phlexible::AliasView
+
+  alias_view :awesome, -> { My::Awesome::Component }
+
+  def view_template
+    div do
+      awesome
+    end
+  end
+end
+```
+
+### `Callbacks`
+
+While Phlex does have `before_template`, `after_template`, and `around_template` hooks, they must be defined as regular Ruby methods, meaning you have to always remember to call `super` when redefining any hook method.
+
+This module provides a more Rails-like interface for defining callbacks in your Phlex views, using `ActiveSupport::Callbacks`. It implements the same `before_template`, `after_template`, and `around_template` hooks as callbacks.
+
+```ruby
+class Views::Users::Index < Views::Base
+  include Phlexible::Callbacks
+
+  before_template :set_title
+
+  def view_template
+    h1 { @title }
+  end
+
+  private
+
+    def set_title
+      @title = 'Users'
+    end
+end
+```
+
+You can still use the regular `before_template`, `after_template`, and `around_template` hooks as well, but I recommend that if you include this module, that you use callbacks instead.
+
+When used with `Rails::AutoLayout`, layout callbacks (`before_layout`, `after_layout`, `around_layout`) are also available. See the `Rails::AutoLayout` section below.
+
+### `ElementVariants`
+
+Declare named variants for one or more HTML elements, then apply them by passing the variant name as a Symbol (or Symbols) in the first argument to the element method. By default, each variant adds a `data-variant-<name>` attribute to the element.
+
+Extend your view class with `Phlexible::ElementVariants` and declare variants with `variant`:
+
+```ruby
+class MyView < Phlex::HTML
+  extend Phlexible::ElementVariants
+
+  variant :divider, on: [:h1, :h2, :h3, :h4, :h5, :h6]
+
+  def view_template
+    h1(:divider) { 'My Title' }
+  end
+end
+```
+
+This will output:
+
+```html
+<h1 data-variant-divider>My Title</h1>
+```
+
+Underscored names are rendered as dashes in the data attribute (e.g. `:super_big` becomes `data-variant-super-big`).
+
+#### Modifying attributes
+
+Pass a block to `variant` to modify the element's attributes when the variant is used. The block receives the attributes hash:
+
+```ruby
+class MyView < Phlex::HTML
+  extend Phlexible::ElementVariants
+
+  variant :external, on: :a do |attributes|
+    attributes[:target] = '_blank'
+  end
+
+  def view_template
+    a(:external, href: 'https://example.com') { 'Link' }
+  end
+end
+```
+
+#### Multiple variants
+
+You can apply multiple variants to a single element by passing more than one Symbol:
+
+```ruby
+a(:external, :primary, href: '/foo') { 'Link' }
+```
+
+Passing an unregistered variant raises `ArgumentError`.
+
+### `PageTitle`
+
+Helper to assist in defining page titles within Phlex views. Also includes support for nested views, where each desendent view class will have its title prepended to the page title. Simply include *Phlexible::PageTitle* module and assign the title to the `page_title` class variable:
+
+```ruby
+class MyView
+  include Phlexible::PageTitle
+  self.page_title = 'My Title'
+end
+```
+
+Then call the `page_title` method in the `<head>` of your page.
+
+### `ProcessAttributes`
+
+> This functionality is already built in to **Phlex >= 1**. This module is only needed for **Phlex >= 2**.
+
+Allows you to intercept and modify HTML element attributes before they are rendered. This is useful for adding default attributes, transforming values, or conditionally modifying attributes based on other attributes.
+
+Extend your view class with `Phlexible::ProcessAttributes` and define a `process_attributes` instance method that receives the attributes hash and returns the modified hash.
+
+```ruby
+class MyView < Phlex::HTML
+  extend Phlexible::ProcessAttributes
+
+  def process_attributes(attrs)
+    # Add a default class to all elements
+    attrs[:class] ||= 'my-default-class'
+    attrs
+  end
+
+  def view_template
+    div(id: 'container') { 'Hello' }
+  end
+end
+```
+
+This will output:
+
+```html
+<div id="container" class="my-default-class">Hello</div>
+```
+
+The `process_attributes` method is called for all standard HTML elements and void elements, as well as any custom elements registered with `register_element`.
+
+```ruby
+class MyView < Phlex::HTML
+  extend Phlexible::ProcessAttributes
+
+  register_element :my_custom_element
+
+  def process_attributes(attrs)
+    attrs[:data_processed] = true
+    attrs
+  end
+
+  def view_template
+    my_custom_element(name: 'test') { 'Custom content' }
+  end
+end
+```
+
 ### `Rails::ActionController::ImplicitRender`
 
 Adds support for default and `action_missing` rendering of Phlex views. So instead of this:
@@ -58,33 +255,48 @@ end
 
 This would resolve `UsersController#index` to `Views::Users::Index` instead.
 
-### `Callbacks`
+### `Rails::ControllerVariables`
 
-While Phlex does have `before_template`, `after_template`, and `around_template` hooks, they must be defined as regular Ruby methods, meaning you have to always remember to call `super` when redefining any hook method.
+> **NOTE:** Prior to **1.0.0**, this module was called `ControllerAttributes` with a very different API. This is no longer available since **1.0.0**.
 
-This module provides a more Rails-like interface for defining callbacks in your Phlex views, using `ActiveSupport::Callbacks`. It implements the same `before_template`, `after_template`, and `around_template` hooks as callbacks.
+Include this module in your Phlex views to get access to the controller's instance variables. It provides an explicit interface for accessing controller instance variables from within the view.
 
 ```ruby
 class Views::Users::Index < Views::Base
-  include Phlexible::Callbacks
+  include Phlexible::Rails::ControllerVariables
 
-  before_template :set_title
+  controller_variable :first_name, :last_name
 
   def view_template
-    h1 { @title }
+    h1 { "#{@first_name} #{@last_name}" }
   end
+end
+```
 
-  private
+#### Options
 
-    def set_title
-      @title = 'Users'
-    end
+`controller_variable` accepts one or many symbols, or a hash of symbols to options.
+
+- `as:` - If set, the given attribute will be renamed to the given value. Helpful to avoid naming conflicts.
+- `allow_undefined:` - By default, if the instance variable is not defined in the controller, an
+  exception will be raised. If this option is to `true`, an error will not be raised.
+
+You can also pass a hash of attributes to `controller_variable`, where the key is the controller
+attribute, and the value is the renamed value, or options hash.
+
+```ruby
+class Views::Users::Index < Views::Base
+  include Phlexible::Rails::ControllerVariables
+
+  controller_variable last_name: :surname, first_name: { as: :given_name, allow_undefined: true }
+
+  def view_template
+    h1 { "#{@given_name} #{@surname}" }
+  end
 end
 ```
 
-You can still use the regular `before_template`, `after_template`, and `around_template` hooks as well, but I recommend that if you include this module, that you use callbacks instead.
-
-When used with `Rails::AutoLayout`, layout callbacks (`before_layout`, `after_layout`, `around_layout`) are also available. See the `Rails::AutoLayout` section below.
+Please note that defining a variable with the same name as an existing variable in the view will be overwritten.
 
 ### `Rails::AutoLayout`
 
@@ -182,80 +394,6 @@ end
 
 Layout resolution is cached per class in production. In development (when `Rails.configuration.enable_reloading` is enabled), layouts are resolved fresh on each render. You can manually clear the cache with `reset_resolved_layout!`.
 
-### `Rails::ControllerVariables`
-
-> **NOTE:** Prior to **1.0.0**, this module was called `ControllerAttributes` with a very different API. This is no longer available since **1.0.0**.
-
-Include this module in your Phlex views to get access to the controller's instance variables. It provides an explicit interface for accessing controller instance variables from within the view.
-
-```ruby
-class Views::Users::Index < Views::Base
-  include Phlexible::Rails::ControllerVariables
-
-  controller_variable :first_name, :last_name
-
-  def view_template
-    h1 { "#{@first_name} #{@last_name}" }
-  end
-end
-```
-
-#### Options
-
-`controller_variable` accepts one or many symbols, or a hash of symbols to options.
-
-- `as:` - If set, the given attribute will be renamed to the given value. Helpful to avoid naming conflicts.
-- `allow_undefined:` - By default, if the instance variable is not defined in the controller, an
-  exception will be raised. If this option is to `true`, an error will not be raised.
-
-You can also pass a hash of attributes to `controller_variable`, where the key is the controller
-attribute, and the value is the renamed value, or options hash.
-
-```ruby
-class Views::Users::Index < Views::Base
-  include Phlexible::Rails::ControllerVariables
-
-  controller_variable last_name: :surname, first_name: { as: :given_name, allow_undefined: true }
-
-  def view_template
-    h1 { "#{@given_name} #{@surname}" }
-  end
-end
-```
-
-Please note that defining a variable with the same name as an existing variable in the view will be overwritten.
-
-### `Rails::Responder`
-
-If you use [Responders](https://github.com/heartcombo/responders), Phlexible provides a responder to support implicit rendering similar to `Rails::ActionController::ImplicitRender` above. It will render the Phlex view using `respond_with` if one exists, and fall back to default rendering.
-
-Just include it in your ApplicationResponder:
-
-```ruby
-class ApplicationResponder < ActionController::Responder
-  include Phlexible::Rails::ActionController::ImplicitRender
-  include Phlexible::Rails::Responder
-end
-```
-
-Then simply `respond_with` in your action method as normal:
-
-```ruby
-class UsersController < ApplicationController
-  def new
-    respond_with User.new
-  end
-
-  def index
-    respond_with User.all
-  end
-end
-```
-
-This responder requires the use of `ActionController::ImplicitRender`, so don't forget to include that in your `ApplicationController`.
-
-If you use `Rails::ControllerVariables` in your view, and define a `resource` attribute, the responder will pass that to your view.
-
 ### `Rails::AElement`
 
 No need to call Rails `link_to` helper, when you can simply render an anchor tag directly with Phlex. But unfortunately that means you lose some of the magic that `link_to` provides. Especially the automatic resolution of URL's and Rails routes.
@@ -278,6 +416,12 @@ class MyView < Phlex::HTML
 end
 ```
 
+You can also pass `:back` as the `href` value, which will use the referrer URL if available, or fall back to `javascript:history.back()`:
+
+```ruby
+a(href: :back) { 'Go back' }
+```
+
 ### `Rails::ButtonTo`
 
 Generates a form containing a single button that submits to the URL created by the set of options.
@@ -333,99 +477,36 @@ class MyView < Phlex::HTML
 end
 ```
 
-### `AliasView`
-
-Create an alias at a given `element`, to the given view class.
-
-So instead of:
-
-```ruby
-class MyView < Phlex::HTML
-  def view_template
-    div do
-      render My::Awesome::Component.new
-    end
-  end
-end
-```
-
-You can instead do:
-
-```ruby
-class MyView < Phlex::HTML
-  extend Phlexible::AliasView
-
-  alias_view :awesome, -> { My::Awesome::Component }
-
-  def view_template
-    div do
-      awesome
-    end
-  end
-end
-```
+### `Rails::Responder`
 
-### `PageTitle`
+If you use [Responders](https://github.com/heartcombo/responders), Phlexible provides a responder to support implicit rendering similar to `Rails::ActionController::ImplicitRender` above. It will render the Phlex view using `respond_with` if one exists, and fall back to default rendering.
 
-Helper to assist in defining page titles within Phlex views. Also includes support for nested views, where each desendent view class will have its title prepended to the page title. Simply include *Phlexible::PageTitle* module and assign the title to the `page_title` class variable:
+Just include it in your ApplicationResponder:
 
 ```ruby
-class MyView
-  include Phlexible::PageTitle
-  self.page_title = 'My Title'
+class ApplicationResponder < ActionController::Responder
+  include Phlexible::Rails::ActionController::ImplicitRender
+  include Phlexible::Rails::Responder
 end
 ```
 
-Then call the `page_title` method in the `<head>` of your page.
-
-### `ProcessAttributes`
-
-> This functionality is already built in to **Phlex >= 1**. This module is only needed for **Phlex >= 2**.
-
-Allows you to intercept and modify HTML element attributes before they are rendered. This is useful for adding default attributes, transforming values, or conditionally modifying attributes based on other attributes.
-
-Extend your view class with `Phlexible::ProcessAttributes` and define a `process_attributes` instance method that receives the attributes hash and returns the modified hash.
+Then simply `respond_with` in your action method as normal:
 
 ```ruby
-class MyView < Phlex::HTML
-  extend Phlexible::ProcessAttributes
-
-  def process_attributes(attrs)
-    # Add a default class to all elements
-    attrs[:class] ||= 'my-default-class'
-    attrs
+class UsersController < ApplicationController
+  def new
+    respond_with User.new
   end
 
-  def view_template
-    div(id: 'container') { 'Hello' }
+  def index
+    respond_with User.all
   end
 end
 ```
 
-This will output:
-
-```html
-<div id="container" class="my-default-class">Hello</div>
-```
-
-The `process_attributes` method is called for all standard HTML elements and void elements, as well as any custom elements registered with `register_element`.
-
-```ruby
-class MyView < Phlex::HTML
-  extend Phlexible::ProcessAttributes
-
-  register_element :my_custom_element
-
-  def process_attributes(attrs)
-    attrs[:data_processed] = true
-    attrs
-  end
+This responder requires the use of `ActionController::ImplicitRender`, so don't forget to include that in your `ApplicationController`.
 
-  def view_template
-    my_custom_element(name: 'test') { 'Custom content' }
-  end
-end
-```
+If you use `Rails::ControllerVariables` in your view, and define a `resource` attribute, the responder will pass that to your view.
 
 ## Development