gather_content-api 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bc4fa4c68863fe799d804ff07fe209eff1e8893b
-  data.tar.gz: fe246d59f62d044e5fb78fc75204490dd8596dcc
+  metadata.gz: b8eb9792ba4691f554b35b13a8bbc8826a46558e
+  data.tar.gz: bdc42f9dd191a88289976ba3d4aa0c03e6d29f7a
 SHA512:
-  metadata.gz: 1163d48c41a4648d40550e237b4d5f8a58e9b3e63ccf8a526880e1bbf8c1c1cd55588937f28975b947eff64751bd25cfab03e6f13456ac84dd5702e0bb8b0b17
-  data.tar.gz: affabeb1a6be1740294f12aad415688305dbc08a0f46949a8d60be34ac719bd58647964817d3aa9cbc0c5ff2778bb9a472d452b354af00e4fe0ff608e4680b07
+  metadata.gz: f34fa4a9124bae94dfc285dc74debfa767abfa5e222f02b21b21faa5122a878e0cd3fd192e6fec0a0ec8f68cf8c0d89372420158bab4bbe9c4e07e8d7c8f2f29
+  data.tar.gz: 4306b9229d0828ba7b8aafe78c3647c3aeb7fb44b263f3056f65c6cf70fb396eb8ed091ed94c85eb2a2cf4a5693c9e32ec5e2aeab56e5a76f0aeb8720db7bb24

data/MIT-LICENSE

@@ -0,0 +1,7 @@
+Copyright 2018 NYU Division of Libraries
+
+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

@@ -1,7 +1,6 @@
 # GatherContent Ruby Client
 
 [![Build Status](https://travis-ci.org/NYULibraries/gather_content-api.svg?branch=master)](https://travis-ci.org/NYULibraries/gather_content-api)
-[![Dependency Status](https://gemnasium.com/badges/github.com/NYULibraries/gather_content-api.svg)](https://gemnasium.com/github.com/NYULibraries/gather_content-api)
 [![Maintainability](https://api.codeclimate.com/v1/badges/ace52f297d3f4160799d/maintainability)](https://codeclimate.com/github/NYULibraries/gather_content-api/maintainability)
 [![Coverage Status](https://coveralls.io/repos/github/NYULibraries/gather_content-api/badge.svg?branch=master)](https://coveralls.io/github/NYULibraries/gather_content-api?branch=master)
 
@@ -221,7 +220,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 +232,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,7 +269,7 @@ 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'
@@ -277,22 +277,22 @@ 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 +393,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
+```

data/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

data/lib/gather_content.rb

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

data/lib/gather_content/api.rb

@@ -1,19 +1,20 @@
+require 'gather_content/api/config'
+require 'gather_content/api/base'
+require 'gather_content/api/me'
+require 'gather_content/api/accounts'
+require 'gather_content/api/account'
+require 'gather_content/api/projects'
+require 'gather_content/api/project'
+require 'gather_content/api/items'
+require 'gather_content/api/item'
+require 'gather_content/api/statuses'
+require 'gather_content/api/status'
+require 'gather_content/api/files'
+require 'gather_content/api/file'
+require 'gather_content/api/templates'
+require 'gather_content/api/template'
+
 module GatherContent
   module Api
-    autoload :Config, 'gather_content/api/config'
-    autoload :Base, 'gather_content/api/base'
-    autoload :Me, 'gather_content/api/me'
-    autoload :Accounts, 'gather_content/api/accounts'
-    autoload :Account, 'gather_content/api/account'
-    autoload :Projects, 'gather_content/api/projects'
-    autoload :Project, 'gather_content/api/project'
-    autoload :Items, 'gather_content/api/items'
-    autoload :Item, 'gather_content/api/item'
-    autoload :Statuses, 'gather_content/api/statuses'
-    autoload :Status, 'gather_content/api/status'
-    autoload :Files, 'gather_content/api/files'
-    autoload :File, 'gather_content/api/file'
-    autoload :Templates, 'gather_content/api/templates'
-    autoload :Template, 'gather_content/api/template'
   end
 end

data/lib/gather_content/config.rb

@@ -0,0 +1,9 @@
+require 'gather_content/config/builder'
+require 'gather_content/config/tabs'
+require 'gather_content/config/tab'
+require 'gather_content/config/elements'
+
+module GatherContent
+  module Config
+  end
+end

data/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 = GatherContent::Config::Tabs.new
+      end
+
+      def self.build(&block)
+        instance = self.new
+        dsl = GatherContent::DSL::Config.new(instance)
+        dsl.instance_eval(&block)
+        instance.tabs
+      end
+    end
+  end
+end

data/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

data/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

data/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

data/lib/gather_content/config/elements/choice_radio.rb

@@ -0,0 +1,62 @@
+require 'gather_content/config/elements/base'
+require 'gather_content/config/elements/option'
+require 'gather_content/config/elements/other_option'
+
+module GatherContent
+  module Config
+    module Element
+      class ChoiceRadio < Base
+        attr_accessor :other_option, :options
+
+        def initialize(name = "", required = false, label = "", microcopy = "", other_option = false)
+          super(name, required, label, microcopy)
+          @other_option = other_option
+          @options = []
+        end
+
+        def serialize(_options = nil)
+          raise ArgumentError, "You need to supply at least one option" if options.size == 0
+
+          if other_option
+            verify_other_option_types!(options)
+          else
+            verify_option_types!(options)
+          end
+
+          verify_options!(options)
+
+          super.merge({
+            type: 'choice_radio',
+            other_option: !!other_option,
+            options: options.map{ |el| el.serialize(_options) }
+          })
+        end
+
+        def to_json(options = nil)
+          serialize.to_json(options)
+        end
+
+
+      private
+        def verify_other_option_types!(options)
+          cleaned = options.select{ |opt| opt.is_a?(GatherContent::Config::Element::Option) }
+          last = cleaned.pop
+
+          raise ArgumentError, "Options can only be GatherContent::Config::Element::Option" if cleaned.size == 0
+          raise ArgumentError, "The last option must be a GatherContent::Config::Element::OptionOther" unless last.instance_of?(GatherContent::Config::Element::OtherOption)
+        end
+
+        def verify_option_types!(options)
+          cleaned = options.select{ |opt| opt.instance_of?(GatherContent::Config::Element::Option) }
+
+          raise ArgumentError, "Options can only be GatherContent::Config::Element::Option" if cleaned.size == 0
+        end
+
+        def verify_options!(options)
+          selected = options.select{ |opt| opt.selected }
+          raise ArgumentError, "You can't select more than one ChoiceRadio Option" if selected.size > 1
+        end
+      end
+    end
+  end
+end