Merge 30c3fae into 06f5fb5

README.md

@@ -221,7 +221,8 @@ item["name"]
 
 Creates a new Item within a particular Project.
 
-The config object (if supplied) should be a Ruby Hash representation of the [configuration](https://docs.gathercontent.com/reference#the-config-field).
+Use the handy [DSL](#config-dsl) to generate a [config field](https://docs.gathercontent.com/reference#the-config-field).
+
 
 If successful, will return the newly created item.
 
@@ -232,22 +233,22 @@ require 'gather_content'
 
 project_id = 123456
 
-config = [{
-  "label": "Content",
-  "name": "tab1",
-  "hidden": false,
-  "elements": [{
-      "type": "text",
-      "name": "el1",
-      "required": false,
-      "label": "Blog post",
-      "value": "Hello world",
-      "microcopy": "",
-      "limit_type": "words",
-      "limit": 1000,
-      "plain_text": false
-  }]
-}]
+config = GatherContent::Config::Builder.build do
+  label "Content"
+  name "tab1"
+  hidden false
+
+  text do
+    name "el1"
+    required false
+    label "Blog post"
+    value "Hello world"
+    microcopy ""
+    limit_type :words
+    limit 1000
+    plain_text false
+  end
+end
 
 begin
   i = GatherContent::Api::Items.new(project_id)
@@ -269,30 +270,30 @@ end
 
 Saves an Item with the newly updated data. It expects a valid configuration structure, otherwise the save request will not be accepted by the API.
 
-The config object should be a Ruby Hash representation of the [configuration](https://docs.gathercontent.com/reference#the-config-field).
+Use the handy [DSL](#config-dsl) to generate a [config field](https://docs.gathercontent.com/reference#the-config-field).
 
 ```ruby
 require 'gather_content'
 
 item_id = 123456
 item = GatherContent::Api::Item.new(item_id)
 
-config = [{
-  "label": "Content",
-  "name": "tab1",
-  "hidden": false,
-  "elements": [{
-      "type": "text",
-      "name": "el1",
-      "required": false,
-      "label": "Blog post",
-      "value": "Hello world",
-      "microcopy": "",
-      "limit_type": "words",
-      "limit": 1000,
-      "plain_text": false
-  }]
-}]
+config = GatherContent::Config::Builder.build do
+  label "Content"
+  name "tab1"
+  hidden false
+
+  text do
+    name "el1"
+    required false
+    label "Blog post"
+    value "Hello world"
+    microcopy ""
+    limit_type :words
+    limit 1000
+    plain_text false
+  end
+end
 
 begin
   item.save(config)
@@ -393,3 +394,129 @@ template["id"]
 template["name"]
 => "Blog theme"
 ```
+
+## Config DSL
+
+This gem also includes a handy DSL to make creating configurations simple.
+
+### Getting started
+
+Every configuration object starts with some tabs (You can define as many as you like)
+
+```ruby
+config = GatherContent::Config::Builder.build do
+  tab do
+    name "website"                        # Required. Must be unique.
+    label "Website"                       # Required
+    hidden false
+  end
+
+  tab do
+    name "email"
+    label "Email"
+    hidden: false
+  end
+end
+```
+
+### Tabs
+
+Tabs can have sections, text, files, radio buttons and checkboxes
+
+```ruby
+config = GatherContent::Config::Builder.build do
+  tab do
+    name "website"
+    label "Website"
+    hidden false
+
+    section do
+      name "main"                       # Required. Must be unique.
+      label "Main Copy"                 # Required
+      subtitle ""
+    end
+
+    text do
+      name "title"                      # Required. Must be unique.
+      label "Title"                     # Required
+      required true
+      value ""
+      microcopy "The title of the page"
+      limit_type :words                 # Can be :words or :chars
+      limit 100                         # Must be positive
+      plain_text false
+    end
+
+    files do
+      name: "images"                    # Required. Must be unique.
+      label "Images"                    # Required
+      required false
+      microcopy "Upload any images referenced in the post"
+    end
+
+    choice_radio do
+      name "post_type"
+      label "Post type"
+      required true
+      microcopy "What type of post is this?"
+      option do
+        name "regular"
+        label "Regular page"
+        selected true
+      end
+      option do
+        name "blog"
+        label "Blog Post"
+        selected false
+      end
+    end
+
+    choice_checkbox do
+      name "notify"
+      label "Notify on publish"
+      required true
+      microcopy "Who needs to be notified when this post is published?"
+
+      # This DSL is just regular Ruby, so you can do things like...
+      [ 'joe@example.com', 'kathy@example.com', 'sam@example.com' ].each_with_index do |email, index|
+        option do
+          name "email_#{index}"
+          label email
+          selected false
+        end
+      end
+    end
+  end
+end
+```
+
+### Radio choices with an "other" option
+
+Use other_option to define a user definable "other" option. This block MUST be the last one in the set.
+
+If the option is selected, you need to supply a value.
+
+```ruby
+choice_radio do
+  name "post_type"
+  label "Post type"
+  required false
+  microcopy "What type of post is this?"
+  option do
+    name "regular"
+    label "Regular page"
+    selected false  # Only one radio option can be selected at a time.
+  end
+  option do
+    name "blog"
+    label "Blog Post"
+    selected false
+  end
+  other_option do
+    name "other"
+    label "Other"
+    selected true
+    value "Push notification"   # If this option is selected, you need to supply a value.
+  end
+end
+```

gather_content-api.gemspec

@@ -19,7 +19,7 @@ Gem::Specification.new do |gem|
   gem.licenses      = ['MIT']
 
   gem.required_ruby_version = '>= 1.9.3'
-  gem.add_dependency 'rake', '~> 10'
+  gem.add_development_dependency 'rake', '~> 10'
   gem.add_dependency 'rest-client', '~> 2'
   gem.add_dependency 'faraday', '~> 0'
 end

lib/gather_content.rb

@@ -2,4 +2,6 @@
 require 'faraday'
 require 'gather_content/version'
 require 'gather_content/api'
+require 'gather_content/config'
+require 'gather_content/dsl'
 require 'gather_content/error'

lib/gather_content/config.rb

@@ -0,0 +1,7 @@
+module GatherContent
+  module Config
+    autoload :Builder, 'gather_content/config/builder'
+    autoload :Tab, 'gather_content/config/tab'
+    autoload :Elements, 'gather_content/config/elements'
+  end
+end

lib/gather_content/config/builder.rb

@@ -0,0 +1,20 @@
+require 'gather_content/dsl/config'
+
+module GatherContent
+  module Config
+    class Builder
+      attr_accessor :tabs
+
+      def initialize
+        self.tabs = []
+      end
+
+      def self.build(&block)
+        instance = self.new
+        dsl = GatherContent::DSL::Config.new(instance)
+        dsl.instance_eval(&block)
+        instance.tabs
+      end
+    end
+  end
+end

lib/gather_content/config/elements.rb

@@ -0,0 +1,15 @@
+module GatherContent
+  module Config
+    module Elements
+      autoload :Base, 'gather_content/config/elements/base'
+      autoload :ChoiceCheckbox, 'gather_content/config/elements/choice_checkbox'
+      autoload :ChoiceRadio, 'gather_content/config/elements/choice_radio'
+      autoload :Files, 'gather_content/config/elements/files'
+      autoload :Option, 'gather_content/config/elements/option'
+      autoload :OtherOption, 'gather_content/config/elements/other_option'
+      autoload :Section, 'gather_content/config/elements/section'
+      autoload :Tab, 'gather_content/config/elements/tab'
+      autoload :Text, 'gather_content/config/elements/text'
+    end
+  end
+end

lib/gather_content/config/elements/base.rb

@@ -0,0 +1,32 @@
+module GatherContent
+  module Config
+    module Element
+      class Base
+        attr_accessor :name, :required, :label, :microcopy
+
+        def initialize(name = nil, required = nil, label = nil, microcopy = nil)
+          @name = name
+          @required = required
+          @label = label
+          @microcopy = microcopy
+        end
+
+        def serialize(options = nil)
+          raise ArgumentError, "name is required" unless name.present?
+          raise ArgumentError, "label is required" unless label.present?
+
+          {
+            name: name,
+            required: !!required,
+            label: label,
+            microcopy: microcopy
+          }
+        end
+
+        def to_json(options = nil)
+          serialize.to_json(options)
+        end
+      end
+    end
+  end
+end

lib/gather_content/config/elements/choice_checkbox.rb

@@ -0,0 +1,32 @@
+require 'gather_content/config/elements/base'
+require 'gather_content/config/elements/option'
+
+module GatherContent
+  module Config
+    module Element
+      class ChoiceCheckbox < Base
+        attr_accessor :options
+
+        def initialize(name = "", required = false, label = "", microcopy = "")
+          super(name, required, label, microcopy)
+          @options = []
+        end
+
+        def serialize(_options = nil)
+          cleaned = options.select{ |opt| opt.instance_of?(GatherContent::Config::Element::Option) }
+          raise ArgumentError, "You need to supply at least one option" if options.size == 0
+          raise ArgumentError, "Options can only be GatherContent::Config::Element::Option" if cleaned.size == 0
+
+          super.merge({
+            type: 'choice_checkbox',
+            options: options.map{ |el| el.serialize(_options) }
+          })
+        end
+
+        def to_json
+          serialize.to_json
+        end
+      end
+    end
+  end
+end