help_engine 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZDk2OTg5NWE0YTJlYWVjMTkzZGZhYzMzNGU5OTNmMTQ3MzlmMTRmZQ==
+  data.tar.gz: !binary |-
+    N2JhYzZlMWI0MTMxMDAzYmMxYTE1NzFjM2Q4YmQ4NzVkN2NiOTAxNA==
+SHA512:
+  metadata.gz: !binary |-
+    Y2E2YjcyYjU3MTA0MjhlYjMzMWIzOThkMjkwN2NhMDM1NzMxYTk4N2JkYWQ3
+    NmUzMjBiNjE3YzkwYjU5MDNhOWMwNGFjZTk2OTZiYjA2MTc0MGI5NTRiMzUx
+    Y2UyZTA1YWJjMzFmMzFkNGI1OGEzMzczZjJiZmM1M2E4NDkyMzk=
+  data.tar.gz: !binary |-
+    ZDFmYzUxNjJjY2EwYThjNGFkODEzMDc5M2FiZDA0YTgyZTQ0Yjc5ZDUwNTJi
+    MmYyYjg4Zjk0NzI4OTQxNjQ3OGFjMTI5ZTY2NThjMGU4MzA3MmYwYWY5M2Ez
+    MGNkMTFkYzEzZWYwMDhkNTJmMDdkYzY3MzdjZjJkZDJhZGIwMTk=

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2015 Rob Nichols and Warwickshire Count Council
+
+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.rdoc

@@ -0,0 +1,129 @@
+= Help Engine
+
+A basic system to add help pages to a Rails application.
+
+I often find myself tacking a simple help system on to rails apps. They
+are usually very simple, and allow users to add and modify the content. As
+I do it so often, I thought I'd bundle it all into a gem so that I can make
+the process even simpler.
+
+== Installation
+
+First add the gem to the host app's Gemfile:
+
+  gem 'help_engine'
+
+Then mount the engine via config/routes.rb:
+
+    mount HelpEngine::Engine => "help"
+
+== Usage
+
+Each help page has a unique slug that is used to generate unique meaningful
+urls. So if a help page is named "Foo Bar", it will have a slug 'foo-bar' and
+the page's url will be help/pages/foo-bar.
+
+To add a link to a particular help page, use the slug to identify the page:
+
+    <%= link_to 'help on Foo Bar', help_engine.help_page_path('foo-bar') %>
+
+To add a link to the help index:
+
+    <%= link_to 'Help', help_engine.root_path %>
+
+On this page links are provided to each of the existing help pages, and there
+is also a link to create a new help page. See the Overriding Help Engine
+behaviour section below regarding added access control to help pages.
+
+== Content
+
+Markdown is used to define the content of help pages. The mark down used is
+as defined here:
+
+  http://daringfireball.net/projects/markdown/basics
+
+Markdown is used as it's easy to create well styled content without having to
+sanitise users' input.
+
+== Dummy app
+
+A dummy app is provided as part of this engine (test/dummy). This provides
+an example of how the engine can be used.
+
+== Author
+
+Each help_page has an author polymorphic relationship. So an user can be 
+associated to a help_page with:
+
+    help_page.author = user
+
+A has_many method can be added to an author class such as User, like this:
+
+  class User < ActiveRecord::Base
+
+    has_many :help_pages, as: :author, class_name: 'HelpEngine::HelpPage'
+
+    ...
+  end
+
+To store an author's identity on help page creation, the help pages controller
+will need to be overwritten.
+
+== Overriding Help Engine behaviour
+
+=== Overriding controllers
+As with most rails engines, you can override the Help Engine behaviour by adding
+matching objects in the host app. So for example, if you want to override how
+the HelpEngine::HelpPagesController behaves (to add access control for example),
+add your own controller code at the host app's:
+
+    app/controllers/help_engine/help_pages_controller.rb
+
+For example, if Devise is installed, you may do something like this (at
+app/controllers/help_engine/help_pages_controller):
+
+    class HelpEngine::HelpPagesController < ApplicationController
+
+      before_action :authenticate_user!, except: [:index, :show]
+
+      def create
+        @help_page = HelpPage.new(help_page_params)
+        @help_page.author = current_user
+
+        if @help_page.save
+          redirect_to @help_page, notice: 'Help page was successfully created.'
+        else
+          render :new
+        end
+      end
+
+    end
+
+=== Overriding views
+HelpEngine views can be overridden in the same way. For example, in the dummy
+app the help_engine layout has been overridden so that bootstrap styling can be
+applied to the help pages. see:
+
+    test/dummy/app/views/layouts/help_engine/application.html.erb
+
+This change has also modified where the CSS for these pages reside. For example,
+the textarea styling for the help_page content in the dummy app is defined at:
+
+    test/dummy/assets/stylesheets/help_pages.css
+
+== Deletion and JavaScript
+
+For the help page delete button to work, the JavaScript environment must be
+correctly set up in the host application. In the dummy app this is done by
+using the 'jquery-rails' gem and enabling jquery in the asset pipeline by
+adding these two lines to app/asserts/javascripts/application.js :
+
+    //= require jquery
+    //= require jquery_ujs
+
+This could be fixed by setting up jquery in the engine, but having had
+problems in the past with rails engines' jquery configuration clashing
+with the host app's jquery configuration, I don't think this is best
+practice. For those interested:
+
+  http://stackoverflow.com/questions/8788304/activeadmin-stops-my-jquery-working

data/Rakefile

@@ -0,0 +1,37 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rdoc/task'
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'HelpEngine'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load 'rails/tasks/engine.rake'
+
+
+load 'rails/tasks/statistics.rake'
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task default: :test

data/app/assets/javascripts/help_engine/application.js

@@ -0,0 +1,13 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or any plugin's vendor/assets/javascripts directory can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// compiled file.
+//
+// Read Sprockets README (https://github.com/sstephenson/sprockets#sprockets-directives) for details
+// about supported directives.
+//
+//= require_tree .

data/app/assets/javascripts/help_engine/help_pages.js

@@ -0,0 +1,2 @@
+// Place all the behaviors and hooks related to the matching controller here.
+// All this logic will automatically be available in application.js.

data/app/assets/stylesheets/help_engine/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any styles
+ * defined in the other CSS/SCSS files in this directory. It is generally better to create a new
+ * file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/assets/stylesheets/help_engine/help_pages.css

@@ -0,0 +1,4 @@
+.help_engine textarea {
+    width: 90%;
+    height: 20em;
+}

data/app/controllers/help_engine/application_controller.rb

@@ -0,0 +1,4 @@
+module HelpEngine
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/help_engine/help_pages_controller.rb

@@ -0,0 +1,62 @@
+require_dependency "help_engine/application_controller"
+
+module HelpEngine
+  class HelpPagesController < ApplicationController
+    before_action :set_help_page, only: [:show, :edit, :update, :destroy]
+
+    # GET /help_pages
+    def index
+      @help_pages = HelpPage.all
+    end
+
+    # GET /help_pages/1
+    def show
+    end
+
+    # GET /help_pages/new
+    def new
+      @help_page = HelpPage.new
+    end
+
+    # GET /help_pages/1/edit
+    def edit
+    end
+
+    # POST /help_pages
+    def create
+      @help_page = HelpPage.new(help_page_params)
+
+      if @help_page.save
+        redirect_to @help_page, notice: 'Help page was successfully created.'
+      else
+        render :new
+      end
+    end
+
+    # PATCH/PUT /help_pages/1
+    def update
+      if @help_page.update(help_page_params)
+        redirect_to @help_page, notice: 'Help page was successfully updated.'
+      else
+        render :edit
+      end
+    end
+
+    # DELETE /help_pages/1
+    def destroy
+      @help_page.destroy
+      redirect_to help_pages_url, notice: 'Help page was successfully destroyed.'
+    end
+
+    private
+      # Use callbacks to share common setup or constraints between actions.
+      def set_help_page
+        @help_page = HelpPage.friendly.find(params[:id])
+      end
+
+      # Only allow a trusted parameter "white list" through.
+      def help_page_params
+        params.require(:help_page).permit(:name, :slug, :content)
+      end
+  end
+end

data/app/helpers/help_engine/application_helper.rb

@@ -0,0 +1,4 @@
+module HelpEngine
+  module ApplicationHelper
+  end
+end

data/app/helpers/help_engine/help_pages_helper.rb

@@ -0,0 +1,4 @@
+module HelpEngine
+  module HelpPagesHelper
+  end
+end

data/app/models/help_engine/help_page.rb

@@ -0,0 +1,26 @@
+require 'github/markdown'
+require 'friendly_id'
+module HelpEngine
+  class HelpPage < ActiveRecord::Base
+
+    extend FriendlyId
+    friendly_id :name, use: :slugged
+
+    belongs_to :author, polymorphic: true
+
+    validates :name, :content, presence: true
+
+    def to_html
+      markdown.render content
+    end
+
+    def self.markdown_parser
+      @markdown_parser ||= GitHub::Markdown
+    end
+
+    def markdown
+      self.class.markdown_parser
+    end
+
+  end
+end

data/app/views/help_engine/help_pages/_form.html.erb

@@ -0,0 +1,43 @@
+<%= form_for(@help_page) do |f| %>
+  <% if @help_page.errors.any? %>
+    <div id="error_explanation">
+      <h2><%= pluralize(@help_page.errors.count, "error") %> prohibited this help_page from being saved:</h2>
+
+      <ul>
+      <% @help_page.errors.full_messages.each do |message| %>
+        <li><%= message %></li>
+      <% end %>
+      </ul>
+    </div>
+  <% end %>
+
+  <div class="field">
+    <%= f.label :name %><br>
+    <%= f.text_field :name %>
+  </div>
+  <p>
+    The name is used to describe the page in the help page index, and to generate
+    the string used to give the page an unique url (the "slug").
+    <% if @help_page.persisted? %>
+      The slug for this page is <em><%= @help_page.slug %></em>.
+    <% else %>
+      That is, creating a page named "Foo bar" will create the slug "foo-bar" and
+      the url for the help page will end: /foo-bar.
+    <% end %>
+  </p>
+
+  <div class="field">
+    <%= f.label :content %><br>
+    <%= f.text_area :content %>
+  </div>
+
+  <p>
+    Content should be entered using Markdown. The Markdown syntax is described
+    <%= link_to 'here', 'http://daringfireball.net/projects/markdown/basics', target: '_blank' %>.
+    This content will form the main output when displaying the help page.
+  </p>
+
+  <div class="actions">
+    <%= f.submit class: 'btn btn-warning' %>
+  </div>
+<% end %>

data/app/views/help_engine/help_pages/edit.html.erb

@@ -0,0 +1,8 @@
+<article class="help_page">
+  <h1>Editing Help Page</h1>
+
+  <%= render 'form' %>
+</article>
+
+<%= link_to 'Show', @help_page %>
+<%= link_to 'List', help_pages_path %>

data/app/views/help_engine/help_pages/index.html.erb

@@ -0,0 +1,21 @@
+<h1>Help Pages</h1>
+
+<%= link_to 'New Help page', new_help_page_path, class: 'btn btn-primary' %>
+
+<section class="help_pages">
+  <% if @help_pages.present? %>
+
+  <ul>
+    <% @help_pages.each do |help_page| %>
+          <li><%= link_to help_page.name, help_page %></li>
+    <% end %>
+    </tbody>
+  </table>
+
+  <% else %>
+
+  <h2>No help pages</h2>
+  <p>The first help page is yet to be added</p>
+
+  <% end %>
+</section>

data/app/views/help_engine/help_pages/new.html.erb

@@ -0,0 +1,7 @@
+<article class="help_page">
+  <h1>New Help Page</h1>
+
+  <%= render 'form' %>
+</article>
+
+<%= link_to 'List', help_pages_path, class: 'btn btn-primary' %>

data/app/views/help_engine/help_pages/show.html.erb

@@ -0,0 +1,16 @@
+<article class="help_page">
+
+  <div class="content">
+    <%= @help_page.to_html.html_safe %>
+  </div>
+
+  <%= link_to 'List', help_pages_path, class: 'btn btn-primary' %>
+  <%= link_to 'Edit', edit_help_page_path(@help_page), class: 'btn btn-warning' %>
+  <%= link_to(
+        'Delete',
+        @help_page,
+        method: :delete, data: { confirm: 'Are you sure?' },
+        class: 'btn btn-danger'
+      )
+  %>
+</article>