active_element 0.0.9 → 0.0.11

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

@@ -0,0 +1,133 @@
+# Text Search
+
+_ActiveElement_ provides a `text_search_field` capable of generating a full text search auto-suggest widget in a form.
+
+The `text_search_field` accepts user input and presents a list of matching options, setting the field's `value` to a value specified by the field's configuration.
+
+For example, you may want a `user_id` field that allows users to search by `name` and `email` on the `User` model, and returning the `id` for the selected result.
+
+The field requires some extra configuration to prevent leaking unwanted data to the front end, and to allow you to select which columns should be searched and which column should be submitted to your controller `params` as the field's `value`.
+
+## Example
+
+We'll make a form that creates a `Pet` record and associates it with a `User` by setting a `user_id` field.
+
+Click the **Rendered Output** tab and type a few characters into the search field. In the real world this would be connected to your application, but for the purpose of this documentation we've stubbed the _Javascript_ `fetch` function to return some fake results based on the input.
+
+```rspec:html
+subject do
+  active_element.component.form model: Pet.new,
+                                fields: [
+                                  :name,
+                                  :animal,
+                                  [:user_id,
+                                   :text_search_field,
+                                   { search: { model: :user, with: [:name, :email], providing: :id } }]
+                                ]
+end
+
+it { is_expected.to include 'Search...' }
+```
+
+When you select an option from the suggestions, the full display value appears in the field, but the controller only receives the `id` attribute in `params[:pet][:user_id]` - the display value is a hidden field that gets overwritten by the actual value.
+
+## Routes
+
+If you run `rails routes` in your project once you've set up _ActiveElement_ you'll notice an extra route added for each of your controllers:
+
+```console
+$ rails routes
+
+Routes for ActiveElement::Engine:
+pets__active_element_text_search POST /pets/_active_element_text_search(.:format)    pets#_active_element_text_search
+```
+
+These routes receive text queries and generate results based on your configuration. They're required for the `text_search_field` to work but you can safely ignore them, they are protected by [permissions](#permissions) if you have [authorization](../../../access-control/authorization) configured, as well as some [model configuration](#model-configuration) to ensure that only fields you explicitly configure are searchable.
+
+## Configuration
+
+### Model Configuration
+
+Allowing users to search arbitrary columns on arbitrary models would be a major security risk. To prevent unauthorized data access and _DoS_ vulnerabilities (e.g. allowing searching unindexed database columns), _ActiveElement_ requires that models define which columns are searchable and which columns can provide values. The example above requires the following model definition in order to work:
+
+```ruby
+# app/models/user.rb
+
+class User < ApplicationRecord
+  authorize_active_element_text_search with: [:name, :email], providing: :id
+end
+```
+
+Now even if an attacker sends a custom request to the text search endpoint of your application, only the `name` and `email` columns on the `users` table are searchable, while the `id` column can be returned in results but not searched.
+
+**Important note:** Specifying columns as searchable using the `with` keyword implicitly permits their matched values to be returned in the result sent back to the front end. This is for two reasons:
+
+1. Displaying the full matched search parameters provides a more coherent user experience. If we only return the `id`, the user won't know if they're selecting the option they're looking for.
+1. Forcing the display of searched values is intended to reduce the risk of giving developers a false sense of security that only values listed in the `providing` keyword will be exposed. An attacker can use trivial techniques to gain the full value of a searchable column without being able to see it in the front end. By including the matched search values in the result, there is no ambiguity that these values are exposed to the front end application.
+
+### Inline Configuration
+
+To allow re-use and to prevent cluttering your views, it is recommended to use [file-based configuration](#file-based), but inline configuration is also available.
+
+We'll re-use the example from above, breaking down exactly what's happening:
+
+```rspec:html
+subject do
+  active_element.component.form model: Pet.new,
+                                fields: [
+                                  :name,
+                                  :animal,
+                                  [:user_id,
+                                   :text_search_field,
+                                   { search: { model: :user, with: [:name, :email], providing: :id } }]
+                                ]
+end
+
+it { is_expected.to include 'Search...' }
+```
+
+First we invoke the `form` component which renders our _HTML_ form, specifying `Pet.new` as the `model`, just like a regular _Rails_ form.
+
+The `fields` array uses the usual format for the `name` and `animal` fields - the field type will be derived from the database type for each field.
+
+The `user_id` field is specified as an array with three elements:
+
+1. The field name, `user_id`. This provides `params[:pet][:user_id]` when the form is submitted to the controller.
+1. The field type, _ActiveElement's_ `text_search_field`.
+1. An options hash, specifically including a `search` key that defines `model`, `with`, and `providing`.
+
+It's important to clarify that specifying these fields in the view is not sufficient to provide security, since they simply provide metadata to help the front-end _Javascript_ component send the correct parameters. A user with access to the application could modify these fields and send arbitrary requests, which is why the [model configuration](#model-configuration) is required.
+
+The `model` option translates `:user` into `User` to identify the _ActiveRecord_ model to use in the search, and the `with` and `providing` options specify the searchable fields (`with`) and the value field (`providing`). Only the `providing` field is included in the request `params`.
+
+### File-based Configuraton
+
+Using inline configuration is fine for one-offs and examples, but it's easy to imagine a form definition becoming cluttered with multiple search fields defined, as well as requiring duplicating and maintaining the same search fields across different forms (e.g. `edit` and `new`).
+
+To mitigate this, file-based configuration is recommended for text search fields.
+
+The above configuration can be redefined by creating `config/forms/pet/user_id.yml`:
+
+```yaml
+# config/forms/pet/user_id.yml
+
+---
+type: text_search_field
+options:
+  search:
+    model: user
+    with:
+    - name
+    - email
+    providing: id
+```
+
+You can still use inline configuration to override these settings, but now the form can be defined as:
+
+```rspec:html
+subject do
+  active_element.component.form model: Pet.new, fields: [:name, :animal, :user_id]
+end
+
+it { is_expected.to include 'Search...' }
+```

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

@@ -0,0 +1,46 @@
+# Form Fields
+
+_ActiveElement_ provides a selection of fields, most of which delegate to _Rails'_ own [form helpers](https://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html).
+
+Extra field types provided by _ActiveElement_ include:
+
+* [`json_field`](form-fields/json.html): A rich _JSON_ schema-based form generator that recursively creates form elements for your _JSON_ objects.
+* [`text_search_field`](form-fields/text-search.html): A full text search/auto-suggest component that provides a secure implementation with minimal configuration.
+* [`check_boxes`](form-fields/check-boxes.html): A set of checkboxes that can optionally be provided as option groups.
+
+Other field types are inferred from the data type and/or column name for each attribute passed to the `fields` array and leverage the existing [form helpers](https://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html) provided by _Rails_. e.g. if you have an _ActiveRecord_ instance with an attribute whose database column type is `date`, a [date field](https://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-date_field) will be automatically rendered. Similarly, a column named `email` will render an [`email_field`](https://api.rubyonrails.org/classes/ActionView/Helpers/FormHelper.html#method-i-email_field).
+
+```rspec:html
+subject do
+  active_element.component.form model: User.new,
+                                fields: [:email, :name, :date_of_birth]
+end
+
+it { is_expected.to include 'type="date"' }
+```
+
+If you need to override these field types, use a two-element array of `[field_name, field_type]`:
+
+```rspec:html
+subject do
+  active_element.component.form model: User.new,
+                                fields: [:email, :name, [:date_of_birth, :text_field]]
+end
+
+it { is_expected.not_to include 'type="date"' }
+```
+
+You can also pass a third element to the array to specify any options you want to pass to the field:
+
+```rspec:html
+subject do
+  active_element.component.form model: User.new,
+                                fields: [
+                                  :email,
+                                  :name,
+                                  [:date_of_birth, :text_field, { class: 'form-control my-class' }]
+                                ]
+end
+
+it { is_expected.to include 'class="form-control my-class"' }
+```

data/rspec-documentation/pages/010-Components/Forms.md

@@ -0,0 +1,44 @@
+# Forms
+
+An interface for creating forms is provided by `active_element.component.form`, available in all views.
+
+The `Form` component delegates to _Rails'_ `form_with` so any keyword arguments not processed by _ActiveElement_ can be passed as usual.
+
+Forms in _ActiveElement_ provide a number of features designed to save you time and help you create powerful and flexible forms with minimal effort:
+
+* Validation errors are automatically rendered for each form element when using _ActiveRecord_ objects or any object that implements `#errors`, `#valid?`, etc.
+* Form inputs are inferred from the database column type of each field specified in the `fields` array.
+* A powerful [_JSON_ editor](form-fields/json.html) is provided for editing complex _JSON_ objects with user-friendly form elements.
+* A [full text search auto-suggest component](form-fields/text-search.html) with a quick and easy setup.
+* Clean and consistent layout.
+
+See the [full keyword argument specification](#options) for information on the various available options and the [Form Fields](form-fields.html) section for documentation on each individual field type.
+
+## Basic Example
+
+```rspec:html
+subject do
+  active_element.component.form model: User.new,
+                                fields: [:name, :email, :enabled]
+end
+
+it { is_expected.to include '<label for="user_name">' }
+```
+
+## Options
+
+Forms receive the following keyword arguments. Any other arguments are passed to the underlying `form_with` call used to generate the form.
+
+| Keyword | Description |
+|-|-|
+| `fields` | An `Array` of `Symbol`. Specifies the fields to render in the form. If a `model` keyword is used then this enables automatic type inference, otherwise the default field type is `text_field`. Pass an array of two-element arrays to specify a specific field type, e.g. `fields: [[:name, :text_field]]`. See [Form Fields](form-fields.html) documentation for available field types.
+| `item` | Optionally pass a `Hash` instead of using `model`. This is useful for e.g. creating a form for generating search parameters.
+| `submit` | Either a `String` specifying the text to display on the submit button, or a hash with the following optional keys: `[:label, :position]`. Set `position` to one of `[:top, :bottom, :both]`, e.g.: `submit: { label: 'Create', position: :top }`.
+| `title` | A `String` specifying a title text to display above the form.
+| `destroy` | A boolean specifying whether to display a "Delete" button above the form. This is only useful for forms editing an existing _ActiveRecord_ object, e.g. in an `edit.html.erb` view. Defaults to `false`.
+| `action` | A `String` that overrides the default action (path the form is submitted to). If this value is not passed, the value is automatically inferred from the current controller path and action: `#new` and `#create` actions to e.g. `/users`, `#edit` and `#update` actions submit to e.g. `/users/:id/edit`.
+| `method` | A `String` that overrides the default method (typically `PATCH` or `POST`). Like `action`, this is automatically inferred from the current controller path and action.
+| `modal` | A boolean specifying whether to provide a button that opens the form as a modal. Defaults to `false`.
+| `columns` | An `Integer` specifying how many columns to use when rending form inputs. Defaults to `1`.
+
+For typical _Rails_ _RESTful_ routing patterns using _ActiveRecord_ objects you will usually only need to specify `model` and `fields`.

data/rspec-documentation/pages/010-Components/JSON Data.md

@@ -0,0 +1,23 @@
+# JSON
+
+The `json` component provides a mechanism for converting _Ruby_ objects and storing them as _JSON_ within your _HTML_ so that it can be later accessed by any _Javascript_ code running in your application.
+
+The implementation is simple but is intended to avoid repetition of serialization and ensures that all _JSON_ data you output is stored consistently in one location.
+
+_JSON_ data is available to _Javascript_ code as `ActiveElement.jsonData`. The component receives a key and an object to be serialized. The key is converted to camel case to provide conventionally-named _Javascript_ accessors.
+
+Note that only the data key is converted to camel case. The data object itself is not transformed in any way aside from converting directly to _JSON_.
+
+```rspec:html
+subject do
+  active_element.component.json :my_data, { some: { example: 'data' } }
+end
+
+it { is_expected.to include '"myData"' }
+```
+
+The data is now available to _Javascript_ code - try running the following code in your browser's _Javascript_ console:
+
+```javascript
+console.log(ActiveElement.jsonData.myData);
+```

data/rspec-documentation/pages/010-Components/Navbar.md

@@ -0,0 +1,56 @@
+# Navbar
+
+A default _Navbar_ is provided automatically for any controllers that inherit from `ActiveElement::ApplicationController` and included in the default [Layout](../layout.html).
+
+The _Navbar_ is generated from `#index` routes for all _ActiveElement_ controllers.
+
+For example, if you have a `BookingsController` and `UsersController` that both inherit from `ActiveElement::Controller` (either directly or via common parent controller that inherits from `ActiveElement::ApplicationController`) and provide an `#index` action, your _Navbar_ will contain links for _Users_ and _Bookings_.
+
+The _Navbar_ brand is calculated from the name of the application `module` as defined in `config/application.rb`.
+
+If you wish to override the default _Navbar_ configuration, create an initializer and set your desired options:
+
+## Configuration
+
+```ruby
+# config/initializers/active_element.rb
+
+ActiveElement.application_name = 'My Bookings System'
+ActiveElement.navbar_items = [
+  { label: 'Bookings', path: '/bookings' },
+  { label: 'Users', path: '/users' },
+  { label: 'New Booking', path: '/bookings/new' }
+]
+```
+
+Note that overriding the default `navbar_items` means that all _Navbar_ items must now be manually configured and _ActiveElement_ will not infer any new items as new controllers/routes are added to your application.
+
+## Custom Usage
+
+If you prefer to use a custom `layout` instead of the default provided by _ActiveElement_, the `navbar` component can be used like any other component. The default _Navbar_ uses `position: fixed` to keep the _Navbar_ visible when the user scrolls. This can be disabled by passing `fixed: false`.
+
+```rspec:html
+subject do
+  active_element.component.navbar(fixed: false)
+end
+
+it { is_expected.to include 'Users' }
+```
+
+The `navbar` component can also receive a custom set of options if you wish to have different menu items for certain pages.
+
+```rspec:html
+subject do
+  active_element.component.navbar(fixed: false, items: [{ label: 'Custom Link', path: '/custom' }])
+end
+
+it { is_expected.to include 'Custom Link' }
+```
+
+## Options
+
+| Keyword | Description |
+|-|-|
+| `fixed` | Enable or disable `position: fixed` on the _Navbar_ element to allow it to stay visible when the user scrolls. Defaults to `true`.
+| `items` | An array of `{ label: ..., path: ...}` specifying all items that should appear in the _Navbar_.
+

data/rspec-documentation/pages/010-Components/Page Section Title.md

@@ -0,0 +1,13 @@
+# Page Section Title
+
+Another very basic component, similar to [`page_title`](page-title.html) and [`page_subtitle`](page-subtitle.html).
+
+Use this component to add a title to individual sections of your page.
+
+```rspec:html
+subject do
+  active_element.component.page_section_title 'Features'
+end
+
+it { is_expected.to include 'Features' }
+```

data/rspec-documentation/pages/010-Components/Page Subtitle.md

@@ -0,0 +1,11 @@
+# Page Subtitle
+
+Like the [`page_title`](page-title.html) component, `page_subtitle` provides a simple heading tag.
+
+```rspec:html
+subject do
+  active_element.component.page_subtitle 'Introduction'
+end
+
+it { is_expected.to include 'Introduction' }
+```

data/rspec-documentation/pages/010-Components/Page Title.md

@@ -0,0 +1,11 @@
+# Page Title
+
+The `page_title` component provides a simple `<h2>` tag. It's very basic but it gives you a consistent way to generate page titles that can be amended later to include any classes that you want to apply to all instances of the component.
+
+```rspec:html
+subject do
+  active_element.component.page_title 'Welcome to ActiveElement'
+end
+
+it { is_expected.to include 'Welcome to ActiveElement' }
+```

data/rspec-documentation/pages/010-Components/Tables/Collection Table.md

@@ -0,0 +1,29 @@
+# Collection Table
+
+The _Collection Table_ component provides a vertical table containing a collection of items. Use with _Active Record_ model instances, an array of objects that extend `ActiveModel::Naming`, or simple hash-like objects.
+
+Field types are automatically inferred from their respective database columns and rendered using an appropriate formatter.
+
+Pagination (provided by [Kaminari](https://github.com/kaminari/kaminari)) is enabled by default for larger collections.
+
+See the [full keyword argument specification](options.html) for information on the various available options.
+
+```rspec:html
+collection = [
+  User.new(name: 'John', email: 'john@example.com', enabled: true),
+  User.new(name: 'Jane', email: 'jane@example.org', enabled: false),
+  User.new(name: 'Peter', email: 'peter@example.org', enabled: false),
+  User.new(name: 'Sally', email: 'sally@example.org', enabled: true)
+]
+
+subject do
+  active_element.component.table collection: collection,
+                                 fields: [:name, :email, :enabled],
+                                 show: true,
+                                 new: true,
+                                 edit: true,
+                                 destroy: true
+end
+
+it { is_expected.to include 'John' }
+```

data/rspec-documentation/pages/010-Components/Tables/Item Table.md

@@ -0,0 +1,18 @@
+# Item Table
+
+The _Item Table_ component provides a horizontal table containing a single item and its attributes. Use with an _Active Record_ model instance, an object that extends `ActiveModel::Naming`, or a simple hash-like object.
+
+See the [full keyword argument specification](options.html) for information on the various available options.
+
+```rspec:html
+item = User.new(name: 'John', email: 'john@example.com', overview: 'Writes Ruby code for a living.')
+
+subject do
+  active_element.component.table item: item,
+                                 fields: [:name, :email, :overview],
+                                 edit: true,
+                                 destroy: true
+end
+
+it { is_expected.to include 'John' }
+```

data/rspec-documentation/pages/010-Components/Tables/Options.md

@@ -0,0 +1,19 @@
+# Options
+
+Tables receive the following keyword arguments:
+
+| Keyword | Description |
+|-|-|
+| `collection` | A collection of objects. Must be iterable, e.g. the result of calling `where` on an _ActiveRecord_ model. Renders a [Collection Table](tables/collection-table.html)
+| `item` | A single object. Renders an [Item Table](tables/item-table.html). Note that you must use either `collection` or `item` but not both.
+| `fields` | _(Required)_ An array specifying the fields to display in the table. The keys specified in this array can be either hash keys or _ActiveRecord_ attribute names.
+| `model_name` | Pass `model_name` if you are not using _ActiveRecord_ objects, e.g. if you are passing a hash or array of hashes, `model_name` should be provided to provide decorators, translations, CSS classes, etc. This argument should be omitted for _ActiveRecord_ objects (or any object that implements `ActiveModel::Naming`. |
+| `class_name` | Provide an explicit class name to override the default derived from the received _ActiveRecord_ model class or the `model_name` parameter.
+| `show` | A _boolean_ value specifying whether to display a _Show_ button in a `collection` table. The path for the link is derived from the received _ActiveRecord_ object, e.g. `user_path(record)`
+| `destroy` | A _boolean_ value specifying whether to display a _Delete_ button for each record in a `collection` table or for the single record in an `item` table. Links to e.g. `user_path(record, method: :delete)`
+| `edit` | A _boolean_ value specifying whether to display an _Edit_ button. Links to e.g. `edit_user_path(record)`
+| `new` | A _boolean_ value specifying whether to display a "Create new ..." button above a `collection` table. Links to e.g. `new_user_path`
+| `style` | Specify a _CSS_ string to be inserted into the `<table>` tag.
+| `row_class` | Specify a class to be inserted into each `<tr>` tag in a `collection` table. Can be a `String` or a `Proc`. A `Proc` will receive the record as an argument, e.g.: `row_class: ->(record) { record.deleted_at.present? 'text-danger' : 'text-primary' }`
+| `group` | Group rows in a `collection` by a given attribute, e.g.: `group: :country_code`.
+| `paginate` | Enable or disable pagination for `collection` tables. Defaults to `true`.

data/rspec-documentation/pages/010-Components/Tables.md

@@ -0,0 +1,29 @@
+# Tables
+
+An interface for creating tables is provided by `active_element.component.table`, available in all views.
+
+The two table types provided are [Collection Table](tables/collection-table.html) and [Item Table](tables/item-table.html).
+
+See the [full keyword argument specification](tables/options.html) for information on the various available options.
+
+## Basic Example
+
+```rspec:html
+collection = [
+  User.new(name: 'John', email: 'john@example.com', enabled: true),
+  User.new(name: 'Jane', email: 'jane@example.org', enabled: false),
+  User.new(name: 'Peter', email: 'peter@example.org', enabled: false),
+  User.new(name: 'Sally', email: 'sally@example.org', enabled: true)
+]
+
+subject do
+  active_element.component.table collection: collection,
+                                 fields: [:name, :email, :enabled],
+                                 show: true,
+                                 new: true,
+                                 edit: true,
+                                 destroy: true
+end
+
+it { is_expected.to include 'John' }
+```

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

@@ -0,0 +1,15 @@
+# Components
+
+The core of _ActiveElement_ is its set of components. These components are intended to be used within _Rails_ views to reduce the amount of _HTML_ developers need to write, as well as standardizing the look and feel of your application. A typical admin application should need very little (if any) custom _HTML_. If custom _HTML_ is needed, the composable nature of the provided components allows for this.
+
+See the individual documentation sections for each component, and visit the [Decorators](decorators.html) section to see how you can write composable partials to override the default data formatters as needed.
+
+All examples demonstrate how to use a component in a _Rails_ view. Every view rendered by a controller that inherits from `ActiveElement::ApplicationController` will have the `active_element` method available to them.
+
+To use a component in your view, call (e.g.) `active_element.component.form` to render a [Form](components/form.html) component:
+
+```erb
+<%# app/views/users/new.html.erb %>
+
+<%= active_element.component.form model: User.new, fields: [:email, :name] %>
+```

data/rspec-documentation/pages/020-Access Control/010-Authentication.md

@@ -0,0 +1,20 @@
+# Authentication
+
+Authentication is enabled by calling `active_element.authenticate_with` from a controller, typically your `ApplicationController`, or some base controller used for a restricted namespace. `active_element.authenticate_with` receives a block which calls your chosen authentication framework's user authentication.
+
+
+The recommended way to handle authentication with _ActiveElement_ is to use `prepend_before_action` which calls the authenticator:
+
+```ruby
+class ApplicationController < ActionController::Base
+  prepend_before_action :configure_authentication
+
+  private
+
+  def configure_authentication
+    active_element.authenticate_with { authenticate_user! }
+  end
+end
+```
+
+Passing the authenticator to _ActiveElement_ is optional and you are free to handle your own authentication, but allowing _ActiveElement_ to call the authenticator is required if you wish to utilize the [authorization model](access-control/authorization.html).

data/rspec-documentation/pages/020-Access Control/020-Authorization/Environments.md

@@ -0,0 +1,9 @@
+# Environments
+
+The documentation in this section covers behaviours as they are defined for deployment environments. Note that in a `development` environment all permissions checks are bypassed, with clear logging describing all permissions that would be expected in a deployment environment.
+
+Since a developer is running an application locally and they are able to modify the application's code, applying permissions in this environment would not add any level of security. Instead, developers receive a clear indication of what permissions they must define in a deployment environment while not being hampered in their work by the authorization model.
+
+To ensure that an application's permissions requirements are taken into account during development, permissions **are** required in a `test` environment. This allows developers to ensure that their application is capable of defining the permissions needed to access it and to verify access control correctness with fixture data.
+
+To assist developers when writing tests, permissions failures are logged to `stderr` the `test` environment, as well as to the application's default log file. i.e. permissions failures will appear in-line with output from the application's test suite and are less likely to go unnoticed.

data/rspec-documentation/pages/020-Access Control/020-Authorization/Permissions/Custom Routes.md

@@ -0,0 +1,41 @@
+# Custom Routes
+
+If you have any routes defined that do not fall under the routes automatically defined by _Rails_ with the `resources` routes helper (i.e. anything other than `index`, `show`, `new`, `create`, `edit`, `update`, `destroy`) you **must** have an explicit permission configuration defined. This design choice is intended to reduce the risk of accidental exposure of sensitive data by defaulting to having all routes protected. _ActiveElement_ will raise `ActiveEleement::UnprotectedRouteError` if an unprotected route is defined.
+
+_ActiveElement_ provides `active_element.permit_action`, available in all controllers that inherit from `ActiveElement::ApplicationController`.
+
+Use this helper to define a permission that a user must have in order to access a route or, if the route is intended to be available for any signed-in user, specify that it is always permitted.
+
+```ruby
+# app/controllers/application_controller.rb
+
+class ApplicationController < ActiveElement::ApplicationController
+  prepend_before_action :configure_authentication
+
+  private
+
+  def configure_authentication
+    active_element.authenticate_with { authenticate_user! }
+    active_element.authorize_with { current_user }
+  end
+end
+```
+
+```ruby
+# app/controllers/bookings_controller.rb
+
+class BookingsController < ApplicationController
+  active_element.permit_action :export_csv, with: 'can_export_bookings_csv'
+  active_element.permit_action :remaining_tickets, always: true
+
+  def export_csv
+    # ...
+  end
+
+  def remaining_tickets
+    # ...
+  end
+end
+```
+
+In this example, `#export_csv` is only accessible to users with the `can_export_bookings_csv` permission, and `#remaining_tickets` is always available to any who has passed initial authentication.

data/rspec-documentation/pages/020-Access Control/020-Authorization/Permissions.md

@@ -0,0 +1,58 @@
+# Permissions
+
+In the [Setup](setup.html) example, `current_user` (typically returning an instance of an _ActiveRecord_ `User` model) must implement a method `#permissions` which returns an array of strings. You are free to implement this however you like, whether you store your permissions as a _JSON_ array in your database, in a join table, or via an external _API_ call.
+
+_ActiveElement_ requires various inferred permissions to be present in order for a user to access a _Rails_ route. If a user does not have permissions, a splash screen appears informing the user what permissions they need to access the resource.
+
+Permission names are based on the following templates:
+
+|Permission Template|Relevant Controller Actions|
+|`can_list_<application>_<namespace>_<controller>`|`#index`
+|`can_view_<application>_<namespace>_<controller>`|`#show`
+|`can_edit_<application>_<namespace>_<controller>`|`#edit`, `#update`
+|`can_create_<application>_<namespace>_<controller>`|`#new`, `#create`
+|`can_delete_<application>_<namespace>_<controller>`|`#destroy`
+
+e.g. if your application is defined as:
+
+```ruby
+# config/application.rb
+
+module BookingSystem
+  class Application < Rails::Application
+  end
+end
+```
+
+and you have your controllers namespaced under `admin`:
+```ruby
+# config/routes.rb
+
+namespace :admin do
+  resources :bookings
+end
+```
+
+then the following permissions will be applied:
+
+* `can_list_booking_system_admin_bookings`
+* `can_view_booking_system_admin_bookings`
+* `can_edit_booking_system_admin_bookings`
+* `can_create_booking_system_admin_bookings`
+* `can_delete_booking_system_admin_bookings`
+
+Note that permissions are not mapped 1:1 to controller actions. This design choice is intended to reduce the risk of e.g. revoking a permission only for the `#edit` action and being misled into thinking that this would prevent a user from submitting a request directly to the `#update` action. `#index` and `#show` are implemented as separate permissions as it is expected that one view may provide more detailed information than another.
+
+## Listing Permissions
+
+All permissions can be viewed at any time by running the provided _Rake_ task:
+
+```console
+$ rake active_element:permissions
+
+* can_list_booking_system_admin_bookings
+* can_view_booking_system_admin_bookings
+* can_edit_booking_system_admin_bookings
+* can_create_booking_system_admin_bookings
+* can_delete_booking_system_admin_bookings
+```

data/rspec-documentation/pages/020-Access Control/020-Authorization/Setup.md

@@ -0,0 +1,27 @@
+## Setup
+
+Enable authorization in your application by calling `active_element.authenticate_with` and `active_element.authorize_with` from a `prepend_before_action`. For example, if you are using [Devise](https://github.com/heartcombo/devise):
+
+```ruby
+# app/controllers/application_controller.rb
+
+class ApplicationController < ActionController::Base
+  prepend_before_action :configure_authentication
+
+  private
+
+  def configure_authentication
+    active_element.authenticate_with { authenticate_user! }
+    active_element.authorize_with { current_user }
+  end
+end
+```
+
+Adjust the provided example to suit your application's authentication framework.
+
+As long as the following conditions are met then your application is ready to use _ActiveElement's_ authorization system:
+
+* The method in the block sent to `active_element.authenticate_with` renders or redirects on authentication failure.
+* The method in the block sent to `active_element.authorize_with` returns an object that implements a `#permissions` method which returns an array of strings.
+
+

data/rspec-documentation/pages/020-Access Control/020-Authorization.md

@@ -0,0 +1,11 @@
+# Authorization
+
+_ActiveElement_ provides a comprehensive and robust authorization model to limit access to specific areas of your application to specific users. Any custom authorization not provided by _ActiveElement_ can be implemented using whatever setup you prefer, either by writing your own `before_action` methods that restrict access, e.g. by calling `head :unauthorized`, or by using a more advanced authorization framework like [Pundit](https://github.com/varvet/pundit) or [CanCanCan](https://github.com/CanCanCommunity/cancancan).
+
+_ActiveElement_ does not attempt to replace the functionality of such frameworks and does not prevent their usage. Instead, the focus is on providing default permissions for accessing specific controller actions. Access control of particular data resources is left to the application and there are numerous high quality frameworks that provide this functionality.
+
+If any controller inherits from `ActiveElement::ApplicationController` then it will automatically have permissions applied to all of its controller actions and, if authorization is enabled, users must have the required permissions to access. This provides an automated [least-privelege model](https://en.wikipedia.org/wiki/Principle_of_least_privilege) to all of your application's endpoints with minimal effort.
+
+Note that actions that exist out of the standard set of _Rails_ _RESTful_ resources (i.e. `index`, `show`, `new`, `create`, `edit`, `update`, `destroy`) **must** have an explicit permission configuration defined using `active_element.permit_action`. See [Custom Routes](authorization/permissions/custom-routes.html) for more information.
+
+See the [Setup](authorization/setup.html) and [Permissions](authorization/permissions.html) sections to get started.