active_element 0.0.12 → 0.0.14

data/rspec-documentation/pages/005-Setup.md

@@ -1,7 +1,5 @@
 # Setup
 
-To integrate _ActiveElement_ into your _Rails_ application, follow the steps below:
-
 ## Installation
 
 Install the `active_element` gem by adding the following to your `Gemfile`:
@@ -20,7 +18,7 @@ $ bundle install
 
 Inherit from `ActiveElement::ApplicationController` in the controller you want to use with _ActiveElement_. In most cases this will either be your main `ApplicationController`, or a namespaced admin area controller, e.g. `Admin::ApplicationController`. This will apply the default _ActiveElement_ layout which includes a [Navbar](components/navbar.html), [Theme Switcher](components/theme-switcher.html), and all the required _CSS_ and _Javascript_.
 
-If you want to add custom content to the layout, see the [Hooks](hooks.html) documentation.
+If you want to add custom content to the layout, see the [Hooks](hooks.html) documentation, or if you want to use a completely custom layout, simply specify `layout 'my_layout'` in your `ApplicationController`.
 
 ```ruby
 # app/controllers/application_controller.rb
@@ -30,23 +28,13 @@ class ApplicationController < ActiveElement::ApplicationController
 end
 ```
 
-## Create a View
+## Default Controller Actions
 
-We'll use `UsersController` in this example, but you can replace this with whatever controller you want to use with _ActiveElement_.
+_ActiveElement_ provides default controller actions for all controllers that inherit from `ActiveElement::ApplicationController` (directly or indirectly).
 
-Assuming your controller is defined something like this:
+Each action provides boilerplate functionality to get your application off the ground as quickly as possible. See the [Default Controller](default-controller.html) for full details.
 
-```ruby
-# app/controllers/users_controller.rb
-
-class UsersController < ApplicationController
-  def index
-    @users = User.all
-  end
-end
-```
-
-And your routes are defined something like this:
+The below example creates a `/users` endpoint for your application with boilerplate to list, search, view, create, edit, and delete users:
 
 ```ruby
 # config/routes.rb
@@ -56,20 +44,25 @@ Rails.application.routes.draw do
 end
 ```
 
-Edit or create `app/views/users/index.html.erb`. Add a page title and a table component:
-
-```erb
-<%# app/views/users/index.html.erb %>
-
-<%= active_element.component.page_title 'Users' %>
+```ruby
+# app/controllers/users_controller.rb
 
-<%= active_element.component.table collection: @users, fields: [:id, :email, :name] %>
+class UsersController < ApplicationController
+  active_element.listable_fields :name, :email, :created_at, order: :name
+  active_element.viewable_fields :name, :email, :created_at, :updated_at
+  active_element.editable_fields :name, :email
+  active_element.searchable_fields :name, :name, :created_at, :updated_at
+  active_element.deletable
+end
 ```
 
-Adjust the `fields` to match whatever attributes you want to display for each `User` in your table.
+```ruby
+# app/models/user.rb
 
-Start your _Rails_ application and browse to `/users` to see your new users index.
+class User < ApplicationRecord
+end
+```
 
-## Next Steps
+You can now browse to `/users` on your local development server and see all the default behaviour provided by _ActiveElement_.
 
-Now that you know how to render components, take a look at the [Components](components.html) section of this documentation to see what components are available and how to use them.
+See the [Default Controller](default-controller.html) and [Custom Controllers](custom-controllers.html) sections for more details.

data/rspec-documentation/pages/010-Components/Form Fields.md

@@ -44,3 +44,38 @@ end
 
 it { is_expected.to include 'class="form-control my-class"' }
 ```
+
+## Custom Fields
+
+If you're using the [Default Controller](../default-controller.html) or you simply want to separate your configuration from your views, you can customize each form field by creating a file named `config/forms/<model>/<field>.yml`.
+
+The `User` `email` field can be configured by creating `config/forms/user/email.yml`:
+
+```yaml
+# config/forms/user/email.yml
+
+type: email_field
+options:
+  class: 'form-control my-email-field-class'
+  description: 'We will use your email address to send your account details.'
+  placeholder: 'Enter your email address, e.g. user@example.com'
+```
+
+```rspec:html
+subject do
+  active_element.component.form model: User.new,
+                                fields: [:email, :name, :date_of_birth]
+end
+
+it { is_expected.to include 'class="form-control my-email-field-class"' }
+```
+
+The `options` configuration receives a small number of options specific to _ActiveElement_ such as `description` and [Text Search](form-fields/text-search.html) configuration, otherwise they are passed directly to the underlying _Rails_ form helper.
+
+The `type` configuration corresponds to either a _Rails_ form helper _ActiveElement_ extension field, i.e. `email_field` will call some variation of:
+
+```ruby
+form_with do |form|
+  form.email_field :email
+end
+```

data/rspec-documentation/pages/015-Custom Controllers.md

@@ -0,0 +1,32 @@
+# Custom Controllers
+
+The [Default Controller](default-controller.html) provides out-of-the-box functionality to get you up and running quickly, but as your application progresses you will likely need to provide custom functionality in some areas.
+
+A custom controller is just a regular _Rails_ controller. You can still benefit from default actions provided by _ActiveElement_ and only override the specific actions you need.
+
+In the example below we'll implement a custom `#show` action on a `UsersController` and create a custom view.
+
+```ruby
+# app/controllers/users_controller.rb
+
+class UsersController < ApplicationController
+  active_element.listable_fields :name, :email, :created_at, order: :name
+  active_element.editable_fields :name, :email
+  active_element.searchable_fields :name, :name, :created_at, :updated_at
+  active_element.deletable
+
+  def show
+    @user = User.find(params[:id])
+  end
+end
+```
+
+```erb
+<%# app/views/users/index.html.erb %>
+
+<%= active_element.component.page_title 'Users' %>
+
+<%= active_element.component.table item: @user, fields: [:email, :name, :created_at, :updated_at] %>
+```
+
+You can customize any action or view you like, simply by following standard _Rails_ patterns.

data/rspec-documentation/pages/016-Default Controller.md

@@ -0,0 +1,132 @@
+# Default Controller
+
+The default controller in _ActiveElement_ provides all the standard _Rails_ actions:
+
+* `#index`
+* `#show`
+* `#new`
+* `#create`
+* `#edit`
+* `#update`
+* `#destroy`
+
+All controllers that inherit from `ActiveElement::ApplicationController` automatically receive these routes, but they must be explicitly enabled in order to serve content, otherwise a default `403 Forbidden` page will be rendered.
+
+Each controller expects to find a model whose name corresponds to the controller, in line with typical _Rails_ conventions. For example, if you have a `RestaurantsController` then _ActiveElement_ will expect to find a `Restaurant` model. Each of the declarations covered below describe interactions with a corresponding model.
+
+Depending on which declarations are defined in your controllers, you will see different _UI_ elements (e.g. a _Delete_ button for each record will only be present when `active_element.deletable` has been called).
+
+## Associations
+
+Model associations are supported, so you can list database columns as well as relations defined on your model.
+
+Here's a basic example:
+
+```ruby
+# app/models/restaurant.rb
+
+class Restaurant < ApplicationRecord
+  belongs_to :restaurateur
+end
+```
+
+```ruby
+# app/models/restaurateur.rb
+
+class Restaurateur < ApplicationRecord
+  has_many :resaturants
+end
+```
+
+```ruby
+# app/controllers/restaurants_controller.rb
+
+class RestaurantsController < ApplicationController
+  active_element.listable_fields :name, :restaurateur, :created_at
+end
+```
+
+Now when you browse to `/restaurants` you'll see a link to each restaurants owner in the rendered table.
+
+## Listable Fields
+
+The `active_element.listable_fields` declaration provides a list of fields on your model that should be displayed in the default `#index` view.
+
+A table of results will be rendered containing each record corresponding for the corresponding record, including _View_, _Edit_, and _Delete_ buttons, as well as a button above the table to create a new record.
+
+The `order` keyword allows you to sort the results by a given field. This value is passed directly to the `ActiveRecord` `order` method, so you can use `:name` or `{ name: :desc }` or any other variation that `ActiveRecord` accepts.
+
+```ruby
+# app/controllers/restaurants_controller.rb
+
+class RestaurantsController < ApplicationController
+  active_element.listable_fields :name, :restaurateur, :created_at, order: :name
+end
+```
+
+As mentioned above, associations are supported, so the `restaurateur` association will automatically map to the associated record and you'll be provided with a link to that record in the results table.
+
+Pagination is also provided by the default `#index` action.
+
+## Searchable Fields
+
+The `active_element.searchable_fields` declaration provides a list of fields on your model that can be searched by a user. You can specify `string`, `integer`, and `datetime` fields.
+
+A search form is generated and user input is processed according to column type.
+
+* `string` fields generate an `ILIKE` (case-insensitive `LIKE`) query from user input: `"joh"` will match `"John Smith"`.
+* `integer` fields require an exact match.
+* `datetime` fields provide a range, allowing users to provide a start date/time, an end date/time, or both.
+* Association fields will join on the relevant association and search all `string` and `integer` fields defined in the `searchable_fields` for the controller corresponding to the association model.
+
+```ruby
+# app/controllers/restaurants_controller.rb
+
+class RestaurantsController < ApplicationController
+  active_element.searchable_fields :name, :restaurateur, :created_at
+end
+```
+
+```ruby
+# app/controllers/restaurateurs_controller.rb
+
+class RestaurateursController < ApplicationController
+  active_element.searchable_fields :name, :address
+end
+```
+
+## Viewable Fields
+
+The `active_element.viewable_fields` declaration provides a list of fields on your model that will be included when viewing an individual record via the `#show` action.
+
+The results will be rendered in a horizontal table with one row for each item, including a _Delete_ and _Edit_ button above the table.
+
+```ruby
+# app/controllers/restaurants_controller.rb
+
+class RestaurantsController < ApplicationController
+  active_element.searchable_fields :name, :restaurateur, :created_at
+end
+```
+
+## Editable Fields
+
+The `active_element.editable_fields` declaration provides a list of fields on your model that can be modified by a user.
+
+This declaration enables both the `#edit`, `#new`, `#update`, and `#create` actions as well as defining the permitted parameters for `#update` and `#create`. A form is automatically generated and each field is selected according to the column data type.
+
+Note that each field type can be overridden and configured by defining `config/forms/<model>/<field.yml>`, allowing you to make many customizations to each field without having to work with views or override the default controller actions, as well as allowing each field configuration to be re-used in multiple places. See the [Form Fields](components/form-fields.html) documentation for more details.
+
+By default, `json` and `jsonb` fields use the [JSON Field](form-fields/json.html) type, allowing you to edit complex _JSON_ data structures via user-friendly _HTML_ forms. A [schema file](form-fields/json/schema.html) **must** be defined for these fields. See the `json_field` documentation for more details.
+
+## Deletable
+
+The `active_element.deletable` declaration does not receive any arguments but specifies that a record can be deleted by a user.
+
+```ruby
+# app/controllers/restaurants_controller.rb
+
+class RestaurantsController < ApplicationController
+  active_element.deletable
+end
+```

data/rspec-documentation/pages/Themes.md

@@ -0,0 +1,3 @@
+# Themes
+
+TODO

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_element
 version: !ruby/object:Gem::Version
-  version: 0.0.12
+  version: 0.0.14
 platform: ruby
 authors:
 - Bob Farrell
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-06-20 00:00:00.000000000 Z
+date: 2023-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bootstrap
@@ -116,6 +116,7 @@ files:
 - app/assets/javascripts/active_element/application.js
 - app/assets/javascripts/active_element/confirm.js
 - app/assets/javascripts/active_element/form.js
+- app/assets/javascripts/active_element/highlight.js
 - app/assets/javascripts/active_element/json_field.js
 - app/assets/javascripts/active_element/pagination.js
 - app/assets/javascripts/active_element/popover.js
@@ -130,6 +131,7 @@ files:
 - app/assets/stylesheets/active_element/application.scss
 - app/controllers/active_element/application_controller.rb
 - app/controllers/concerns/active_element/default_controller_actions.rb
+- app/views/active_element/_title.html.erb
 - app/views/active_element/_user.html.erb
 - app/views/active_element/components/_horizontal_tabs.html.erb
 - app/views/active_element/components/_vertical_tabs.html.erb
@@ -318,8 +320,11 @@ files:
 - lib/active_element/controller_interface.rb
 - lib/active_element/controller_state.rb
 - lib/active_element/default_controller.rb
-- lib/active_element/default_record_params.rb
-- lib/active_element/default_search.rb
+- lib/active_element/default_controller/actions.rb
+- lib/active_element/default_controller/controller.rb
+- lib/active_element/default_controller/json_params.rb
+- lib/active_element/default_controller/params.rb
+- lib/active_element/default_controller/search.rb
 - lib/active_element/engine.rb
 - lib/active_element/json_field_schema.rb
 - lib/active_element/permissions_check.rb
@@ -354,6 +359,8 @@ files:
 - rspec-documentation/pages/010-Components/Tables/Item Table.md
 - rspec-documentation/pages/010-Components/Tables/Options.md
 - rspec-documentation/pages/010-Components/Tabs.md
+- rspec-documentation/pages/015-Custom Controllers.md
+- rspec-documentation/pages/016-Default Controller.md
 - rspec-documentation/pages/020-Access Control.md
 - rspec-documentation/pages/020-Access Control/010-Authentication.md
 - rspec-documentation/pages/020-Access Control/020-Authorization.md
@@ -367,6 +374,7 @@ files:
 - rspec-documentation/pages/040-Decorators/View Decorators.md
 - rspec-documentation/pages/300-Alternatives.md
 - rspec-documentation/pages/900-License.md
+- rspec-documentation/pages/Themes.md
 - rspec-documentation/spec_helper.rb
 - rspec-documentation/support.rb
 - sig/active_element.rbs

data/lib/active_element/default_record_params.rb

@@ -1,62 +0,0 @@
-# frozen_string_literal: true
-
-module ActiveElement
-  # Provides params for ActiveRecord models when using the default boilerplate controller
-  # actions. Navigates input parameters and maps them to appropriate relations as needed.
-  class DefaultRecordParams
-    def initialize(controller:, model:)
-      @controller = controller
-      @model = model
-    end
-
-    def params
-      with_transformed_relations(
-        controller.params.require(controller.controller_name.singularize)
-                  .permit(controller.active_element.state.editable_fields)
-      )
-    end
-
-    private
-
-    attr_reader :controller, :model
-
-    def with_transformed_relations(params)
-      params.to_h.to_h do |key, value|
-        next [key, value] unless relation?(key)
-
-        relation_param(key, value)
-      end
-    end
-
-    def relation_param(key, value)
-      case relation(key).macro
-      when :belongs_to
-        belongs_to_param(key, value)
-      when :has_one
-        has_one_param(key, value)
-      when :has_many
-        has_many_param(key, value)
-      end
-    end
-
-    def belongs_to_param(key, value)
-      [relation(key).foreign_key, value]
-    end
-
-    def has_one_param(key, value) # rubocop:disable Naming/PredicateName
-      [relation(key).name, relation(key).klass.find_by(relation(key).klass.primary_key => value)]
-    end
-
-    def has_many_param(key, _value) # rubocop:disable Naming/PredicateName
-      [relation(key).name, relation(key).klass.where(relation(key).klass.primary_key => relation(key).value)]
-    end
-
-    def relation?(attribute)
-      relation(attribute.to_sym).present?
-    end
-
-    def relation(attribute)
-      model.reflect_on_association(attribute.to_sym)
-    end
-  end
-end

data/lib/active_element/default_search.rb

@@ -1,110 +0,0 @@
-# frozen_string_literal: true
-
-module ActiveElement
-  # Full text search and datetime querying for DefaultController, provides full text search
-  # filters for all controllers with configured searchable fields. Includes support for querying
-  # across relations.
-  class DefaultSearch
-    def initialize(controller:, model:)
-      @controller = controller
-      @model = model
-    end
-
-    def search_filters
-      @search_filters ||= controller.params.permit(*searchable_fields).transform_values do |value|
-        value.try(:compact_blank) || value
-      end.compact_blank
-    end
-
-    def text_search?
-      search_filters.present?
-    end
-
-    def text_search
-      conditions = search_filters.to_h.map do |key, value|
-        next relation_matches(key, value) if relation?(key)
-        next datetime_between(key, value) if datetime?(key)
-
-        model.arel_table[key].matches("#{value}%")
-      end
-      conditions[1..].reduce(conditions.first) do |accumulated, condition|
-        accumulated.and(condition)
-      end
-    end
-
-    def search_relations
-      search_filters.to_h.keys.map { |key| relation?(key) ? key.to_sym : nil }.compact
-    end
-
-    private
-
-    attr_reader :controller, :model
-
-    def searchable_fields
-      controller.active_element.state.searchable_fields.map do |field|
-        next field unless field.to_s.end_with?('_at')
-
-        { field => %i[from to] }
-      end
-    end
-
-    def noop
-      Arel::Nodes::True.new.eq(Arel::Nodes::True.new)
-    end
-
-    def datetime?(key)
-      model.columns.find { |column| column.name.to_s == key.to_s }&.type == :datetime
-    end
-
-    def datetime_between(key, value)
-      return noop if value[:from].blank? && value[:to].blank?
-
-      model.arel_table[key].between(range_begin(value)...range_end(value))
-    end
-
-    def range_begin(value)
-      value[:from].present? ? Time.zone.parse(value[:from]) + timezone_offset : -Float::INFINITY
-    end
-
-    def range_end(value)
-      value[:to].present? ? Time.zone.parse(value[:to]) + timezone_offset : Float::INFINITY
-    end
-
-    def timezone_offset
-      controller.request.cookies['timezone_offset'].to_i.minutes
-    end
-
-    def relation_matches(key, value)
-      fields = searchable_relation_fields(key)
-      relation_model = relation(key).klass
-      fields.select! do |field|
-        relation_model.columns.find { |column| column.name.to_s == field.to_s }&.type == :string
-      end
-
-      return noop if fields.empty?
-
-      relation_conditions(fields, value, relation_model)
-    end
-
-    def relation_conditions(fields, value, relation_model)
-      fields[1..].reduce(relation_model.arel_table[fields.first].matches("#{value}%")) do |condition, field|
-        condition.or(relation_model.arel_table[field].matches("#{value}%"))
-      end
-    end
-
-    def searchable_relation_fields(key)
-      Components::Util.relation_controller(model, controller, key)
-                      &.active_element
-                      &.state
-                      &.fetch(:searchable_fields, []) || []
-    end
-
-    def relation?(attribute)
-      relation(attribute.to_sym).present?
-    end
-
-    def relation(attribute)
-      model.reflect_on_association(attribute.to_sym)
-    end
-  end
-end