tolaria 1.0.0

data/lib/tolaria/default_config.rb

@@ -0,0 +1,74 @@
+Tolaria.configure do |config|
+
+  # The name of the company or group using this admin interface.
+  # Used in system navigation and HTML page titles.
+  config.company_name = "Company Name"
+
+  # Redirect the users to this route by default when logging in.
+  config.default_redirect = :admin_administrators
+
+  # Tolaria sends authentication emails. Set the value of the From header here.
+  config.from_address = "Rails <tolaria@example.org>"
+
+  # You can assign models to a category group them on the nav menu.
+  # Add/modify categories by changing the array below.
+  # Categories first in the array will be first on the menu.
+  config.menu_categories = ["Settings"]
+
+  # The cost factor for bcrypt.
+  # It is VERY DANGEROUS to set this below 10 for production.
+  # Use 1 in test mode to speed up your test suite.
+  config.bcrypt_cost = Rails.env.test?? 1 : 13
+
+  # The length of time that emailed passcodes should be valid.
+  # It is STRONGLY RECOMMENDED that you keep this under 30 minutes.
+  config.passcode_lifespan = 10.minutes
+
+  # The number of times an administrator can flunk their passcode
+  # challenge or request a token before Tolaria disables their account.
+  config.lockout_threshold = 10
+
+  # The length of time that an administrator’s account is disabled
+  # after they trip the lockout threshold.
+  config.lockout_duration = 1.hour
+
+  # An array of hashes used to construct HelpLinks
+  config.help_links = []
+
+  # Tolaria does not come bundled with a Markdown processing strategy.
+  # You must provide a string that names a Ruby constant that can process Markdown.
+  # The constant must respond to render(document), returning a string of HTML.
+  # For example: if you provide "MyMarkDownRenderer", Tolaria will
+  # call MyMarkdownRenderer.render(document).
+  config.markdown_renderer = nil
+
+  # Tolaria attempts to convert models to a pretty “display”
+  # string for presenting in forms and listings.
+  # The methods below are tried in order on models until one responds.
+  # Must be an array of symbols.
+  config.display_name_methods = %i[
+    admin_name
+    display_name
+    title
+    name
+    label
+    username
+    login
+    email
+    to_s
+    id
+  ]
+
+  # The number of items on each page when paginating models.
+  config.page_size = 15
+
+  # Default permitted_params for all forms.
+  # End-developers probably shouldn’t change this.
+  config.permitted_params = %i[
+    _method
+    authenticity_token
+    id
+    utf8
+  ]
+
+end

data/lib/tolaria/engine.rb

@@ -0,0 +1,23 @@
+module Tolaria
+  class Engine < ::Rails::Engine
+
+    # Add Tolaria’s assets to config.assets.precompile
+    initializer "tolaria.assets.precompile", group: :all do |app|
+      app.config.assets.precompile += %w[
+        admin/admin.css
+        admin/admin.js
+        admin/lib/no.js
+      ]
+    end
+
+    # Reference ApplicationController and set Tolaria.safe_management
+    # to indicate that the application has finished booting
+    initializer "tolaria.safe_management", group: :all do |app|
+      app.config.after_initialize do
+        "ApplicationController".safe_constantize
+        Tolaria.safe_management = true
+      end
+    end
+
+  end
+end

data/lib/tolaria/form_buildable.rb

@@ -0,0 +1,203 @@
+module Tolaria
+  module FormBuildable
+
+    # Returns a `p.hint` used to explain a nearby form field containing
+    # the given +hint_text+.
+    def hint(hint_text)
+      content_tag(:p, content_tag(:span, hint_text.chomp), class:"hint")
+    end
+
+    # Creates a `<select>` list that can be filtered by typing word fragments.
+    # Uses the jQuery Chosen plugin internally to power the user interface.
+    # Parameters are the same as Rails’s `collection_select`.
+    #
+    # #### Special Options
+    #
+    # - `:multiple` - if set to `true`, the select allows more than one choice.
+    #   The default is `false`.
+    def searchable_select(method, collection, value_method, text_method, options = {})
+      render(partial:"admin/shared/forms/searchable_select", locals: {
+        f: self,
+        method: method,
+        collection: collection,
+        value_method: value_method,
+        text_method: text_method,
+        options: options,
+        html_options: options,
+      })
+    end
+
+    # Creates a `searchable_select` that also shows a dynamic image preview of the selected record.
+    # Useful for previewing images or avatars chosen by name.
+    # +preview_url_method+ should be a method name to call on the associated model instance
+    # that returns a fully-qualified URL to the image preview.
+    def image_association_select(method, collection, value_method, text_method, preview_url_method, options = {})
+      render(partial:"admin/shared/forms/image_association_select", locals: {
+        f: self,
+        method: method,
+        collection: collection,
+        value_method: value_method,
+        text_method: text_method,
+        preview_url_method: preview_url_method,
+        options: options,
+        html_options: options,
+      })
+    end
+
+    # Renders a Markdown composer element for editing +method+,
+    # with fullscreen previewing and some text assistance tools.
+    # Requires that you set `Tolaria.config.markdown_renderer`.
+    # Options are forwarded to `text_area`.
+    def markdown_composer(method, options = {})
+      render(partial:"admin/shared/forms/markdown_composer", locals: {
+        f: self,
+        method: method,
+        options: options,
+      })
+    end
+
+    # Returns a file upload field with a more pleasant interface than browser
+    # file inputs. Changes messaging if the +method+ already exists.
+    # Options are forwarded to the hidden `file_field`.
+    def attachment_field(method, options = {})
+      render(partial:"admin/shared/forms/attachment_field", locals: {
+        f: self,
+        method: method,
+        options: options,
+      })
+    end
+
+    # Returns an image upload field with a more pleasant interface than browser
+    # file inputs. Changes messaging if the +method+ already exists.
+    #
+    # #### Special Options
+    #
+    # - `:preview_url` If the file already exists, provide a URL to a 42×42px
+    #   version of the image, and it will be displayed to the user in a preview
+    #   box to better communicate which file they are replacing.
+    #
+    # Other options are forwarded to the hidden `file_field`.
+    def image_field(method, options = {})
+      render(partial:"admin/shared/forms/image_field", locals: {
+        f: self,
+        method: method,
+        options: options,
+        preview_url: options[:preview_url]
+      })
+    end
+
+    # Returns a text field that allows the user to input a date and time.
+    # Automatically validates itself and recovers to a template if blanked out.
+    # This field uses moment.js to parse the date and set the values on a
+    # set of hidden Rails `datetime_select` fields.
+    # Options are forwarded to the hidden `datetime_select` group.
+    def timestamp_field(method, options = {})
+      render(partial:"admin/shared/forms/timestamp_field", locals: {
+        f: self,
+        method: method,
+        options: options,
+      })
+    end
+
+    # Returns a text field that parameterizes its input as users type
+    # and renders it into the given preview template. Useful for
+    # demonstrating the value of a URL or other sluggified text.
+    #
+    # #### Special Options
+    #
+    # - `:pattern` - Should be a string that includes an asterisk (`*`)
+    #   character. As the user types, the asterisk will be replaced with
+    #   a parameterized version of the text in the text box and shown
+    #   in a preview area below the field.
+    #   The default is `"/blog-example/*"`.
+    #
+    # Other options are forwarded to `text_field`.
+    def slug_field(method, options = {})
+      pattern = options.delete(:pattern)
+      preview_value = self.object.send(method).try(:parameterize).presence || "*"
+      render(partial:"admin/shared/forms/slug_field", locals: {
+        f: self,
+        method: method,
+        options: options,
+        preview_value: preview_value,
+        pattern: (pattern || "/blog-example/*")
+      })
+    end
+
+    # Returns a text field that expects to be given a 3 or 6-digit
+    # hexadecimal color value. A preview block near the field
+    # demonstrates the provided color to the user.
+    # Options are forwarded to `text_field`.
+    def swatch_field(method, options = {})
+      render(partial:"admin/shared/forms/swatch_field", locals: {
+        f: self,
+        method: method,
+        options: options,
+      })
+    end
+
+    # Opens an ERB block for UI to manage a `has_many` + `accepts_nested_attributes_for`
+    # association in the current form. The block will look similar to this:
+    #
+    #    <%= f.has_many :footnotes do |ff| %>
+    #      <%= ff.has_many_header allow_destroy:true %>
+    #      <% # Your nested model fields for footnote here %>
+    #    <% end %>
+    #
+    # You must use `f.has_many_header` inside the block to create headers.
+    #
+    # If you need to pass an ordered collection or otherwise not allow automatically
+    # determining the association objects from the +association+ symbol you can
+    # pass the collection manually as +association_objects+.
+    #
+    # If +allow_create+ is `false` then the button to append a new model
+    # instance will be disabled. The default is `true`.
+    def has_many(association, association_objects = nil, allow_create:true, &block)
+
+      new_object = self.object.send(association).klass.new
+
+      view_template = self.fields_for(association, new_object, child_index:new_object.object_id) do |builder|
+        yield(builder)
+      end
+
+      existing_fields = self.fields_for(association, association_objects) do |builder|
+        yield(builder)
+      end
+
+      render(partial:"admin/shared/forms/has_many", locals: {
+        association: association,
+        button_label: association.to_s.humanize.singularize.titleize,
+        new_object: new_object,
+        existing_fields: existing_fields,
+        allow_create: allow_create,
+        f: self,
+        data: {
+          template: view_template.tr("\n"," "),
+          id: new_object.object_id,
+        }
+      })
+
+    end
+
+    # Creates a header suitable for use inside `has_many` for separating
+    # form elements. If +allow_destroy+ is `true`, controls will be exposed that allow
+    # removing nested instances of the model. The default is `false` to match Rails’.
+    def has_many_header(allow_destroy:false)
+      render(partial:"admin/shared/forms/has_many_header", locals: {
+        allow_destroy: allow_destroy,
+        f: self,
+      })
+    end
+
+  end
+end
+
+class Admin::FormBuilder < ActionView::Helpers::FormBuilder
+  include Tolaria::FormBuildable
+  delegate :content_tag, :tag, :render, to: :@template
+end
+
+class Ransack::Helpers::FormBuilder
+  include Tolaria::FormBuildable
+  delegate :content_tag, :tag, :render, to: :@template
+end

data/lib/tolaria/help_links.rb

@@ -0,0 +1,78 @@
+module Tolaria
+
+  @help_links = []
+
+  def self.initialize_help_links!
+    @help_links = []
+    self.config.help_links.each do |hashy|
+      @help_links << Tolaria::HelpLink.new(**hashy)
+    end
+  end
+
+  def self.help_links
+    @help_links ||= []
+  end
+
+  class HelpLink
+
+    # The title of the link
+    attr_reader :title
+    # Part part of the link at `/admin/help/:slug` when rendering a Markdown file
+    attr_reader :slug
+    # The file path to the Markdown file
+    attr_reader :markdown_file
+    # The path to link to when not rendering a Markdown file
+    attr_reader :link_to
+
+    # Create a new HelpLink with the passed settings.
+    # You must provide +title+, the title of the link.
+    # To configure automatic rendering of a Markdown file, provide
+    # a string +slug+ and the path to a +markdown_file+.
+    # A route to view the file will be constructed for you at `/admin/help/:slug`.
+    # To link to an arbirary path or URI, provide it as +link_to+.
+    def initialize(title:, slug:nil, markdown_file:nil, link_to:nil)
+      @title = title.to_s.freeze
+      @slug = slug.to_s.freeze
+      @markdown_file = markdown_file.to_s.freeze
+      @link_to = link_to.to_s.freeze
+      validate!
+    end
+
+    # True if this HelpLink is a link to an arbirary path
+    def link_type?
+      link_to.present?
+    end
+
+    # True if this HelpLink is a Markdown file
+    def markdown_type?
+      markdown_file.present?
+    end
+
+    # Quack like an ActiveRecord::Base model
+    def to_param
+      slug
+    end
+
+    # Raises RuntimeError if this HelpLink is incorrectly configured
+    def validate!
+
+      if title.blank?
+        raise RuntimeError, "HelpLinks must provide a string title"
+      end
+
+      file_configured = (slug.present? && markdown_file.present?)
+      link_configured = link_to.present?
+
+      unless file_configured || link_configured
+        raise RuntimeError, "Incomplete HelpLink config. You must provide link_to, or both slug and markdown_file."
+      end
+
+      if file_configured && link_configured
+        raise RuntimeError, "Ambiguous HelpLink config. You must provide link_to, or both slug and markdown_file, but not all three."
+      end
+
+    end
+
+  end
+
+end

data/lib/tolaria/introspection.rb

@@ -0,0 +1,13 @@
+module Tolaria
+
+  # Using this method, you can attempt to get a pretty “display”
+  # string for presenting the passed +resource+ as a label.
+  def self.display_name(resource)
+    Tolaria.config.display_name_methods.each do |method_name|
+      if resource.respond_to?(method_name)
+        return resource.send(method_name).to_s.truncate(40, omission:"…")
+      end
+    end
+  end
+
+end

data/lib/tolaria/manage.rb

@@ -0,0 +1,57 @@
+module Tolaria
+
+  @safe_mangagment = false
+  @managed_classes = []
+
+  # True if the application has actually booted
+  # and Tolaria is safe to start referencing models
+  def self.safe_management
+    @safe_mangagment
+  end
+
+  # Set the value of Tolaria.safe_management. +bool+ should be truthy.
+  # Don't call this method directly.
+  def self.safe_management=(bool)
+    @safe_mangagment = !!bool
+  end
+
+  # Tolaria keeps a list of all managed classes and the controllers
+  # for those classes internally so that other parts of the system
+  # can iterate over them. Return the list.
+  def self.managed_classes
+    @managed_classes
+  end
+
+  # Internal factory for adding managed classes. Developers should
+  # use ActiveRecord::Base#manage_with_tolaria.
+  def self.manage(klass, options = {})
+
+    # If we already have a class of this name, discard it
+    discard_managed_class(klass)
+
+    # Wrap the Rails model inside a Tolaria::ManagedClass
+    managed_klass = Tolaria::ManagedClass.create(klass, options)
+
+    # Add class to the internal tracker
+    @managed_classes.push(managed_klass)
+
+    # Check if there is already a correctly named controller because
+    # this means the end-developer made one and we don't want to unseat it.
+    # Otherwise create a controller for the model to use in the admin namespace.
+    unless "Admin::#{managed_klass.controller_name}".safe_constantize
+      managed_controller = Class.new(Tolaria::ResourceController)
+      ::Admin.const_set(managed_klass.controller_name, managed_controller)
+    end
+
+    return managed_klass
+
+  end
+
+  # Discard a managed class instance for the given ActiveRecord::Base
+  def self.discard_managed_class(klass)
+    @managed_classes.delete_if do |managed_class|
+      klass.to_s == managed_class.klass.to_s
+    end
+  end
+
+end