docent 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 Aaron Sumner
+
+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.markdown

@@ -0,0 +1,60 @@
+# Docent: Contextual support for Rails applications
+
+Docent is a friendly guide who points your application's users to the proper support documentation, as hosted in some external knowledge base like Desk.com, Zendesk, Confluence, and so on. It does so based on a table of URLs with controller-action combos, then supplies the link based on that view in your application.
+
+Docent is a proof-of-concept, based on something I baked into a Rails 2-point-something app back in 2008 and recently realized I could use again. It operates as a mountable Rails engine and is still pretty raw right now.
+
+## Setup
+
+1. Add Docent to your Gemfile and install with Bundler.
+
+2. Mount the engine in your application:
+
+        mount Docent::Engine => "/docent"
+
+3. Add the Docent-specific tables to your database:
+
+        rake docent:install:migrations
+        rake db:migrate
+
+4. Create an initializer in `config/initializers/docent.rb`. This establishes a default link (top level of your knowledge base, support form, whatever) for views without support documents in Docent; it also provides a username and password for authentication via HTTP Basic:
+
+        Docent.default_link = 'http://yourhelpsite.com/docs'
+        Docent.username = 'docent_admin'
+        Docent.password = 'secret'
+
+## Usage
+
+1. Load Docent's admin panel at `http://yourapp.com/docent`
+
+2. Enter links to support documents. You can enter links specific to a controller#action combination, as well as catch-all links to controllers. Docent looks for links in the following order:
+
+  1. The controller#action combination (e.g., `posts#new`)
+  2. The controller only
+  3. The default, set above in the initializer
+
+3. Provide links to your application's users by adding the following in your application's layout file:
+
+        <%= link_to_docent %>
+
+  By default, Docent labels the link *Help*; you can add your own and any options you could otherwise pass to Rails' `link_to` helper:
+
+        <%= link_to_docent 'Support', {target: 'new' } %>
+
+## To Do
+
+- add a generator to do most of the setup automatically
+- replace HTTP basic authentication with something integrated with the host application
+- add support for self-hosted documents (I'd link to be able to post documents directly from ScreenSteps into Docent via XMLRPC, for example).
+
+## Contributing
+
+I'd love to see your ideas and improvements. Fork the project on GitHub, make your changes (with specs!), and submit a pull request. **A note on specs:** I used Capybara feature specs to build Docent; the specs related to end-user access to links currently relies on a non-Rack::Test driver due to the need to check for redirection to an external site. I stuck with Selenium to minimize dependencies, at the expense of speed.
+
+StatBoard is released under the [MIT License][mit]. See MIT-LICENSE for further details.
+
+[mit]: http://www.opensource.org/licenses/MIT
+
+## Thanks
+
+Having not messed with mountable engines in Rails much in the past, I took inspiration from [StatBoard](https://github.com/vigetlabs/stat_board) by Viget Labs (in particular the initializer setup and testing setup).

data/Rakefile

@@ -0,0 +1,27 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Docent'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+

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

@@ -0,0 +1,15 @@
+// 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 vendor/assets/javascripts of plugins, if any, 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
+// the compiled file.
+//
+// WARNING: THE FIRST BLANK LINE MARKS THE END OF WHAT'S TO BE PROCESSED, ANY BLANK LINE SHOULD
+// GO AFTER THE REQUIRES BELOW.
+//
+//= require jquery
+//= require jquery_ujs
+//= require_tree .

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

@@ -0,0 +1,13 @@
+/*
+ * 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 vendor/assets/stylesheets of plugins, if any, 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 top of the
+ * compiled file, but it's generally better to create a new file per style scope.
+ *
+ *= require_self
+ *= require_tree .
+ */

data/app/assets/stylesheets/docent/scaffold.css

@@ -0,0 +1,120 @@
+body {
+  background-color: #fff;
+  color: #333;
+  margin: 0;
+  padding: 0;
+}
+
+body, p, ol, ul, td {
+  font-family: helvetica, arial, sans-serif;
+  font-size:   13px;
+  line-height: 18px;
+}
+
+pre {
+  background-color: #eee;
+  padding: 10px;
+  font-size: 11px;
+}
+
+a { color: #026; }
+
+a.button {
+  color: #fff;
+  text-decoration: none;
+  background-color: #026;
+  padding: 4px;
+  -mozilla-border-radius: 3px;
+  -webkit-border-radius: 3px;
+  border-radius: 3px;
+}
+
+div.field, div.actions {
+  margin-bottom: 10px;
+}
+
+header {
+  background-color: #ccc;
+  color: #fff;
+  padding: 5px 20px;
+}
+
+header h1 {
+  font-weight: normal;
+}
+
+header a {
+  color: #fff;
+  text-decoration: none;
+}
+
+#content {
+  margin: 20px;
+}
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+th {
+  text-align: left;
+}
+
+tr {
+  height: 40px;
+}
+
+th, td {
+  padding: 10px;
+}
+
+tr td:last-child {
+  text-align: right;
+}
+
+.odd { background-color: #eee; }
+.even { background-color: #fff; }
+
+footer {
+  color: #ccc;
+  border-top: 1px solid #ccc;
+  margin-top: 25px;
+  padding-top: 25px;
+  text-align: center;
+}
+
+#notice {
+  color: green;
+}
+
+.field_with_errors {
+  padding: 2px;
+  background-color: red;
+  display: table;
+}
+
+#error_explanation {
+  width: 450px;
+  border: 2px solid red;
+  padding: 7px;
+  padding-bottom: 0;
+  margin-bottom: 20px;
+  background-color: #f0f0f0;
+}
+
+#error_explanation h2 {
+  text-align: left;
+  font-weight: bold;
+  padding: 5px 5px 5px 15px;
+  font-size: 12px;
+  margin: -7px;
+  margin-bottom: 0px;
+  background-color: #c00;
+  color: #fff;
+}
+
+#error_explanation ul li {
+  font-size: 12px;
+  list-style: square;
+}

data/app/controllers/docent/application_controller.rb

@@ -0,0 +1,13 @@
+module Docent
+  class ApplicationController < ActionController::Base
+    before_filter :basic_authenticate, if: lambda { Docent.username and Docent.password }
+
+    private
+
+    def basic_authenticate
+      authenticate_or_request_with_http_basic do |name, password|
+        name == Docent.username and password == Docent.password
+      end
+    end
+  end
+end

data/app/controllers/docent/links_controller.rb

@@ -0,0 +1,45 @@
+require_dependency "docent/application_controller"
+
+module Docent
+  class LinksController < ApplicationController
+
+    def index
+      @links = Link.all
+    end
+
+    def new
+      @link = Link.new
+    end
+
+    def edit
+      @link = Link.find(params[:id])
+    end
+
+    def create
+      @link = Link.new(params[:link])
+
+      if @link.save
+        redirect_to links_url, notice: 'Successfully created link.'
+      else
+        render action: "new"
+      end
+    end
+
+    def update
+      @link = Link.find(params[:id])
+
+      if @link.update_attributes(params[:link])
+        redirect_to links_url, notice: 'Successfully updated link.'
+      else
+        render action: "edit"
+      end
+    end
+
+    def destroy
+      @link = Link.find(params[:id])
+      @link.destroy
+
+      redirect_to links_url, notice: 'Successfully deleted link.'
+    end
+  end
+end

data/app/helpers/docent/application_helper.rb

@@ -0,0 +1,7 @@
+module Docent
+  module ApplicationHelper
+    def link_to_docent(label="Help", options={})
+      link_to label, Docent::Link.link_for(controller.controller_name, controller.action_name), options
+    end
+  end
+end

data/app/models/docent/link.rb

@@ -0,0 +1,21 @@
+module Docent
+  class Link < ActiveRecord::Base
+    attr_accessible :action, :controller, :url
+
+    def shortcut
+      "#{controller}##{action}"
+    end
+
+    def self.link_for(controller=nil, action=nil)
+      if link = self.where(controller: controller).
+                where(action: action).
+                first
+        link.url
+      elsif link = self.where(controller: controller).first
+        link.url
+      else
+        Docent.default_link
+      end
+    end
+  end
+end

data/app/views/docent/links/_form.html.erb

@@ -0,0 +1,29 @@
+<%= form_for(@link) do |f| %>
+  <% if @link.errors.any? %>
+    <div id="error_explanation">
+      <h2><%= pluralize(@link.errors.count, "error") %> prohibited this link from being saved:</h2>
+
+      <ul>
+      <% @link.errors.full_messages.each do |msg| %>
+        <li><%= msg %></li>
+      <% end %>
+      </ul>
+    </div>
+  <% end %>
+
+  <div class="field">
+    <%= f.label :controller %><br />
+    <%= f.text_field :controller %>
+  </div>
+  <div class="field">
+    <%= f.label :action %><br />
+    <%= f.text_field :action %>
+  </div>
+  <div class="field">
+    <%= f.label :url, 'URL' %><br />
+    <%= f.text_field :url %>
+  </div>
+  <div class="actions">
+    <%= f.submit %>
+  </div>
+<% end %>

data/app/views/docent/links/edit.html.erb

@@ -0,0 +1,6 @@
+<h1>Editing link</h1>
+
+<%= render 'form' %>
+
+<%= link_to 'Show', @link %> |
+<%= link_to 'Back', links_path %>

data/app/views/docent/links/index.html.erb

@@ -0,0 +1,20 @@
+<h1>Links</h1>
+
+<%= link_to 'New Link', new_link_path, class: 'button' %>
+
+<table>
+  <tr>
+    <th>controller#action</th>
+    <th>URL</th>
+    <th></th>
+  </tr>
+
+<% @links.each do |link| %>
+  <tr id="link_<%= link.id %>" class="<%= cycle('odd','even') %>">
+    <td><%= link_to link.shortcut, edit_link_path(link) %></td>
+    <td><%= link_to link.url, link.url %></td>
+    <td><%= link_to 'Delete', link, method: :delete, data: { confirm: 'Are you sure?' }, class: 'button' %></td>
+  </tr>
+<% end %>
+</table>
+

data/app/views/docent/links/new.html.erb

@@ -0,0 +1,5 @@
+<h1>New link</h1>
+
+<%= render 'form' %>
+
+<%= link_to 'Back', links_path %>

data/app/views/layouts/docent/application.html.erb

@@ -0,0 +1,25 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Docent</title>
+  <%= stylesheet_link_tag    "docent/application", :media => "all" %>
+  <%= javascript_include_tag "docent/application" %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+  <header>
+    <h1><%= link_to 'Docent', root_path %></h1>
+  </header>
+
+  <div id="content">
+    <p id="notice"><%= notice %></p>
+    <%= yield %>
+  </div>
+
+  <footer>
+    Powered by
+    <%= link_to 'Docent', 'https://github.com/ruralocity/docent' %>
+    <%= Docent::VERSION %>
+  </footer>
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,5 @@
+Docent::Engine.routes.draw do
+  resources :links
+
+  root to: 'links#index'
+end

data/db/migrate/20121223020016_create_docent_links.rb

@@ -0,0 +1,11 @@
+class CreateDocentLinks < ActiveRecord::Migration
+  def change
+    create_table :docent_links do |t|
+      t.string :controller
+      t.string :action
+      t.string :url
+
+      t.timestamps
+    end
+  end
+end

data/lib/docent.rb

@@ -0,0 +1,5 @@
+require "docent/engine"
+
+module Docent
+  mattr_accessor :default_link, :username, :password
+end

data/lib/docent/engine.rb

@@ -0,0 +1,18 @@
+module Docent
+  class Engine < ::Rails::Engine
+    isolate_namespace Docent
+
+    initializer 'contextual_help.action_controller' do |app|
+      ActiveSupport.on_load :action_controller do
+        helper Docent::ApplicationHelper
+      end
+    end
+
+    config.generators do |g|
+      g.test_framework      :rspec,        :fixture => false
+      g.fixture_replacement :factory_girl, :dir => 'spec/factories'
+      g.assets false
+      g.helper false
+    end
+  end
+end

data/lib/docent/version.rb

@@ -0,0 +1,3 @@
+module Docent
+  VERSION = "0.0.1"
+end

data/lib/tasks/docent_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :docent do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,186 @@
+--- !ruby/object:Gem::Specification
+name: docent
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Aaron Sumner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-12-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.2'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.12.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.12.0
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.0.1
+- !ruby/object:Gem::Dependency
+  name: factory_girl_rails
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 4.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 4.1.0
+- !ruby/object:Gem::Dependency
+  name: database_cleaner
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Docent is a mountable Rails engine to provide your app's users with links
+  to proper support documentation.
+email:
+- asumner@mac.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- app/assets/javascripts/docent/application.js
+- app/assets/stylesheets/docent/application.css
+- app/assets/stylesheets/docent/scaffold.css
+- app/controllers/docent/application_controller.rb
+- app/controllers/docent/links_controller.rb
+- app/helpers/docent/application_helper.rb
+- app/models/docent/link.rb
+- app/views/docent/links/_form.html.erb
+- app/views/docent/links/edit.html.erb
+- app/views/docent/links/index.html.erb
+- app/views/docent/links/new.html.erb
+- app/views/layouts/docent/application.html.erb
+- config/routes.rb
+- db/migrate/20121223020016_create_docent_links.rb
+- lib/docent/engine.rb
+- lib/docent/version.rb
+- lib/docent.rb
+- lib/tasks/docent_tasks.rake
+- MIT-LICENSE
+- Rakefile
+- README.markdown
+homepage: https://github.com/ruralocity/docent
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 3064965182523156662
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 3064965182523156662
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Contextually-aware links to externally-hosted support docs.
+test_files: []