rooftop-rails-extras 0.0.3

data/README.md

@@ -0,0 +1,162 @@
+# Rooftop::Rails::Extras
+A selection of things we're finding handy at [Error](http://error.agency) so you might, too.
+
+## `Rooftop::Rails::Extras::ResourceSearch` - Free-text Searchable resources
+Rooftop CMS search is a work in progress, and only supports basic WordPress LIKE queries at the moment. You can do a little better than that, at the expense of getting a collection of all resources, if you do a regex match in Rails.
+ 
+```
+class SomePostType
+    include Rooftop::Post
+    include Rooftop::Rails::Extras::ResourceSearch #searches title and content by default
+    
+    # add extra fields to search, by creating a lambda which returns text. Markup and punctuation is stripped after calling it.
+    add_search_field ->(record) {
+        record.fields.some_custom_field
+    }
+    
+    # Or a more complicated example, where a custom field is returning an object of some sort
+    add_search_field ->(record) {
+        record.fields.some_complex_object[:some][:deep][:data]
+    }
+    
+    # or even a collection, from an ACF repeater
+    add_search_field ->(record) {
+        content = record.fields.some_repeater.collect do |object|
+            object.some.deep.thing
+        end
+        content.join(" ") #return the collection, joined with a space
+    }
+    
+end
+```
+
+## Contact form handling
+Almost every website we build needs a simple mail handler. Extending the [mail_form gem](https://github.com/plataformatec/mail_form), we've added a way to handle these with minimal fuss. Some assumptions are made in the name of expedience; if you need more than this, you probably need to use `mail_form` directly.
+
+### Create a contact form model, inheriting from the Rooftop extras one
+First define a model which inherits from `Rooftop::Rails::Extras::ContactForm`. You need to do some setup in here, including:
+
+* Defining the fields (and types) you need to handle
+* The to / from addresses, and any extra headers you want to define in the email
+
+```
+class ContactForm < Rooftop::Rails::Extras::ContactForm #you can call your class anything
+    #the values of these hashes are Rails form helper method names
+    self.fields = {
+        name: :text_field, 
+        email: :text_field,
+        message: :text_area
+    }
+    self.to = "the email you want to send the contact messages to"
+    self.from = "the email from which you want to send the messages"
+end
+```
+
+### Create a controller and add the mixin
+Write a simple controller and add the `Rooftop::Rails::Extras::ContactFormHandler` mixin.
+
+```
+class ContactFormsController < ApplicationController # you can call your controller anything to suit
+  include Rooftop::Rails::Extras::ContactFormHandler
+  # Declare the class you've just defined, above. If you called it something else, change it here.
+  self.contact_form = ::ContactForm
+end
+```
+
+### Create a route
+If you called your controller something else, you need to tweak the route accordingly. Of course, this is all just normal Rails routes so you can do what you need to, as long as a POST request hits your controller.
+
+```
+resources :contact_forms, only: :create
+```
+
+### Define a 'thankyou' page in Rooftop CMS
+When the form is submitted, the controller redirects the user to a thankyou page, which is any page you want. You need to derive the ID of this page somehow, to get it into a hidden field in the form. Generally, we create a field in Rooftop for this, and decorate the Page model with a'thankyou_page_id' method which returns the ID. 
+
+### Create your form
+How you build the form is up to you, but here's a quick way to use the fields you defined above.
+
+```
+<%= form_for ContactForm.new, method: :post, class: 'contact' do |f| %>
+<!-- The form will create a flash with the errors from the form, if any -->
+    <% if flash[:notice].present?  %>
+        <p class="form-errors">
+            Your message couldn't be sent: <%= flash[:notice] %>
+        </p>
+    <% end %>
+    <!-- f.object is the ContactForm instance above, so we know it responds to `fields` -->
+    <% f.object.fields.each do |field, type| %>
+    <!-- iterate over each field, setting the value if passed in, and adding an error class if there's an error on the field -->
+        <p>
+            <%= f.label field %>
+            <%= f.send(
+                    type,
+                    field,
+                    class: (params[:errors].present? && params[:errors].include?(field.to_s)) ? "has-errors" : "",
+                    value: params[field],
+                    required: true
+                )%>
+        </p>
+    <% end %>
+    <!-- these hidden tags tell the controller how to redirect the user. If there's an error, we'll redirect back to this page, with get params for the errors and each completed field. If there isn't, the user is redirected to the thankyou page -->
+    <%= hidden_field_tag :from_page, page.id %>
+    <%= hidden_field_tag :to_page, page.thankyou_page_id %>
+
+    <p><input type="submit" id="submit" value="Send" /></p>
+<% end %>
+```
+
+### Handling Errors
+`Rooftop::Rails::Extras::ContactForm` assumes every field you enter is required. If there are errors on the model, the controller will return the user to the original page (as a redirect) but add some querystring params:
+
+* `errors[]` - an array of each fieldname with errors (in our example above, we check for this and add a classname on the offending inputs
+* params for each entered field, so you can set the field values to save data re-entry
+
+## Navigation View Helpers
+For nested post types (pages, products etc.) you might well want to create subnavigation, showing the path to this page, its siblings and parent pages. We use this often enough at [Error Agency](http://error.agency) to have a helper do the iteration.
+
+We also generally use WordPress menus in Rooftop for the main navigation on a site, and also footer links.
+
+### `subnavigation_for()` helper
+Given a page, this helper will return a nested unordered list of links, starting at the root of the page, and rendering the page, it's parents and their siblings, and its ancestors above parents.
+
+Here's a call to the helper in a view, with the default options shown:
+
+```
+<%# @page is defined in your controller as a call to Page.find() %>
+<%= subnavigation_for(@page, class: 'subnavigation-list', current_class: 'is-current', current: nil) %>
+```
+
+If you want to specify different class names for the UL and currently-active page, just amend the options.
+
+If you want to highlight *another page* when the subnav is rendered, that's fine too:
+
+```
+<%= subnavigation_for(@page, current: @another_page) %>
+```
+
+You might want to do this if, for example, your markup requires some navigational components in 2 different places.
+
+### `menu_for()` helper
+Given a `Rooftop::Menus::Menu` object, `menu_for()` will return a nested unordered list.
+
+```
+<%# @menu is defined in your controller as a call to Rooftop::Menus::Menu.find()
+<%= menu_for(@menu, current_class: 'is-current') %>
+```
+
+A utility `menu-level-[x]` class is added to each level of the nested menu, in case you want to target a particular level in a different way with css. Useful for dropdown menus.
+
+### `breadcrumbs_for()` helper
+Breadcrumbs are similar to a nested subnavigation, but they only represent a direct path to this page (or other nested post type).
+
+```
+<%# @page is defined in your controller as a call to Page.find() %>
+<%= breadcrumbs_for(@page, class: 'breadcrumbs', current_class: 'is-current') %>
+```
+
+# Licence
+This gem is licenced GPLv3; contributions are most welcome!
+
+# Contributing
+The usual: fork, change, PR. Clean PRs (rebased if necessary) are preferred, but anything you can do is valuable.

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/app/controllers/concerns/rooftop/rails/extras/contact_form_handler.rb

@@ -0,0 +1,46 @@
+module Rooftop
+  module Rails
+    module Extras
+      # A controller mixin to handle contact forms easily. If you don't use Page as your page class, you need to specify it.
+      # You also need to specify the contact form class you're using (which needs to inherit from Rooftop::Rails::Extras::ContactForm)
+      module ContactFormHandler
+        extend ActiveSupport::Concern
+
+        class_methods do
+          def contact_form=(klass)
+            @contact_form = klass
+          end
+
+          def contact_form
+            @contact_form
+          end
+
+          def page_class=(klass)
+            @page_class = klass
+          end
+
+          def page_class
+            @page_class || ::Page
+          end
+        end
+
+        def create
+          raise ArgumentError, "You need to call contact_form=(YourClass) in your controller, which must inherit from Rooftop::Rails::Extras::ContactForm" unless self.class.contact_form.ancestors.include?(Rooftop::Rails::Extras::ContactForm)
+          raise ArgumentError, "You need to include hidden fields for from_page and to_page IDs, so this controller can redirect appropriately" unless params.has_key?(:from_page) && params.has_key?(:to_page)
+          form = self.class.contact_form.new(contact_form_params)
+          from_page, to_page = *self.class.page_class.where(post__in: [params[:from_page], params[:to_page]], orderby: :post__in)
+          if form.deliver
+            redirect_to Rooftop::Rails::RouteResolver.new(:page, to_page.nested_path).resolve
+          else
+            redirect_to Rooftop::Rails::RouteResolver.new(:page, from_page.nested_path).resolve(contact_form_params.merge(errors: form.errors.keys)), notice: form.errors.full_messages.to_sentence
+          end
+        end
+
+        private
+        def contact_form_params
+          params.require(self.class.contact_form.to_s.underscore.to_sym).permit(self.class.contact_form.fields.keys)
+        end
+      end
+    end
+  end
+end

data/app/helpers/rooftop/rails/extras/navigation_helper.rb

@@ -0,0 +1,117 @@
+module Rooftop
+  module Rails
+    module Extras
+      module NavigationHelper
+        def subnavigation_for(entity, opts = {})
+          default_opts = {
+            class: 'subnavigation-list',
+            current_class: 'is-current',
+            current: nil
+          }.merge(opts)
+          raise ArgumentError, "#{entity.class} isn't a nested class" unless entity.respond_to?(:resolved_children)
+          raise ArgumentError, "You passed a current #{entity.class.to_s.downcase} which isn't a #{entity.class} object" unless (default_opts[:current].nil? || default_opts[:current].is_a?(entity.class))
+          if entity.resolved_children.any?
+            # byebug
+            content_tag(:ul, class: default_opts[:class]) do
+              items = entity.resolved_children.collect do |child|
+                subnavigation_item_for(child, default_opts)
+              end
+              items.join.html_safe
+            end
+          end
+        end
+
+        def menu_for(menu, opts={})
+          default_opts = {
+            class: 'main-navigation-list',
+            current_class: 'is-current'
+          }.merge(opts)
+          content_tag(:ul, class: default_opts[:class]) do
+            items = menu.items.collect do |item|
+              menu_item_for(item, opts)
+            end
+            items.join.html_safe
+          end
+        end
+
+        def menu_item_for(item, opts={})
+          default_opts = {
+            current_class: 'is-current',
+            level: 1
+          }.merge(opts)
+          item_path = path_for_menu_item(item)
+          item_class = path_matches?(item_path) ? default_opts[:current_class] : ""
+          content_tag :li, class: item_class do
+            link = content_tag :a, href: item_path do
+              item.title.html_safe
+            end
+            child_links = ""
+            if item.children.present?
+              child_links = content_tag :ul, class: "menu-level-#{default_opts[:level]}" do
+                items = item.children.collect do |child|
+                  menu_item_for(child, default_opts.merge({level: default_opts[:level] + 1}))
+                end
+                items.join.html_safe
+              end
+            end
+            link + child_links
+          end
+        end
+
+        def breadcrumbs_for(entity, opts = {})
+          default_opts = {
+            class: 'breadcrumbs',
+            current_class: 'is-current'
+          }.merge(opts)
+          content_tag :ul, class: default_opts[:class] do
+            items = entity.ancestors.reverse.inject({}) do |links,ancestor|
+              links[(links.present? ?  "#{links.keys.last}/#{ancestor.slug}" : ancestor.slug)] = ancestor
+              links
+            end
+            items.merge!({"#{items.keys.last}/#{entity.slug}" => entity})
+            links = items.collect do |path, item|
+              item_class = (item.id == entity.id ? default_opts[:current_class] : "")
+              content_tag :li, class: item_class do
+                content_tag :a, href: "/#{path}" do
+                  item.title
+                end
+              end
+            end
+            links.join.html_safe
+          end
+        end
+
+        private
+        def subnavigation_item_for(entity, opts = {})
+          list_opts = {}
+          opts.reverse_merge!({level: 1})
+          list_opts[:class] = opts[:current_class] if opts[:current].present? && opts[:current].id == entity.id
+          # The link to the entity
+          content_tag :li, list_opts do
+
+            link = content_tag :a, href: "/#{entity.nested_path}" do
+              entity.title.html_safe
+            end
+
+            child_links = ""
+
+            # Nested ul for children if necessary
+            if opts[:current].present? && (opts[:current].ancestors.collect(&:id).include?(entity.id) || opts[:current].id == entity.id)
+              children = entity.class.where(post_parent: entity.id)
+              if children.any?
+                child_links = content_tag :ul, class: "subnavigation-level-#{opts[:level]}" do
+                  items = children.collect do |child|
+                    subnavigation_item_for(child, opts.merge({level: opts[:level] + 1}))
+                  end
+                  items.join.html_safe
+                end
+              end
+            end
+            link + child_links
+          end
+        end
+
+      end
+    end
+  end
+end

data/app/helpers/rooftop/rails/extras/related_fields_helper.rb

@@ -0,0 +1,14 @@
+module Rooftop
+  module Rails
+    module Extras
+      module RelatedFieldsHelper
+        def field_from_related_resource(resource, field)
+          field_data = resource[:advanced].select {|f| f[:fields].collect {|f| f[:name] == field.to_s}.any?}
+          if field_data.any?
+            field_data.first[:fields].find {|f| f[:name] == field.to_s}.try(:[],:value)
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/concerns/rooftop/rails/extras/contact_form.rb

@@ -0,0 +1,51 @@
+module Rooftop
+  module Rails
+    module Extras
+      class ContactForm < MailForm::Base
+        class << self
+          attr_accessor :fields, :subject, :to, :from, :headers
+        end
+
+        DEFAULT_FIELDS = {
+          name: :text_field,
+          email: :text_field,
+          message: :text_area
+        }
+
+        def self.inherited(base)
+          (base.fields || DEFAULT_FIELDS).keys.each do |field|
+            base.send(:attribute,field, {validate: true})
+          end
+
+          base.subject ||= "Contact form message"
+          base.to ||= "change.me@#{base.to_s.underscore}"
+          base.from ||= "change.me@#{base.to_s.underscore}"
+          base.headers ||= {}
+        end
+        #
+        # attribute :salutation
+        # attribute :first_name,      validate: true
+        # attribute :last_name,     validate: true
+        # attribute :email, validate: true
+        # attribute :phone
+        # attribute :message, validate: true
+        # attribute :nickname,  captcha: true
+
+        # Declare the e-mail headers. It accepts anything the mail method
+        # in ActionMailer accepts.
+        def headers
+          {
+            subject: self.class.subject,
+            to: self.class.to,
+            from: %("Contact form" <#{self.class.from}>)
+          }.merge(self.class.headers)
+        end
+
+        def fields
+          self.class.fields
+        end
+
+      end
+    end
+  end
+end

data/app/models/concerns/rooftop/rails/extras/page_redirect.rb

@@ -0,0 +1,20 @@
+module Rooftop
+  module Rails
+    module Extras
+      module PageRedirect
+        extend ActiveSupport::Concern
+
+        def redirect?
+          fields.respond_to?(:redirect_this_page) && fields.redirect_this_page == true && fields.respond_to?(:redirect_url) && fields.redirect_url.present?
+        end
+
+        def redirect_to
+          if redirect?
+            fields.redirect_url
+          end
+        end
+
+      end
+    end
+  end
+end

data/app/models/concerns/rooftop/rails/extras/resolved_children.rb

@@ -0,0 +1,21 @@
+module Rooftop
+  module Rails
+    module Extras
+      module ResolvedChildren
+        extend ActiveSupport::Concern
+
+        def resolved_children
+          child_ids = children.collect(&:id)
+
+          if child_ids.any?
+            self.class.where(post__in: child_ids)
+          else
+            []
+          end
+
+        end
+      end
+
+    end
+  end
+end

data/app/models/concerns/rooftop/rails/extras/resource_search.rb

@@ -0,0 +1,48 @@
+module Rooftop
+  module Rails
+    module Extras
+      # A module to search for free text in a resource. You can add extra fields to search the free text in, by specifying a proc to call (which should return the text you want to search)
+      module ResourceSearch
+        extend ActiveSupport::Concern
+
+        included do
+          scope :search, ->(q) {
+            all.to_a.select do |item|
+              q = q.gsub(/[^a-zA-z1-9 ]/,"")
+              item.searchable_text.match(%r{#{q.downcase}})
+            end
+          }
+        end
+
+        class_methods do
+
+          # A method which takes a lambda which is expected to return a string of text for searching.
+          def add_search_field(field)
+            @search_fields ||= []
+            @search_fields << field
+          end
+          # A collection of lambdas, each of which returns a string
+          def search_fields
+            @search_fields ||= []
+          end
+        end
+
+        def searchable_text
+          remove_regex = /[^a-zA-z1-9 ]/
+          text = []
+          text << title.gsub(remove_regex,"").downcase
+          text << ActionController::Base.helpers.strip_tags(fields.content).gsub(remove_regex,"").downcase
+          # Iterate over the search field lambdas, and call each one, passing in self. Check the arity is 1, to ensure that the lambda is expecting the object
+          self.class.search_fields.each do |field|
+            if field.arity == 1
+              text << ActionController::Base.helpers.strip_tags(field.call(self)).gsub(remove_regex,"").downcase
+            end
+          end
+          text.join(" ")
+
+        end
+
+      end
+    end
+  end
+end

data/lib/generators/rooftop/extras_generator.rb

@@ -0,0 +1,21 @@
+module Rooftop
+  class ExtrasGenerator < ::Rails::Generators::Base
+    desc "A wrapper around the common things we do with Rooftop and Rails. Creates a PagesController, Page model, sets up templates as we tend to "
+
+    def create_page_class
+      generate 'rooftop:page'
+    end
+
+    def install_pages_controller
+      generate 'rooftop:pages_controller'
+    end
+
+    def create_content_page_template
+      generate "rooftop:template content_page"
+    end
+
+    def create_post_class
+      generate 'rooftop:post post'
+    end
+  end
+end

data/lib/generators/rooftop/page_generator.rb

@@ -0,0 +1,14 @@
+module Rooftop
+  class PageGenerator < ::Rails::Generators::Base
+    source_root File.expand_path("../templates", __FILE__)
+    desc "Generate a page class, mixing in Rooftop::Page and Rooftop::Rails::Extras::ResourceSearch"
+    class_option :class_name, :type => :string, :desc => "The class name to generate", :default => "page"
+    def create_class
+      template 'page_class.rb.erb', 'app/models/page.rb'
+    end
+
+    def create_decorator
+      generate "decorator #{options[:class_name]}"
+    end
+  end
+end

data/lib/generators/rooftop/pages_controller_generator.rb

@@ -0,0 +1,27 @@
+module Rooftop
+    class PagesControllerGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("../templates", __FILE__)
+      desc "Generate a standardised PagesController and views. Assumes a PageDecorator and Page model"
+
+      def copy_template
+        template "pages_controller.rb.erb", "app/controllers/pages_controller.rb"
+      end
+
+      def create_views
+        template "application.html.erb", "app/views/layouts/application.html.erb"
+        template "show.html.erb", "app/views/pages/show.html.erb"
+        template "index.html.erb", "app/views/pages/index.html.erb"
+      end
+
+      def add_route
+        comment_lines 'config/routes.rb', /pages#.*/
+        route 'root to: "pages#index"'
+        route 'match "/*nested_path", via: [:get], to: "pages#show", as: :page'
+        inject_into_file 'config/routes.rb', before: 'match "/*nested_path"' do <<-'RUBY'
+        # IMPORTANT: this is a greedy catchall route - it needs to be the last route in the file.
+        RUBY
+        end
+      end
+
+    end
+end

data/lib/generators/rooftop/post_generator.rb

@@ -0,0 +1,9 @@
+module Rooftop
+  class PostGenerator < ::Rails::Generators::NamedBase
+    source_root File.expand_path("../templates", __FILE__)
+    desc "Generate a post class - requires the name of the class to create"
+    def create_class
+      template 'post_class.rb.erb', "app/models/#{name}.rb"
+    end
+  end
+end

data/lib/generators/rooftop/template_generator.rb

@@ -0,0 +1,9 @@
+module Rooftop
+  class TemplateGenerator < ::Rails::Generators::NamedBase
+    source_root File.expand_path("../templates", __FILE__)
+    desc "Generate a template in views/layouts/templates"
+    def copy_template
+      template "template.html.erb", "app/views/layouts/templates/#{name}.html.erb"
+    end
+  end
+end

data/lib/generators/rooftop/templates/application.html.erb

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <title><%= Rails.application.class.parent_name %></title>
+    <%%= stylesheet_link_tag    'application', media: 'all' %>
+    <%%= javascript_include_tag 'application' %>
+    <%%= csrf_meta_tags %>
+</head>
+<body>
+
+<%%= content_for?(:template) ? yield(:template) : yield %>
+
+</body>
+</html>

data/lib/generators/rooftop/templates/index.html.erb

@@ -0,0 +1,2 @@
+<p>This renders the index method of the PagesController - generally the homepage. This view is available in <%%= __FILE__ %></p>
+

data/lib/generators/rooftop/templates/page_class.rb.erb

@@ -0,0 +1,4 @@
+class <%= options[:class_name].classify %>
+    include Rooftop::Page
+    include Rooftop::Rails::Extras::ResourceSearch
+end

data/lib/generators/rooftop/templates/pages_controller.rb.erb

@@ -0,0 +1,49 @@
+class PagesController < ApplicationController
+  include Rooftop::Rails::NestedResource
+  nested_rooftop_resource :page
+  decorates_assigned :page, with: PageDecorator
+
+  prepend_before_action :redirect_page_if_required, only: :show
+  prepend_before_action :find_and_validate_page, only: :show
+
+  layout :determine_layout
+
+  # This is the homepage. We're assuming that the slug is 'home'
+  def index
+    @page = Page.find_by(slug: "home").first
+    get_homepage_content
+  end
+
+  # This is the method used to render every page on the site except the homepage
+  def show
+  end
+
+
+  private
+
+  # If there's a redirect required, do that instead of rendering.
+  def redirect_page_if_required
+    if @page.redirect?
+      redirect_to @page.fields.redirect_url and return
+    end
+  end
+
+  # Determine which layout to show, assuming a standardised approach of having a templates folder under layouts with all the templates in, named as underscored versions of the Rooftop template names.
+  def determine_layout
+    if action_name == "index"
+      "templates/homepage"
+    else
+      if @page.present? && @page.template.present? && template_exists?(@page.template.underscore,File.join("layouts/templates"))
+        "templates/#{@page.template.underscore}"
+      else
+        "templates/content_page"
+      end
+    end
+  end
+
+  def get_homepage_content
+    # This is where you put homepage-specific stuff - usually other calls to Rooftop which you assign to instance variables.
+  end
+
+
+end

data/lib/generators/rooftop/templates/post_class.rb.erb

@@ -0,0 +1,3 @@
+class <%= name.classify %>
+    include Rooftop::Post
+end

data/lib/generators/rooftop/templates/show.html.erb

@@ -0,0 +1,3 @@
+<p>This renders the show() methods of PagesController, generally every page on the site except the homepage. It is available in <%%= __FILE__ %></p>
+<p>The title of this page is <%%= @page.try(:title).try(:html_safe) %></p>
+

data/lib/generators/rooftop/templates/template.html.erb

@@ -0,0 +1,8 @@
+<%% content_for :template do %>
+    <p>This template is in <%%= __FILE__ %></p>
+
+    <%%= yield %>
+
+<%% end %>
+
+<%%= render template: "layouts/application" %>