doop 0.0.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    NDZjODg0NTdlY2FkODllYmE3YzhhMmJkYzhjNGFhOTUyZDAxYWJhMg==
+  data.tar.gz: !binary |-
+    MmI1MGNlMWVmNWQ0NTBiMDYzMjVlMzJhYzRhMmNhNWE5NDQ5MWQxNQ==
+SHA512:
+  metadata.gz: !binary |-
+    ZWI3Y2UwYmUzNjhhNGI0YjU5ZTk2YmZiMTBhMDhlY2U2Nzk1Y2I2ZWNiNzY5
+    ZjA4OTNkNmI0YWNjMmIzMzIyZWNiMGFjZjE5OTlmMjJmZTZmMzYxMmZlODhl
+    ZTljMGRiODdkMDM2YWM5YjY1NmJiNjY1NzJhM2ZmYTQwNTI0N2I=
+  data.tar.gz: !binary |-
+    YmI5M2ViZDkzYjYyNzAwYmFlNjQzMmFjZGJkMTdjZmI5YzBiNmUwZGQzZDBi
+    YmE4ZGQyNjQ2M2RkMjg1ZjdkZWYyZmEyMTQzMmIxYTFmMTZhN2M0YmE2MTIz
+    NjQyYjkwNTI0MTllOWYxY2U1NmNmZmY2NzU3MGVhY2JhYmU1ZmE=

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+*.swp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in doop.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 coder36
+
+MIT License
+
+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,203 @@
+# Doop
+
+A question framework for govuk sites, inspired by the great work GDS have done to standardize the cross government internet presence.
+
+# Quick start
+
+Assuming ruby, rails and nodejs is installed:
+
+    $ rails new govsite
+    $ cd govsite
+    $ echo "gem 'doop'" >> Gemfile
+    $ bundle
+    $ rails generate doopgovuk demo
+    $ rails s
+
+Navigate to http://localhost:3000
+
+This is still in development, so if you want the latest, then add `gem 'doop', git: 'git://github.com/coder36/doop.git'` to your Gemfile.
+
+
+     
+
+## Background
+Whilst working with the Student Loans company and GDS we discovered that the best way to get a student to fill a form in was to progressively ask questions, one after the other rather than as one big form.  User experience testing showed this was a far less intimidating experience, and they would more likely stick at it.  Furthermore, based on pevious answers, we  can choose which questions to ask.  This makes each questionaire effectively tailored to the individual student.
+
+Other things we learned, was that students hate answering lots of questions, only to find at the end they are not eligible.  So the order of questions is very important, and thats why some of the early questions when applying for a student loan may seem a bit obscure, but they are designed to weed out those who are inelligble as soon as possible. 
+
+If you compare the Student loans site and the DVLA site, which are both govuk questionaires you will see that they have been implemented in very different ways, and as a result look fairly different, but essentially do the same thing.  In fact I found that within the same company, you had multiple approaches, and completely different technology stacks to achieve the same thing.  I spent months writing Daone of these sites, 
+
+Designing something from scratch is expensive and time consuming.  This is where GDS have added real value.  They have provided a set of ruby gems to trivialise the production of
+govuk sites.  One thing they are lacking however is a gem to trivialize the creation of complex questionaires.  And this is why government organisations are seemingly reinventing
+the wheel multiple times over.  This is the niche which Doop fills.
+
+If your govuk site requires any kind of questionaire, doop is the answer.  
+
+
+## Features
+
+* DSL
+* Rails generator to quickly get you started
+* Ability to Change answer
+* Summarize answers
+* Broswer backbutton integration
+* Stateless
+* Fast
+* Ajax call backs
+* Built on rails 4
+
+
+# Usage
+
+## Generator
+
+Make sure that the gemfile contains gem 'doop'.   Then run
+
+    $ rails generate doopgovuk demo
+
+Navigate to http://localhost:3000 and you will see the demo questionaire.  
+    
+See the [demo rails controller](https://github.com/coder36/doop/blob/master/lib/generators/doopgovuk/templates/app/controllers/demo_controller.rb) to get a feel for the DSL.
+
+
+## Yaml
+
+Doop is initiated with a Yaml data structure:
+
+    page: {
+      preamble: {
+        _page: "preamble",
+        _nav_name: "Apply Online",
+        enrolled_before: {
+          _question: "Have you enrolled for this service before ?"
+        },
+        year_last_applied: {
+          _question: "What year did you last apply?"
+        }
+      }
+    }
+
+Once initialized doop will add meta data to the structure.  Each question will get meta data.  So the above yaml will end up looking like:
+
+    page: {
+      _answered: false,
+      _answer: "",
+      _summary: "",
+      _enabled: true,
+      _open: false,
+      preamble: {
+        _answered: false,
+        _answer: "",
+        _summary: "",
+        _enabled: true,
+        _page: "preamble",
+        _nav_name: "Apply Online",
+        enrolled_before: {
+          _answered: false,
+          _answer: "",
+          _summary: "",
+          _enabled: true,
+          _question: "Have you enrolled for this service before ?"
+        },
+        year_last_applied: {
+          _answered: false,
+          _answer: "",
+          _summary: "",
+          _enabled: true,
+          _question: "What year did you last apply?"
+        }
+      }
+    }
+
+Meta data always starts with an _.  Doop uses the meta data to keep track of whats been answerd, what's currently being asked, and what questions are enabled.
+
+
+
+## Question order
+
+The questions will be asked in the order in which they appear in yaml.  So for above, the order of questions will be:
+
+1.  page/preamble/enrolled_before
+2.  page/preamble/year_last_applied
+3.  page/preamble
+4.  page
+
+The most nested question is asked first, then the next and so ending on the least nested question.  
+
+
+As the questions are answered, callbacks will invoked.
+
+
+## Callbacks
+
+Call backs are used to manipulate the yaml structure, to set _metadata etc.  In the example below, when /page/preamble/enrolled_before is answered, the summary will be set to the answer.
+
+```ruby
+on_answer "/page/preamble/enrolled_before"  do |question,path, params, answer|
+  answer_with( question, { "_summary" => answer } )
+end
+
+```
+
+On_answer call backs can be used to change the question flow.  The code below will enable or disable the year_last_applied question depending on whether the answer was Yes or No:
+
+```ruby
+on_answer "/page/preamble/enrolled_before"  do |question,path, params, answer|
+  answer_with( question, { "_summary" => answer } )
+  enable( "/page/preamble/year_last_applied", answer == "Yes" )
+end
+```
+
+
+# Notes
+
+## Performance
+
+For the demo, the serialized questionaire is stored as a form parameter.  This is a nice approach as a general strategy since its completely stateless and as a result scalable.  
+Its also very fast.  
+
+I've worked with a lot of java farmeworks (I'm thinking JSF!) and in comparison I can assure you that the demo application is fast.  Doop fully supports jruby, so you may get some 
+optimisation going down that route.  As mentioned earlier its completely stateless, so you can scale by simply firing up more servers. 
+
+I tested it with passenger and nginx and it was lightening fast.  Without any optimisation each request was taking about 20ms.
+
+## Jruby
+
+The yaml serialization uses encryption, so you will need to tell java to allow unlimted strength cryptography.  Create a file config/initializers/unlimited_strength_cryptography
+
+```ruby
+    platform :jruby do
+      require 'java'
+      security_class = java.lang.Class.for_name('javax.crypto.JceSecurity')
+      restricted_field = security_class.get_declared_field('isRestricted')
+      restricted_field.accessible = true
+      restricted_field.set nil, false
+    end
+```
+
+Don't forget to deal with database drivers.  In your Gemfile, you will need to use JDBC drivers:
+
+```ruby
+    platform :jruby do
+      gem 'activerecord-jdbcsqlite3-adapter'
+    end
+
+    platform :ruby do
+      gem 'sqlite3'
+    end
+```
+
+
+## TODO
+
+* Refactor -  make the code, simpler and read better
+* Doop-Rspec - it would be nice to have a DSL to drive answering questions.  This could be extended to capybara.
+
+
+## Contributing
+
+1. Fork it ( https://github.com/coder36/doop/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,5 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+

data/app/helpers/doop_helper.rb

@@ -0,0 +1,51 @@
+module DoopHelper
+
+  def info_box &block
+    render "doop/info_box", :content => block
+  end
+
+  def question_visible? path
+    doop = request[:doop]
+    doop.each_visible_question do |root,p|
+      return true if p == path
+    end
+    false
+  end
+
+  def question_form doop, res, &block
+    request[:doop] = doop
+    s = render( "doop/question_form", :content => block, :res => res, :doop => doop )
+    s
+  end
+
+  def question path, opts = {:title => nil, :indent => false}, &block
+    doop = request[:doop]
+    root = doop[path]
+    s = ""
+    if question_visible? path
+      s = render( "doop/question", :content => block, :root => root, :path => path, :answer => root["_answer"], :title => opts[:title], :indent => opts[:indent] )
+    end
+    s
+  end
+
+  def when_answered path, &block
+    doop = request[:doop]
+    block.call if doop.all_nested_answered(path)
+  end
+
+  def error res, id
+    render( "doop/error", :msg => res[id] ) if res[id] != nil
+  end
+
+  def list path_regex, &block
+    doop = request[:doop]
+    l = {}
+    doop.each_question do |root,path|
+      m = path.match( "^#{path_regex}$")
+      l[m[1]] = path if m != nil
+    end
+
+    l.keys.sort.each { |k| block.call( l[k], k.to_i ) }
+  end
+
+end

data/doop.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'doop/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "doop"
+  spec.version       = Doop::VERSION
+  spec.authors       = ["Mark Middleton"]
+  spec.email         = ["markymiddleton@gmail.com"]
+  spec.summary       = %q{Question framework for govuk websites.}
+  spec.description   = %q{A question framework for govuk sites, inspired by the great work GDS have done to standardize the cross government internet presence.}
+  spec.homepage      = "https://github.com/coder36/doop"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib", "app"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+
+  spec.add_runtime_dependency "rails"
+end

data/lib/doop.rb

@@ -0,0 +1,313 @@
+require "doop/version"
+
+require "yaml"
+require 'doop_controller'
+
+module Doop
+
+  class Engine < ::Rails::Engine
+  end
+
+
+  class Doop
+
+    attr_accessor :yaml
+
+    def initialize yaml=nil
+      if yaml != nil
+        @yaml = yaml
+        init
+      end
+      setup_handlers
+    end
+
+    def init
+      @hash = YAML.load( yaml )
+      add_meta_data
+    end
+
+    def set_yaml yaml
+      @yaml = yaml
+    end
+
+    def setup_handlers
+      @on_answer_handlers = {}
+      @on_answer_handlers["default"] = method(:default_on_answer)
+
+      @on_all_nested_answer_handlers = {}
+      @on_all_nested_answer_handlers["default"] = method(:default_on_all_nested_answer)
+    end
+
+    def default_on_all_nested_answer( root, path, context )
+      # do nothing
+    end
+
+    def default_on_answer( root, path, context, answer )
+      self[path + "/_answer"] = context["answer"] if context["answer"] != nil
+      self[path + "/_summary"] = context["summary"] if context["summary"] != nil
+      self[path + "/_answered"] = true
+      self[path + "/_open"] = false
+      {}
+    end
+
+    def dump
+      @hash.to_yaml
+    end
+
+    def [](path)
+      path_elements(path).inject(@hash) { |a,n| a[n] }
+    end
+
+    def []=(path,val)
+      l = path_elements(path)
+      missing = []
+
+      # create missing nodes
+      while self[construct_path(l)] == nil
+        missing << l.pop
+      end
+
+      missing.reverse.each do |elem|
+        self[construct_path(l)][elem] = ""
+        l << elem
+      end
+
+      # set node to value
+      elem = l.pop
+      self[construct_path(l)][elem] = val
+
+    end
+
+    def construct_path(elements)
+       elements.join("/")
+    end
+
+    def path_elements(path)
+      path.split("/").select {|n| !n.empty? }
+    end
+
+    def add(path, hash={})
+      self[path] = hash
+      add_meta_data
+    end
+
+    def remove(path)
+      e = path_elements(path)
+      k = e.pop
+      self[construct_path(e)].delete(k)
+    end
+
+    def move( from, to )
+      q = self[from]
+      remove(from)
+      add(to)
+      self[to] = q
+    end
+
+    def renumber( path )
+      q = self[path]
+      i = 1
+      q.keys.select{|n| (n =~ /^(.*)__(\d)+/) != nil }. sort_by{|s| s.scan(/\d+/).map{|s| s.to_i}}.each do |elem|
+        name = elem.match( /(.*)__\d+/)[1]
+        move( "#{path}/#{elem}", "#{path}/#{name}__#{i}" )
+        i+=1
+      end
+    end
+
+    def each_path_elem(path)
+      p = ""
+      path.split("/").select{|r| !r.empty?}.each do |n|
+        p += "/" + n
+        yield( p )
+      end
+    end
+
+    def each_path_elem_reverse(path)
+      a = []
+      each_path_elem(path) {|n| a << n }
+      a.reverse.each { |n| yield(n) }
+    end
+
+    def each_question(root=@hash, path="", &block) 
+      root.keys.each do |key|
+        next if key.start_with?("_")
+        new_path = path + "/" + key
+        new_root = root[key]
+        block.call( new_root, new_path )
+        each_question( new_root, new_path, &block )
+      end
+    end
+
+    def add_meta_data
+      each_question do |root, path|
+        root["_open"] = false if !root.has_key?("_open")
+        root["_enabled"] = true if !root.has_key?("_enabled")
+        root["_answered"] = false if !root.has_key?("_answered")
+        root["_answer"] = nil if !root.has_key?("_answer")
+      end
+    end
+
+    def ask_next
+
+      q = ""
+      disabled_path = nil
+
+      each_question do |root, path|
+        self[path]["_open"] = false
+        next if disabled_path != nil && path.start_with?(disabled_path)
+        if self[path+"/_enabled"] == false
+          disabled_path = path
+          next
+        end
+
+        q = path if path.start_with?(q) && root["_answered"] == false
+      end
+
+      each_path_elem( q )  { |n| self[n]["_open"] = true } 
+
+    end
+
+    def currently_asked
+      # get the most nested open answer
+      p = ""
+      each_question do |root, path|
+        p = path if path.start_with?(p) && root["_open"] == true
+      end
+      p.empty? ? nil : p
+    end
+
+    def question
+      currently_asked
+    end
+
+    def answer context
+      path = currently_asked
+      root = self[path]
+      root["_answered"] = false 
+      bind_params( root, context )
+      res = get_handler(@on_answer_handlers, path, "_on_answer_handler").call( root, path, context, root["_answer"] )
+      res = {} if ! res.is_a? Hash
+
+      ask_next
+      path = currently_asked
+      return if path == nil
+      each_path_elem_reverse(path) do |p|
+        if all_nested_answered( p ) == true
+          get_handler( @on_all_nested_answer_handlers, p, "_on_all_nested_answered" ).call( self[p], p, context )
+          ask_next
+        end
+      end
+      res
+    end
+
+    def bind_params root, context
+      a = {}
+      context.keys.each do |k|
+        if k == "b_answer"
+          root["_answer"] = context[k]
+        else
+          a[k[2..-1]] = context[k] if k.to_s.start_with?("b_")
+        end
+      end
+
+      root["_answer"] = a if !a.empty?
+    end
+
+
+    def get_handler handlers, path, handler_elem
+      handler = self[path][handler_elem]
+      if handler != nil
+        block = handlers[handler]
+      else
+        keys = handlers.keys.select { |k| path.match( "^#{k}$" ) != nil }
+        block = keys.empty? ? handlers["default"] : handlers[keys[0]]
+      end
+      block
+    end
+
+    def all_nested_answered path
+      return true if path==nil
+      each_question( self[path], path ) do |root,path| 
+        if root["_enabled"] 
+          return false if root["_answered"] == false || root["_open"] == true
+        end
+      end
+      true
+    end
+
+    def disable path
+      self[path + "/_enabled"] = false
+      ask_next
+    end
+
+    def enable path, enable = true
+      self[path + "/_enabled"] = enable
+      ask_next
+    end
+
+    def change path
+      each_path_elem_reverse(currently_asked) do |p|
+        self[p + "/_open"] = false
+      end
+
+      # open all parent questions
+      each_path_elem_reverse(path) do |p|
+        self[p + "/_open"] = true
+      end
+    end
+
+    def on_answer(path, &block)
+      @on_answer_handlers[path] = block
+    end
+
+    def on_all_nested_answer(path, &block)
+      @on_all_nested_answer_handlers[path] = block
+    end
+
+    def answer_path path, a, summary = nil
+      self[path]["_answer"] = a
+      self[path]["_answered"] = true
+      self[path]["_summary"] = summary == nil ? a : summary
+      {}
+    end
+
+    def answer_with root, hash
+      root["_answered"] = true
+      hash.keys.each { |k| root[k] = hash[k] }
+    end
+
+    def unanswer_path path
+      self[path]["_answered"] = false
+      {}
+    end
+
+
+    def each_visible_question 
+      open_paths = []
+      each_question do |root,path|
+        if root["_enabled"]
+          open_paths << path if root["_open"]
+          is_child = open_paths.select { |n| path.start_with?(n) && n.count('/')+1 == path.count('/') }.count > 0
+          yield(root, path) if is_child || root["_open"]
+        end
+      end
+    end
+
+    def all_answered path
+      each_question(self[path], path) do |root, p|
+        return false if root["_answered"] == false && root["_enabled"]
+      end
+      true
+    end
+
+
+    def each_question_with_regex_filter regex
+      each_question do |question,path|
+        yield(question, path) if path.match( regex ) != nil
+      end
+    end
+
+
+  end
+
+end