ask_awesomely 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fef8189f02630e738799f66750c04c1735839c6a
-  data.tar.gz: 28f428f626cf0297cd6544a946429716b47f353a
+  metadata.gz: 53ff9446c8f755df7d9ac559825c389a44d4dab1
+  data.tar.gz: 0a567bbcf6b84fc08e3827bbfd1fe2e4d4a09350
 SHA512:
-  metadata.gz: 6b3cdd6d5b76a9e02d82e11380b3ff8cf1a63be9f23257092f9ad8e7be736caea26ad17c492f233e8ffa1bc4387363b600370445619b9b69e5f78cb52a1df6b8
-  data.tar.gz: b7dfdc73f7e60e9c4225bea064a70b5a9bc6faa299c233ec6b04fd4b7398b8818211e2e2041a531bf52b6f2bfc1ae041e76128091287700735b0700d5579fae9
+  metadata.gz: 7e5d7e5062b8dd82613c64ff68665fccf1cfc3156c47db9867d431214eab559d83e82fa22d2c799781223bb490fb2f78ab3e962cbd8a990a5405c37fe91dde7e
+  data.tar.gz: f1aea9894e9455ea590faeded81547f9d9891e63bfe5db130c0646afae4afa6d1445d176ffaa535d08501fec10f21cf47499c255ac4a3d38cf0e8fd88d35e4ec

data/.codeclimate.yml

@@ -0,0 +1,6 @@
+engines:
+  rubocop:
+    enabled: true
+    checks:
+      Rubocop/Style/StringLiterals:
+        enabled: false

data/README.md

@@ -3,6 +3,7 @@
 Build Typeforms awesomely. In Ruby.
 
 [![Gem Version](https://badge.fury.io/rb/ask_awesomely.svg)](http://badge.fury.io/rb/ask_awesomely) [![Build Status](https://travis-ci.org/leemachin/ask_awesomely.svg?branch=master)](https://travis-ci.org/leemachin/ask_awesomely)
+[![Code Climate](https://codeclimate.com/github/leemachin/ask_awesomely/badges/gpa.svg)](https://codeclimate.com/github/leemachin/ask_awesomely)
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
@@ -29,6 +30,8 @@ Build Typeforms awesomely. In Ruby.
   - [Email](#email)
   - [Website](#website)
   - [Legal](#legal)
+- [Logic Jumps](#logic-jumps)
+- [Conditional Fields](#conditional-fields)
 - [Common Customisations](#common-customisations)
 - [Passing Context](#passing-context)
 - [Rendering the Typeform](#rendering-the-typeform)
@@ -349,6 +352,81 @@ field :legal
 end
 ```
 
+## Logic Jumps
+
+A logic jump allows you to change the next questions you ask based on the answer of a previous question. For example, you could have a `yes_no` field that shows one question if the answer is 'yes', and a different question if the answer is 'no'. At the time of writing this is the only supported behaviour for logic jumps.
+
+Check out the [documentation on Logic Jumps](http://docs.typeform.io/docs/logic-jumps) to understand more about how they work.
+
+In order to set one up, you need to give the relevant fields a reference. In this case, when the user answers 'no' to the first question about their age, it should immediately go to the next question like normal. If they answer 'yes', though, the form should ask them another question to confirm they're not lying about being grown up.
+
+```ruby
+field :yes_no do
+  ask "Are you over 18?"
+  required
+
+  ref :is_over_18
+end
+
+field :statement do
+  say "You're too young to continue"
+end
+
+field :yes_no do
+  ask "Are you *sure* you're over 18?"
+  required
+
+  ref :is_really_over_18?
+end
+```
+
+Notice how the two `yes_no` fields have a reference. These are what we use to define the logic jump:
+
+```ruby
+jump from: :is_over_18, to: :is_really_over_18?, if_answer: true
+
+```
+
+If you need to change the structure of a Typeform based on your own data and not that supplied in an answer, then continue on to [**Conditional Fields**](#conditional-fields).
+
+## Conditional Fields
+
+Consider a form where you ask for the user's email address:
+
+```ruby
+class EmailTypeform
+  include AskAwesomely::DSL
+
+  field :email do
+    ask -> (user) { "Hey #{user.name}, what is your email address?" }
+    required
+  end
+
+  # ... more fields
+end
+```
+
+What if you already have the user's email? It makes no sense to repeatedly ask for it, does it? You can tell *Ask Awesomely* to not include this field if a certain condition is met; in this case the user having an email address already.
+
+```ruby
+class EmailTypeform
+  include AskAwesomely::DSL
+
+  field :email do
+    ask -> (user) { "Hey #{user.name}, what is your email address?" }
+    required
+
+    skip if: -> (user) { !user.email.nil? }
+
+    # alternatively
+    skip unless: -> (user) { user.email.nil? }
+  end
+
+  # ... more fields
+end
+```
+
+Note that this is not a feature of the Typeform I/O API. These conditions are evaluated at **build time** and not when the form is rendered (as with logic jumps), which means that the field won't be included in the final Typeform at all.
 
 ## Common Customisations
 
@@ -427,7 +505,7 @@ end
 
 You can also embed a form straight away if you prefer. `AskAwesomely` generates the correct embed code for you, with the correct URL and Typeform title. The style can be customised with CSS, and you can also tweak some of the output.
 
-To see what each embedding option looks like, check out the [`Embedding Modes`](http://docs.typeform.io/docs/embedding-introduction) documentation at Typeform I/O. It has pictures and everything.
+To see what each embedding option looks like, check out the [**Embedding Modes**](http://docs.typeform.io/docs/embedding-introduction) documentation at Typeform I/O. It has pictures and everything.
 
 Assuming you have built a Typeform as in the other examples, rendering the embed code is simple:
 
@@ -478,7 +556,7 @@ class UserTypeform
 end
 ```
 
-`AskAwesomely` will warn you if you don't configure this, as Typeform I/O doesn't store the responses for you and they'll be lost in the either.
+*Ask Awesomely* will warn you if you don't configure this, as Typeform I/O doesn't store the responses for you and they'll be lost in the ether.
 
 Check the documentation on [results and webhooks](http://docs.typeform.io/docs/results-introduction) to find out more about how this works, what happens when a webhook submission request fails, and how you can deduplicate your submissions.
 

data/lib/ask_awesomely/choice.rb

@@ -1,21 +1,19 @@
 module AskAwesomely
   class Choice
 
-    attr_reader :state, :picture
+    include JsonBuilder
 
-    def initialize(label:, picture: nil)
-      @state = OpenStruct.new(label: label.to_s)
-      @picture = picture && Picture.new(picture)
-    end
+    attr_reader :state
 
-    def build_json(context = nil)
-      @state.image_id = picture && picture.typeform_id
+    def initialize(label:, picture: nil)
+      @state = OpenStruct.new(
+        label: label.to_s,
+      )
 
-      state.to_h.reduce({}) do |json, (k, v)|
-        json[k] = v.respond_to?(:call) ? v.call(context) : v
-        json
+      if picture 
+        @state.image_id = proc { Picture.new(picture).typeform_id }
       end
     end
-      
+
   end
 end

data/lib/ask_awesomely/dsl.rb

@@ -3,6 +3,7 @@ module AskAwesomely
 
     def self.included(recv)
       recv.extend(ClassMethods)
+      recv.include(JsonBuilder)
     end
 
     module ClassMethods
@@ -35,6 +36,11 @@ module AskAwesomely
         _state.fields << Field::Field.of_type(type, &block)
       end
 
+      def jump(conditions)
+        _state.jumps ||= []
+        _state.jumps << LogicJump.new(conditions)
+      end
+
       def send_responses_to(url)
         unless url =~ /\A#{URI::regexp(['http', 'https'])}\z/
           raise AskAwesomely::InvalidUrlError, "you must use a valid URL for webhooks, e.g https://example.com/webhook"
@@ -44,35 +50,21 @@ module AskAwesomely
       end
     end
 
-    attr_reader :context, :json
-
-    def build_json
-      warn_if_no_webhook_set!
-      
-      state.to_h.reduce({}) do |json, (k, v)|
-        json[k] = case
-        when v.respond_to?(:to_ary) then v.map {|f| f.respond_to?(:build_json) ? f.build_json(context) : f }
-        when v.respond_to?(:call) then v.call(context)
-        when v.respond_to?(:build_json) then v.build_json(context)
-        else
-          v
-        end
+    attr_reader :context, :json, :state
 
-        json
-      end.to_json
+    def to_json
+      warn_if_no_webhook_set
+      build_json(context).to_json
     end
 
     private
     
     def initialize(context = nil)
       @context = context
+      @state = self.class._state
     end
 
-    def state
-      self.class._state
-    end
-
-    def warn_if_no_webhook_set!
+    def warn_if_no_webhook_set
       return if state.webhook_submit_url
       AskAwesomely.configuration.logger.warn(<<-STR.gsub(/^\s*/, ''))
         Your Typeform has no webhook URL! The responses to this form **will NOT** be saved!

data/lib/ask_awesomely/field/field.rb

@@ -1,6 +1,8 @@
 module AskAwesomely
   class Field::Field
 
+    prepend JsonBuilder
+
     VALID_FIELD_TYPES = %i(
       short_text 
       long_text 
@@ -61,18 +63,18 @@ module AskAwesomely
       @state.tags = tags
     end
     
-    def build_json(context = nil)
-      state.to_h.reduce({}) do |json, (k, v)|
-        json[k] = case 
-        when v.respond_to?(:to_ary) then v.map {|f| f.respond_to?(:build_json) ? f.build_json(context) : f }
-        when v.respond_to?(:call) then v.call(context)
-        when v.respond_to?(:build_json) then v.build_json(context)
-        else
-          v
-        end
-        json
+    def ref(name)
+      @state.ref = name.to_s
+    end
+
+    def skip(condition)
+      if cond_if = condition[:if]
+        @state.skip = -> (context) { cond_if.call(context) == true }
+      end
+
+      if cond_unless = condition[:unless]
+        @state.skip = -> (context) { cond_unless.call(context) != true }
       end
     end
-    
   end
 end

data/lib/ask_awesomely/json_builder.rb

@@ -0,0 +1,27 @@
+module AskAwesomely
+  module JsonBuilder
+    
+    def build_json(context = nil)
+      super if defined?(super) 
+
+      state.to_h.reduce({}) do |json, (k, v)|
+
+        next if k == :skip && v.call(context) == true
+        
+        json[k] = case 
+                  when v.respond_to?(:to_ary)
+                    v.map {|f| f.respond_to?(:build_json) ? f.build_json(context) : f }
+                     .compact
+                  when v.respond_to?(:call)
+                    v.call(context)
+                  when v.respond_to?(:build_json)
+                    v.build_json(context)
+                  else
+                    v
+                  end
+        json
+      end
+    end
+    
+  end
+end

data/lib/ask_awesomely/logic_jump.rb

@@ -0,0 +1,17 @@
+module AskAwesomely
+  class LogicJump
+
+    include JsonBuilder
+
+    attr_reader :state
+
+    def initialize(args)
+      @state = OpenStruct.new(
+        to: args[:to],
+        from: args[:from],
+        if_answer: args[:if_answer]
+      )
+    end
+    
+  end
+end

data/lib/ask_awesomely/typeform.rb

@@ -33,7 +33,7 @@ module AskAwesomely
     end
 
     def to_json
-      @structure.build_json
+      @structure.to_json
     end
 
   end

data/lib/ask_awesomely/version.rb

@@ -1,3 +1,3 @@
 module AskAwesomely
-  VERSION = "0.1.5"
+  VERSION = "0.1.6"
 end

data/lib/ask_awesomely.rb

@@ -6,6 +6,7 @@ require "aws-sdk"
 require "typhoeus"
 
 require "ask_awesomely/version"
+require "ask_awesomely/json_builder"
 require "ask_awesomely/configuration"
 require "ask_awesomely/dsl"
 require "ask_awesomely/field"
@@ -15,6 +16,7 @@ require "ask_awesomely/s3"
 require "ask_awesomely/api_client"
 require "ask_awesomely/typeform"
 require "ask_awesomely/embeddable"
+require "ask_awesomely/logic_jump"
 
 module AskAwesomely
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ask_awesomely
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Lee Machin
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-10-07 00:00:00.000000000 Z
+date: 2015-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk
@@ -115,6 +115,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".codeclimate.yml"
 - ".gitignore"
 - ".rspec"
 - ".ruby-version"
@@ -151,6 +152,8 @@ files:
 - lib/ask_awesomely/field/statement.rb
 - lib/ask_awesomely/field/website.rb
 - lib/ask_awesomely/field/yes_no.rb
+- lib/ask_awesomely/json_builder.rb
+- lib/ask_awesomely/logic_jump.rb
 - lib/ask_awesomely/picture.rb
 - lib/ask_awesomely/s3.rb
 - lib/ask_awesomely/typeform.rb