edit_in_place 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1a49b654229bb462de8d09e761fb800ef58647a8964b793e90c308e29b65589b
+  data.tar.gz: dbc63f81542231c4defe07042f10664cf0376a61f47a41abf2983175134671ba
+SHA512:
+  metadata.gz: 615184175d7f147d9764c2a35ce3246e3114db24e33699ad02bfd422e8e6d9021653f2600ee0793245966e76538a8ccd286fd4e0c2aca361ddf29da279e5e76d
+  data.tar.gz: fef7dc43b4333a89fe8d23b3f62d92aabbca2372fffca8535899c6b089c21be8f64201621eea27c71c26f7e9aed54a7a97d4027963f69dc6519877ca6cc60218

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2021 Jacob
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,301 @@
+# EditInPlace
+
+[![Build Status](https://travis-ci.com/jacoblockard99/edit_in_place.svg?branch=master)](https://travis-ci.com/jacoblockard99/edit_in_place)
+[![Inline docs](http://inch-ci.org/github/jacoblockard99/edit_in_place.svg?branch=master)](http://inch-ci.org/github/jacoblockard99/edit_in_place)
+[![Maintainability](https://api.codeclimate.com/v1/badges/389fc591cd9cccb2ceb1/maintainability)](https://codeclimate.com/github/jacoblockard99/edit_in_place/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/389fc591cd9cccb2ceb1/test_coverage)](https://codeclimate.com/github/jacoblockard99/edit_in_place/test_coverage)
+
+`edit_in_place` is a Rails plugin that facilitates the creation of user interfaces that allow the user to edit content "in place" in a natural way. `edit_in_place` aims to be:
+  - **Flexible.** Everything has been designed with extensibility in mind. The `edit_in_place` core (this repository) can be extended for a huge variety of use cases.
+  - **Reliable.** Every aspect of the plugin is thoroughly tested and documented.
+  - **Natural.** Coding with `edit_in_place` is just as natural as editing content with it is! We think you'll really enjoy working with the `edit_in_place` API.
+
+## Links
+
+  - [API Docs](https://rubydoc.info/github/jacoblockard99/edit_in_place)
+  - [CHANGELOG.md](CHANGELOG.md)
+  - [Releases](https://github.com/jacoblockard99/edit_in_place/releases)
+
+## Installation
+
+`edit_in_place` is a Ruby gem. If you use Bundler, you may install it by adding it to your `Gemfile`, like so:
+
+```ruby
+gem 'edit_in_place'
+```
+
+And then execute:
+```bash
+$ bundle install
+```
+
+Or you may install it manually with:
+```bash
+$ gem install edit_in_place
+```
+
+`edit_in_place` currently has two dependencies: `rails` and `middlegem`.
+
+## Concepts
+
+`edit_in_place` is—at the most fundamental level—a tool to render content in different _modes_.
+
+This begins with the concept of a _field_, which is a single, self-contained piece of modal content. Given the same input, but different modes, a field can be rendered differently. This functionality could be used in a variety of cases, but is especially useful for creating "editable content". As an example, imagine that we have built a static website. On that website, we would like to allow the owner to modify certain parts of it. The way we would approach this with `edit_in_place` is to make each editable portion of the page a field. Then, when the site is being viewed by a visitor, we render all the fields in a `:viewing` mode, but when being edited by the owner, an `:editing` mode. Each field is then rendered differently, given the appropriate mode. A "text" field, for example, might render plain text in a `:viewing` mode, but some kind of text input in an `:editing` mode.
+
+A _field type_ is a subclass of `EditInPlace::FieldType` that is essentially a template for a field. Given various options, including a mode, it is in charge of actually rendering the field.
+
+To render a field, the `EditInPlace::Builder#field` method is used. Given a field type, field options, and an input, it will merge the field options with the default ones, transform the input as appropriate, and use the `FieldType` to render the content, returning the result. This is where the flexibility of `edit_in_place` begins to reveal itself: you see, the "input" given to `#field` is completely arbitrary! In other words, you can set up field types to accept whatever input they need to render the field. That means that you have virtually limitless options for how exactly you acquire and save editable data—`edit_in_place` doesn't care.
+
+Furthermore, `edit_in_place` has the concept of field "middlewares". You can pass middlewares ([`middlegem`](https://github.com/jacoblockard99/middlegem/) is used for middlewares) to `#field` that can arbitrarily transform its input. This can be used for a host of things—transforming the data, validating the input, adding arguments to the input based on context, or really anything you want.
+
+Of course, with this power comes significant verbosity. With only the `edit_in_place` core, you would need to set everything up yourself. However, in many cases, editable content with `edit_in_place` follows a fairly set pattern: "models" (not necessarily ActiveRecord ones) store editable attribtues; an `edit_in_place` field corresponds to one (or occasionally more) attributes; and the "editable" version of a field is a form input which allows the data to be saved back to a data store. For this functionality, see the `edit_in_place` extension [`models_in_place`](https://github.com/jacoblockard99/models_in_place).
+
+## Usage
+
+### Field Types
+
+A fair amount of configuration is required to get started with `edit_in_place` if you're not using `models_in_place`. The first step is to define some field types, which provide templates for generated fields. This can be done by extended the `FieldType` class and doing one of the following:
+  1. Overriding the `render` method, which is called regardless of the mode.
+  2. Relying on the default `render` implementation, and overriding one of the `render_*` that it will call.
+Here are a few examples:
+
+```ruby
+# text_field_type.rb
+
+class TextFieldType < EditInPlace::FieldType
+  protected
+
+  def render_viewing(options, name, value)
+    options.view.tag.p value
+  end
+
+  def render_editing(options, name, value)
+    options.view.text_field_tag name, value
+  end
+end
+```
+
+```ruby
+# boolean_field_type.rb
+
+class DummyFieldtype < EditInPlace::FieldType
+  def render(options, *)
+    "You are currently #{options.mode} the webpage!"
+  end
+end
+```
+
+Notice that the `render` method is passed an options parameter, which is an instance of `EditInPlace::FieldOptions`, that contains the view context and the mode. Also note how `render_viewing` and `render_editing` will be called according to the current mode. If you want to define a `render_*` method for a different mode, you'll need to override the `supported_modes` method, like so:
+
+```ruby
+class LockedField
+  protected
+
+  def render_viewing(*)
+    'You are viewing this field!'
+  end
+  
+  def render_editing(*)
+    'You are editing this field!'
+  end
+
+  def render_admin_editing(*)
+    'You are editing this field as an admin!'
+  end
+
+  def supported_modes
+    [:viewing, :editing:, :admin_editing]
+  end
+end
+```
+
+Attempts to call `render` with a mode that is not is `supported_modes` will result in an `EditInPlace::UnsupportedModeError`, even if the field type has a corresponding `render_*` method.
+
+As mentioned earlier, one of the aims of `edit_in_place` is to be natural for the developer. Thus, in the interests of convenience, `edit_in_place` allows you to "register" field types with a name, making them easier to use. We might register our "text" field type, for example, like this:
+
+```ruby
+EditInPlace.configure do |c|
+  c.field_types.register :text, TextFieldType.new
+end
+```
+
+Now this:
+
+```erb
+<%= @builder.field TextFieldType.new, 'contact_name', 'Jacob' %>
+```
+
+Becomes:
+
+```erb
+<%= @builder.field :text, 'contact_name', 'Jacob' %>
+```
+
+Note that field type names must be symbols—strings are not allowed. Also note that duplicate registrations are not alowed and will raise an `EditInPlace::DuplicateRegistrationError`.
+
+### Configuring a Builder
+
+The next step is creating and using an `EditInPlace::Builder` instance. A builder always has an `EditInPlace::Configuration` instance that contains all its options and context. When a builder is first instantiated, its configuration is copied from the global `EditInPlace` configuration. Thus, you can set any global configuration options using `EditInPlace.config` or `EditInPlace.configure`, and all builders with use those options by default. For example:
+
+```ruby
+EditInPlace.configure do |c|
+  c.field_options.mode = :editing
+end
+```
+
+This would make editing the *default* mode. Then, you can modify builder-specific configuration using `Builder#config` or `Builder#configure`, like so:
+
+```ruby
+@builder = Builder.new # current mode is :editing
+@builder.config.field_options.mode = :viewing # switched to :viewing
+```
+
+Both `EditInPlace.config` and `Builder#config` are `EditInPlace::Configuration` instances, so you configure them identically. You are encouraged to check out the [docs](https://rubydoc.info/github/jacoblockard99/edit_in_place/EditInPlace/Configuration) on `Configuration` to see all the available configuration options.
+
+Only two options are really critical to using the builder: the view context and the mode. The view context is necessary when the field type needs access to a view context to render the field. In our `TextFieldType` example above, for example, the `text_field_tag` method was required. Probably the easiest way to pass the view context is to simply use the `view_context` method in Rails controllers. For example:
+
+```
+class SomeController
+  def index
+    @builder = Builder.new
+    @builder.field_options.view = view_context
+  end
+end
+```
+
+Now, field types will automatically have access to the view context. This method has some pitfalls, however, most importantly that `view_context` returns a _new_ view context, not the one used in the actual view. If you must have the actual view context object, something like this could be done instead:
+
+```erb
+<% @builder.field_options.view = self %>
+
+<%= @builder.field :text, "hello, world" %>
+```
+
+Of course, you would need to put this at the top of all your views.
+
+There are a few approaches to managing builder modes. One approach is to have a seperate controller for each, like so:
+
+```ruby
+class ViewingController < ApplicationController
+  def index
+    @builder = Builder.new
+
+    render 'some_page'
+  end
+end
+```
+
+```ruby
+class EditingController < ApplicationController
+  def index
+    @builder = Builder.new
+    @builder.config.field_options.mode = :editing
+    
+    render 'some_page'
+  end
+end
+```
+
+Then, in the 'some_page' view you can use the builder in the exact same way, but get different results because of the different mode. Other options are possible, however. Use whatever works best!
+
+### Rendering Fields
+
+Once you have some fields types and a builder, you are ready to actually render some fields! The `Builder#field` method is used to render a field of a given type, with the given options, and the given input. For example, with our previous `TextFieldType` example:
+
+```erb
+<%= @builder.field :text, 'phone_number', '(123) 456-7890' %>
+```
+
+When viewing the site, the user would see a simple paragraph containing the phone number. When editing the site, the user would see an editable text input. Of course, the text input currently would do nothing—you are in charge of ensuring that the data actually gets saved. You can do this however you want, but typically the fields are submitted via a form or via AJAX to a controller which saves the data. As part of the philosphy of flexibility, `edit_in_place` makes no attempt whatsoever to handle any of this.
+
+If the second argument to `Builder#field` is either a `FieldOptions` instance or a hash, then it will be used as the options for the field. For example, you could render a specific field as always editable:
+
+```erb
+<%= @builder.field :text, { mode: :editing }, 'phone_number', '(123) 456-7890' %>
+```
+
+If your field type happens to expect the first input argument to be a hash, you will need to pass an empty options hash, like this:
+
+```erb
+<%= @builder.field :some_type, {}, { option: true }, 'etc' %>
+```
+
+### Middlewares
+
+Perhaps the most powerful feature of `edit_in_place` are the field middlewares. `edit_in_place` uses [`middlegem`](https://github/jacoblockard99/middlegem) for middlewares, which you may want to briefly review. Field middlewares allow the inputs to a field to be transformed before actually making it to the field type's `render` method. The use cases for this are limitless.
+
+There are two steps for using field middlewares: defining them and using them. First, you must define all the middleware classes that you will be using in your application. This is to ensure that middlewares are always run in the right order. For example, let's say we have two middleware classes, one that multiplies a number by 10, and another that surrounds it with parentheses. We would define the middleware as follows:
+
+```ruby
+EditInPlace.configure do |c|
+  c.defined_middleware = [
+    MultiplyMiddleware,
+    ParenthesesMiddleware
+]
+```
+
+This will ensure that, no matter what order they're added, the `MultplyMiddleware` will always be run before the `ParenthesesMiddleware`. If a middleware is used that has not been defined, a `Middlegem::UnpermittedMiddleware` error will be raised by `middlegem`.
+
+Next, the middlewares can be actually used. Middlewares reside in the `FieldOptions` class, meaning you have three options for adding middlewares to fields: adding it to the global `EditInPlace` configuration, adding it to the `Builder` configuration, and passing them to `Builder#field`. You might want all fields to be surrounded in parentheses, for example, but only some to be multiplied by ten. This could be accomplished with:
+
+```ruby
+class SomeController
+  def index
+    @builder = Builder.new
+    @builder.config.field_options.middlewares << ParenthesesMiddleware.new
+  end
+end
+```
+
+```erb
+<%= @builder.field :text, { middlewares: [MultiplyMiddleware.new] }, 'name', '500' %>
+<%= @builder.field :text, 'name', 'a string' %>
+```
+
+Now, when viewing the site, the first one would show "(5000)" and the second would show "(a string)". Note that middlewares are often too verbose to be easily used like this. They are really best used by edit_in_place extensions.
+
+### Scoped Builders
+
+There will likely be times when you wish for many fields to have the same `FieldOptions`. This can be accomplished with the `Builder#scoped` method, which allows field options to be shared across a block. For example:
+
+```erb
+<%= @builder.scoped middlewares: [AppendArgumentMiddleware.new('example')] |b| do %>
+  <%= b.field :text, 'name', 'value' %>
+<% end %>
+```
+
+Now any fields generated with the scoped `b` builder will have an `'example'` argument appended to their input (assuming that `AppendArgumentMiddleware` has been defined).
+
+### Extending Builder
+
+If you are developing an extension for `edit_in_place`, you may wish to add methods to `Builder`. While you could create a subclass, subclassing has its share of problems. You could not, for example, use multiple builder subclasses at once. Thus, `edit_in_place` provides an `ExtendedBuilder` class which you can use to add **new** methods to `Builder`. Essentially, `ExtendedBuilder` stores a base builder and delegates all missing method calls to it. You can use it like:
+
+```ruby
+class MyBuilderExtension < EditInPlace::ExtendedBuilder
+  def hello
+    'Hello, world!'
+  end
+end
+```
+
+And then instantiate it:
+
+```ruby
+class SomeController < ApplicationController
+  def index
+    base = Builder.new
+    @my_builder = MyBuilderExtension.new(base)
+  end
+end
+```
+
+Then, in the view:
+
+```erb
+<%= @my_builder.hello %>
+```
+
+These builder extension can be chained as many times as desired. Please note however that *you should only add new methods*, never override existing ones. If you override existing methods, further down the chain, that method may be called, and will not be sent to your extension, which could cause some confusing results.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+require 'bundler/gem_tasks'
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/lib/edit_in_place.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'edit_in_place/version'
+require 'edit_in_place/railtie'
+require 'edit_in_place/builder'
+require 'edit_in_place/configuration'
+require 'edit_in_place/registrar'
+require 'edit_in_place/extended_builder'
+require 'edit_in_place/field_options'
+require 'edit_in_place/field_type'
+require 'edit_in_place/field_type_registrar'
+
+# {EditInPlace} is a namespace that contains all the modules and classes of the edit_in_place
+# Rails gemified plugin.
+#
+# @author Jacob Lockard
+# @since 0.1.0
+module EditInPlace
+  # {Error} is a subclass of {https://ruby-doc.org/core-2.5.0/StandardError.html StandardError}
+  # from which all custom errors in edit_in_place are derived. One potential use for this class
+  # is to rescue all custom errors produced by edit_in_place. For example:
+  #
+  #   begin
+  #     # Do something risky with edit_in_place here...
+  #   rescue EditInPlace::Error
+  #     # Catch any edit_in_place-specific error here...
+  #   end
+  #
+  # @see https://ruby-doc.org/core-2.0.0/Exception.html
+  class Error < StandardError; end
+
+  @config = Configuration.new
+
+  # Gets the `Configuration` instance that represents the global configuration for the
+  # edit_in_place plugin. The global configuration will be applied to all created {Builder}
+  # instances.
+  # @return [Configuration] the global configuration.
+  # @see Configuration
+  def self.config
+    @config
+  end
+
+  # Sets the `Configuration` instance that represents the global configuration for the
+  # edit_in_place plugin. A convenient use for this method is to reset the global configuration
+  # by setting it to +EditInPlace::Configuration.new+.
+  # @param config [Configuration] the global configuration.
+  # @return [void]
+  # @see Configuration
+  def self.config=(config)
+    @config = config
+  end
+
+  # Configures the edit_in_place plugin by yielding the global configuration to the given block.
+  # This is a convenient way to configure the plugin. For example:
+  #
+  #   EditInPlace.configure do |c|
+  #     c.field_options.mode = :editing
+  #     c.defined_middlewares = [SomeMiddleware, AnotherMiddleware]
+  #   end
+  # @yieldparam config [Configuration] the {Configuration} instance of the edit_in_place plugin.
+  # @yieldreturn [void]
+  # @return [void]
+  # @see Configuration
+  def self.configure
+    yield config if block_given?
+  end
+end
+
+require 'edit_in_place/invalid_field_type_error'
+require 'edit_in_place/unregistered_field_type_error'
+require 'edit_in_place/invalid_registration_name_error'
+require 'edit_in_place/duplicate_registration_error'

data/lib/edit_in_place/builder.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module EditInPlace
+  # {Builder} is the class that provides the actual functionality to build and render editable
+  # content. This class will usually be instantiated in a controller and passed somehow to a
+  # view. The view can then use its methods to generate content. Note that when a {Builder} is
+  # created, it's {Configuration} is copied from the global configuration.
+  #
+  # This class can be extended by utilizing {ExtendedBuilder} to safely add additional
+  # functionality. This can be particularly helpful for edit_in_place extensions that would like
+  # to add other content generation methods without requiring the user to yield another builder
+  # to the view.
+  #
+  # @author Jacob Lockard
+  # @since 0.1.0
+  class Builder
+    # The {Configuration} instance that stores the options for this {Builder}.
+    # @return [Configuration] the configuration for this {Builder}.
+    # @note This configuration is initially derived from the global configuration defined in
+    #   {EditInPlace.config}.
+    attr_accessor :config
+
+    # Creates a new instance of {Builder}.
+    def initialize
+      @config = EditInPlace.config.dup
+    end
+
+    # Creates a deep copy of this {Builder}, whose configuration can be safely modified.
+    # @return [Builder] a deep copy of this {Builder}.
+    def dup
+      b = Builder.new
+      b.config = config.dup
+      b
+    end
+
+    # Configures this {Builder} by yielding its configuration to the given block. For example,
+    #
+    #   @builder = EditInPlace::Builder.new
+    #   @builder.configure do |c|
+    #     c.field_options.mode = :editing
+    #     c.field_options.middlewares = [:one, :two]
+    #   end
+    #
+    # Note that this method is simply a convenience method, and the above code is exactly
+    # equivalent to the following:
+    #
+    #   @builder = EditInPlace::Builder.new
+    #   @builder.config.field_options.mode = :editing
+    #   @builder.config.field_options.middlewares = [:one, :two]
+    # @yieldparam config [Configuration] the {Configuration} instance associated with this
+    #   {Builder}.
+    # @yieldreturn [void]
+    # @return [void]
+    # @see EditInPlace.configure
+    def configure
+      yield config if block_given?
+    end
+
+    # @overload field(type, options, *args)
+    #   Renders a single field of the given type with the given field option and arguments
+    #   to be passed to the field type renderer.
+    #   @param type [FieldType, Symbol] the type of field to render, either an actual instance of
+    #     {FieldType}, or the symbol name of a registered field type.
+    #   @param options [FieldOptions, Hash] the field options to be used when rendering the
+    #     field. These options are defined in {FieldOptions}. Either an actual instance of
+    #     {FieldOptions} or a hash are acceptable.
+    #   @param args [Array] the arguments to be passed to the field renderer.
+    #   @return [String] the rendered field, as HTML.
+    # @overload field(type, *args)
+    #   Renders a single field of the given type with the given arguments to be passed to the
+    #   field type renderer. The default field options (as defined in {FieldOptions}) will be
+    #   used.
+    #   @param type [FieldType, Symbol] the type of field to render, either an actual instance of
+    #     {FieldType}, or the symbol name of a registered field type.
+    #   @param args [Array] the arguments to be passed to the field renderer.
+    #   @return [String] the rendered field, as HTML.
+    def field(type, *args)
+      inject_field_options!(args)
+      args[0] = config.field_options.merge(args[0])
+
+      definition = Middlegem::ArrayDefinition.new(config.defined_middlewares)
+      stack = Middlegem::Stack.new(definition, middlewares: args[0].middlewares)
+      args = stack.call(*args)
+
+      type = evaluate_field_type(type)
+      type.render(*args)
+    end
+
+    # Yields a new, scoped {Builder} with the given field options. This method is helpful when
+    # many fields require the same options. One use, for example, is to easily give field types
+    # access to the current view context, like so:
+    #
+    #   <!-- some_view.html.erb -->
+    #
+    #   <%= @builder.scoped view: self do |b|
+    #     <%= b.field(:example_type, 'random scoped field') %>
+    #     <!-- ... -->
+    #   <% end %>
+    #
+    # Now all fields generated using +b+ will have access to +self+ as the view context in
+    # {FieldOptions#view}.
+    # @yieldparam scoped_builder [Builder] the new, scoped {Builder} instance.
+    # @yieldreturn [string] the output generated with the scoped builder.
+    # @param field_options [FieldOptions, Hash] the field options that the scoped builder should
+    #   have. Note that these options will be merged (using {FieldOptions#merge!}) with the
+    #   current ones. Either an actual {FieldOptions} instance or a hash of options are
+    #   acceptable.
+    # @return [string] the output of the block.
+    def scoped(field_options = {})
+      field_options = FieldOptions.new(field_options) unless field_options.is_a? FieldOptions
+
+      scoped_builder = dup
+      scoped_builder.config.field_options.merge!(field_options)
+
+      yield scoped_builder
+    end
+
+    private
+
+    # Ensures that the first argument in the given list of arguments is a valid, appropriate
+    # {FieldOptions} instance for the list of arguments. In particular:
+    # - When the first argument is already an instance of {FieldOptions}, the argument list
+    #   is not touched.
+    # - When the first argument is a hash, then it is converted to a
+    #   {FieldOptions} instance.
+    # - Otherwise, the default {FieldOptions} instance is prepended to the argument list.
+    # @param args [Array] the raw arguments into which to inject the field options.
+    # @return [void]
+    def inject_field_options!(args)
+      options = args.first
+
+      return if options.is_a? FieldOptions
+
+      if options.is_a? Hash
+        args[0] = FieldOptions.new(options)
+      else
+        args.unshift(FieldOptions.new)
+      end
+    end
+
+    # Gets an appropriate {FieldType} instance for the given raw field type argument. In
+    # particular:
+    # - When the input is already a FieldType instance, that instance is simply returned.
+    # - When the input is a symbol, attempts to find a registered field type associated with it.
+    # - Otherwise, raises an error.
+    # @return [FieldType] an appropriate {FieldType} instance for the given input.
+    def evaluate_field_type(type)
+      case type
+      when FieldType
+        type
+      when Symbol
+        result = config.field_types.find(type)
+        raise UnregisteredFieldTypeError, type if result.nil?
+
+        result
+      else
+        raise InvalidFieldTypeError, type
+      end
+    end
+  end
+end

data/lib/edit_in_place/configuration.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module EditInPlace
+  # {Configuration} is a class that is capable of storing configuration for an edit_in_place
+  # {Builder}. Essentially all the options provided by edit_in_place reside in this class for
+  # easy reuse. This class is currently used in two locations---the global configuration in
+  # {EditInPlace.config} and the builder-specific configuration in {Builder#config}.
+  #
+  # @author Jacob Lockard
+  # @since 0.1.0
+  class Configuration
+    # The default mode in which fields should be rendered if left unpspecified in the
+    # configuration.
+    DEFAULT_MODE = :viewing
+
+    # The {FieldTypeRegistrar} used to store the list of registered field types.
+    # @return [FieldTypeRegistrar] the {FieldTypeRegistrar} that stores the list of registered
+    #   field types.
+    attr_accessor :field_types
+
+    # The default {FieldOptions} instance to use when a builder renders a field. Note that this
+    # instance will be merged with the one passed directly to {Builder#field}.
+    # @return [FieldOptions] the default field options to use when rendering a field.
+    attr_accessor :field_options
+
+    # An array containing all the middleware classes permitted, in the order they should be run.
+    # @return [Array] the array of defined middlewares.
+    attr_accessor :defined_middlewares
+
+    # Creates a new, default instance of {Configuration}.
+    def initialize
+      @field_types = FieldTypeRegistrar.new
+      @field_options = FieldOptions.new(mode: DEFAULT_MODE)
+      @defined_middlewares = []
+    end
+
+    # Creates a deep copy of this {Configuration} that can be safely modified.
+    # @return [Configuration] a deep copy of this configuration.
+    def dup
+      c = Configuration.new
+      c.field_types = field_types.dup
+      c.field_options = field_options.dup
+      # Note that this is purposely NOT a deep copy---it doesn't make sense to duplicate classes.
+      c.defined_middlewares = defined_middlewares.dup
+      c
+    end
+  end
+end

data/lib/edit_in_place/duplicate_registration_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module EditInPlace
+  # An error that occurs when a name that has already been registered is registered.
+  class DuplicateRegistrationError < Error; end
+end

data/lib/edit_in_place/extended_builder.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module EditInPlace
+  # A base class that allows one to easily and safely extend the {Builder} class with additional
+  # functionality. Every {ExtendedBuilder} contains a base builder to which it delegates all
+  # missing method calls. In this way, builder instances can be extended multiple times, like so:
+  #   base = Builder.new({...})
+  #   base.respond_to? :field # => true
+  #
+  #   hello_builder = HelloBuilder.new(base_builder, {...}) # a sub-class of ExtendedBuilder
+  #   hello_builder.respond_to? :hello # => true
+  #   hello_builder.respond_to? :field # => true
+  #
+  #   world_builder = WorldBuilder.new(hello_builder, {...}) # a sub-class of ExtendedBuilder
+  #   world_builder.respond_to? :world # => true
+  #   world_builder.respond_to? :hello # => true
+  #   world_builder.respond_to? :field # => true
+  #
+  # A word of caution is in order, however! An {ExtendedBuilder} should *never*
+  # override a method on the base builder. While this may seem like a convenient way to add new
+  # methods to {Builder}, it can cause problems, since other methods further along in the chain
+  # will not call the overriden one. {ExtendedBuilder} is intended only for adding new methods,
+  # not mdifying existing ones.
+  #
+  # @author Jacob Lockard
+  # @since 0.1.0
+  class ExtendedBuilder
+    # @return [Object] the base builder instance which this {ExtendedBuilder} extends. It should
+    #   quack like a {Builder}.
+    attr_reader :base
+
+    delegate_missing_to :base
+
+    # Creates a new {ExtendedBuilder} with the given base builder.
+    # @param base [Object] the base builder to extend. It should quack like a {Builder}.
+    def initialize(base)
+      @base = base
+    end
+  end
+end

data/lib/edit_in_place/field_options.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module EditInPlace
+  # {FieldOptions} is a class that stores the options and context required to render a field.
+  #
+  # @author Jacob Lockard
+  # @since 0.1.0
+  class FieldOptions
+    # @overload mode
+    #   Gets the "mode" with which the field should be rendered. For example, a text field may
+    #   render an +<input type="text" ...>+ element when in an "editing" mode, but render simple
+    #   text in a "viewing" mode.
+    #   @return [Symbol] the mode in which the field should be rendered.
+    # @overload mode=
+    #   Sets the new mode.
+    #   @param mode [String, Symbol, nil] the new mode.
+    #   @note All strings will be converted to symbols.
+    #   @return [void]
+    attr_reader :mode
+
+    # The view context to be used when rendering the field. This view context can be derived in
+    # a number of ways, most commonly by creating a new instance of +ActionView::Base+.
+    # @return the view context to be used when rendering the field.
+    attr_accessor :view
+
+    # An array of middleware instances that should be applied to the field's input.
+    # @return the array of middlewares.
+    attr_accessor :middlewares
+
+    # @overload initialize(options)
+    #   Creates a new instance of {FieldOptions} with the given options.
+    #   @param options [Hash, #[]] a hash containing the given field options.
+    #   @option options [Symbol] :mode the {#mode} in which fields should be rendered.
+    #   @option options :view the {#view} context to use when rendering the field.
+    # @overload initialize
+    #   Creates a new instance of {FieldOptions} with the default options.
+    def initialize(options = {})
+      self.mode = options[:mode]
+      self.view = options[:view]
+      self.middlewares = options[:middlewares] || []
+    end
+
+    # Documentation for this method resides in the attribute declaration.
+    def mode=(mode)
+      @mode = mode.nil? ? nil : mode.to_sym
+    end
+
+    # Creates a deep copy of this {FieldOptions} instance that can be safely modified.
+    # @return [FieldOptions] a deep copy of this {FieldOptions} instance.
+    def dup
+      f = FieldOptions.new
+      f.mode = mode
+      f.view = view
+      f.middlewares = middlewares.deep_dup
+      f
+    end
+
+    # Merges the given {FieldOptions} instance into this one. Modes and view contexts from the
+    # other instance will overwrite those in this instance if present. The other instance is
+    # duplicated before being merged, so it can be safely modified after the fact. All
+    # middleware arrays will be merged.
+    # @param other [FieldOptions] the other field options to merge into this one.
+    # @return [void]
+    def merge!(other)
+      other = other.dup
+
+      self.mode = other.mode unless other.mode.nil?
+      self.view = other.view unless other.view.nil?
+      self.middlewares += other.middlewares
+    end
+
+    # Creates a _new_ {FieldOptions} instance that is the result of merging the given
+    # {FieldOptions} instance into this one. Neither instance is modified, and both are
+    # duplicated, meaning that they can be safely modified after the fact. Merging occurs exactly
+    # as with {#merge!}.
+    # @param other [FieldOptions] the other field options to merge into this one.
+    # @return [FieldOptions] the result of merging the two instances.
+    def merge(other)
+      new = dup
+      new.merge!(other)
+      new
+    end
+  end
+end

data/lib/edit_in_place/field_type.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module EditInPlace
+  # {FieldType} is a class that represents a single type of field. A field is a single,
+  # self-contained component that displays data in various "modes", typically either "viewing" or
+  # "editing". Field types provide the templates for similar fields.
+  #
+  # @abstract
+  # @author Jacob Lockard
+  # @since 0.1.0
+  class FieldType
+    # Render the field, given a {FieldOptions} instance and an array of arguments passed by
+    # the caller.
+    #
+    # While subclasses may override this method as appropriate, the default
+    # implementation simply does two things:
+    # 1. uses {#validate_mode!} to ensure that the mode is supported, and
+    # 2. calls a +render_*+ method.
+    # For example, if the mode were +:admin_editing+, then a +render_admin_editing+ method would
+    # be called. Naturally, the +render_*+ methods need to be defined by the subclass.
+    # @param options [FieldOptions] options passed by the {Builder} instance that should
+    #   be used to render the field.
+    # @param args [Array<Object>] the arguments passed by the field creator.
+    # @return [String] the rendered HTML.
+    def render(options, *args)
+      validate_mode!(options.mode)
+      send("render_#{options.mode}", options, *args)
+    end
+
+    # Gets the modes that are supported by this field type, +:viewing+ and +:editing+ by default.
+    # @return [Array<Symbol>] the modes supported by this field type.
+    # @note Subclasses should override this method as appropriate.
+    def supported_modes
+      %i[viewing editing]
+    end
+
+    # @!method dup
+    #   Should create a deep copy of this {FieldType} that can be safely modified.
+    #   @return [FieldType] a deep copy of this field type.
+    #   @note This method should be overriden as necessary by subclasses to duplicate any added
+    #     data.
+
+    protected
+
+    # Ensures that the given mode is supported by this field type.
+    # @param mode [Symbol] the mode to validate.
+    # @return [void]
+    def validate_mode!(mode)
+      raise UnsupportedModeError, mode unless supported_modes.include? mode
+    end
+  end
+end

data/lib/edit_in_place/field_type_registrar.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module EditInPlace
+  # {FieldTypeRegistrar} is a subcalss of {Registrar} that only allows {FieldType}
+  # instances to be registered.
+  #
+  # @author Jacob Lockard
+  # @since 0.1.0
+  class FieldTypeRegistrar < Registrar
+    protected
+
+    # Adds to the default `validate_registration!` implementation by ensuring that only
+    # {FieldType} instances can be registered.
+    # @param name [Symbol] the name to validate.
+    # @param field_type [FieldType] the field type to validate.
+    # @return [void]
+    def validate_registration!(name, field_type)
+      super
+      raise InvalidFieldTypeError, field_type unless field_type.is_a? FieldType
+    end
+  end
+end

data/lib/edit_in_place/invalid_field_type_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module EditInPlace
+  # An error that occurs when an object that cannot be parsed into a {FieldType} is used as one.
+  class InvalidFieldTypeError < Error
+    # Creates a new instance of {InvalidFieldTypeError} with the given field type that
+    # caused the error.
+    # @param field_type [object] the field type that caused the error; used in the error message.
+    def initialize(field_type)
+      super("'#{field_type.inspect}' is not a valid field type!")
+    end
+  end
+end

data/lib/edit_in_place/invalid_registration_name_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module EditInPlace
+  # An error that occurs when an object is registered with an invalid name. This error usually
+  # occurs when the name is not a symbol.
+  class InvalidRegistrationNameError < Error; end
+end

data/lib/edit_in_place/railtie.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module EditInPlace
+  class Railtie < ::Rails::Railtie
+  end
+end

data/lib/edit_in_place/registrar.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module EditInPlace
+  # {Registrar} is a class that is capable of storing a list of objects registered with symbol
+  # names. Note that it makes no attempt to validate the objects registered. If such validation
+  # is required feel free to subclass {Registrar} and override the {validate_registration!}
+  # method.
+  #
+  # @author Jacob Lockard
+  # @since 0.1.0
+  class Registrar
+    # Creates a new instance of {Registrar}.
+    def initialize
+      @registrations = {}
+    end
+
+    # Creates a deep copy of this {Registrar} that can be safely modified.
+    # @return [Registrar] a deep copy of this registrar.
+    def dup
+      r = Registrar.new
+      r.register_all(all)
+      r
+    end
+
+    # Registers the given object with the given symbol name.
+    # @param name [Symbol] the symbol name with which to associate the object.
+    # @param object the object to register.
+    # @return [void]
+    # @see #register_all
+    def register(name, object)
+      validate_registration!(name, object)
+      registrations[name] = object
+    end
+
+    # Registers all the symbol names and objects in the given hash. All elements of the hash are
+    # passed through {#register}.
+    # @param objects [Hash<(Symbol, Object)>] the hash of names and objects to register.
+    # @return [void]
+    # @see #register
+    def register_all(objects)
+      # The identical loops are necessary to prevent anyything from being registered if even one
+      # fails the validation.
+
+      # rubocop:disable Style/CombinableLoops
+      objects.each { |n, t| validate_registration!(n, t) }
+      objects.each { |n, t| register(n, t) }
+      # rubocop:enable Style/CombinableLoops
+    end
+
+    # Attempts to find an object associated with the given symbol name.
+    # @param name [Symbol] the symbol name to search for.
+    # @return [Object] if found.
+    # @return [nil] if no object was associated with the given name.
+    def find(name)
+      registrations[name]
+    end
+
+    # Gets a hash of all registrations. Note that this hash is a deep clone of the actual,
+    # internal one and can be safely modified.
+    # @return [Hash<(Symbol, Object)>] the hash of registered names and objects.
+    def all
+      registrations.deep_dup
+    end
+
+    protected
+
+    # @return [Hash<(Symbol, Object)>] A hash of registrations.
+    attr_reader :registrations
+
+    # Should ensure that the given registration is valid. By default a registration is valid if
+    # its name is not already taken and is a symbol. Subclasses may override this method to add
+    # validation rules. Errors should be raised for any invalid registrations.
+    # @param name [Symbol] the name to validate.
+    # @param _object [Object] the object to validate.
+    # @return [void]
+    def validate_registration!(name, _object)
+      if registrations.key?(name)
+        raise DuplicateRegistrationError, <<~ERR
+          The name '#{name}' has already been registered!
+        ERR
+      end
+
+      unless name.is_a?(Symbol)
+        raise InvalidRegistrationNameError, <<~ERR
+          The name '#{name}' is not a valid symbol registration name!
+        ERR
+      end
+    end
+  end
+end

data/lib/edit_in_place/unregistered_field_type_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module EditInPlace
+  # An error that occurs when no registered field types exist for the field type name given.
+  class UnregisteredFieldTypeError < Error
+    # Creates a new instance of {UnregisteredFieldTypeError} with the given field type name that
+    # caused the error.
+    # @param name [Symbol] the field type that caused the error; used in the error message.
+    def initialize(name)
+      super("No field types are registered with the name '#{name}'")
+    end
+  end
+end

data/lib/edit_in_place/unsupported_mode_error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module EditInPlace
+  # An error that occurs when a field is rendered with a mode that is does not support.
+  class UnsupportedModeError < Error
+    # Creates a new instance of {UnsupportedModeError} with the given mode that
+    # caused the error.
+    # @param mode [Symbol] the mode that caused the error.
+    def initialize(mode)
+      super("The mode '#{mode}' is not supported by this field type!")
+    end
+  end
+end

data/lib/edit_in_place/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EditInPlace
+  VERSION = '0.1.0'
+end

data/lib/tasks/edit_in_place_tasks.rake

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+# desc "Explaining what the task does"
+# task :edit_in_place do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,170 @@
+--- !ruby/object:Gem::Specification
+name: edit_in_place
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jacob
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-07-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '11.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.18'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '0.17'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: '0.17'
+- !ruby/object:Gem::Dependency
+  name: middlegem
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.1.3
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.1.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.1.3
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.1.3.2
+description: 'edit_in_place is a Ruby on Rails plugin that allows the creation of
+  user interfaces that allow the user to edit content in an intuitive, natural, "in
+  place" way.
+
+  '
+email:
+- jacoblockard99@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/edit_in_place.rb
+- lib/edit_in_place/builder.rb
+- lib/edit_in_place/configuration.rb
+- lib/edit_in_place/duplicate_registration_error.rb
+- lib/edit_in_place/extended_builder.rb
+- lib/edit_in_place/field_options.rb
+- lib/edit_in_place/field_type.rb
+- lib/edit_in_place/field_type_registrar.rb
+- lib/edit_in_place/invalid_field_type_error.rb
+- lib/edit_in_place/invalid_registration_name_error.rb
+- lib/edit_in_place/railtie.rb
+- lib/edit_in_place/registrar.rb
+- lib/edit_in_place/unregistered_field_type_error.rb
+- lib/edit_in_place/unsupported_mode_error.rb
+- lib/edit_in_place/version.rb
+- lib/tasks/edit_in_place_tasks.rake
+homepage: https://github.com/jacoblockard99/edit_in_place
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.5.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.3
+signing_key:
+specification_version: 4
+summary: A Rails plugin that facilitates the creation of intuitive editable content.
+test_files: []