[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://badge.fury.io/rb/wcc-contentful) [![CircleCI](https://circleci.com/gh/watermarkchurch/wcc-contentful.svg?style=svg)](https://circleci.com/gh/watermarkchurch/wcc-contentful) [![Coverage Status](https://coveralls.io/repos/github/watermarkchurch/wcc-contentful/badge.svg?branch=master)](https://coveralls.io/github/watermarkchurch/wcc-contentful?branch=master) Full documentation: https://www.rubydoc.info/github/watermarkchurch/wcc-contentful # WCC::Contentful ## Installation Add this line to your application's Gemfile: ```ruby gem 'wcc-contentful', require: 'wcc/contentful/rails' ``` And then execute: $ bundle Or install it yourself as: $ gem install wcc-contentful ## Configure ```ruby WCC::Contentful.configure do |config| config.access_token = config.space = end WCC::Contentful.init! ``` ## Usage ### WCC::Contentful::Model API The WCC::Contentful::Model API exposes Contentful data as a set of dynamically generated Ruby objects. These objects are based on the content types in your Contentful space. All these objects are generated by WCC::Contentful.init! The following examples show how to use this API to find entries of the `page` content type: ```ruby # Find objects by id WCC::Contentful::Model::Page.find('1E2ucWSdacxxf233sfa3') # => # # Find objects by field WCC::Contentful::Model::Page.find_by(slug: '/some-slug') # => # # Use operators to filter by a field # must use full notation for sys attributes (except ID) WCC::Contentful::Model::Page.find_all('sys.created_at' => { lte: Date.today }) # => [#, ... ] # Nest queries to mimick joins WCC::Contentful::Model::Page.find_by(subpages: { slug: '/some-slug' }) # => # # Pass the preview flag to use the preview client (must have set preview_token config param) preview_redirect = WCC::Contentful::Model::Redirect.find_by({ slug: 'draft-redirect' }, preview: true) # => # preview_redirect_object.href # => 'http://www.somesite.com/slug-for-redirect' ``` See the {WCC::Contentful::Model} documentation for more details. ### Store API The Store layer is used by the Model API to access Contentful data in a raw form. The Store layer returns entries as hashes parsed from JSON, conforming to the object structure returned from the Contentful CDN. The following examples show how to use the Store API to retrieve raw data from the store: ```ruby store = WCC::Contentful::Services.instance.store # => # {"sys"=> # ... # "fields"=> # ...} store.find_by(content_type: 'page', filter: { slug: '/some-slug' }) # => {"sys"=> # ... # "fields"=> # ...} query = store.find_all(content_type: 'page').eq('group', 'some-group') # => # {"sys"=> # ... # "fields"=> # ...} query.result # => # query.result.force # => [{"sys"=> ...}, {"sys"=> ...}, ...] ``` See the {WCC::Contentful::Store} documentation for more details. ### Direct CDN API (SimpleClient) The SimpleClient is the bottom layer, and is used to get raw data directly from the Contentful CDN. It handles response parsing and paging, but does not resolve links or transform the result into a Model class. The following examples show how to use the SimpleClient to retrieve data directly from the Contentful CDN: ```ruby client = WCC::Contentful::Services.instance.client # => # # "{\n \"sys\": {\n ... response.raw # => {"sys"=> # ... # "fields"=> # ...} client.asset('5FsqsbMECsM62e04U8sY4Y').raw # => {"sys"=> # ... # "fields"=> # ...} response = client.entries('fields.group' => 'some-group', 'limit' => 5) # => # 99 response.first # => {"sys"=> # ... # "fields"=> # ...} response.items => # response.items.count # Careful! This evaluates the lazy iterator and gets all pages # => 99 response.includes # => {"4xNnFJ77egkSMEogE2yISa"=> # {"sys"=> ...} # "6Fwukxxkxa6qQCC04WCaqg"=> # {"sys"=> ...} # ...} ``` The client handles Paging automatically within the lazy iterator returned by #items. This lazy iterator does not respect the `limit` param - that param is only passed through to the API to set the page size. Entries included via the `include` parameter are made available on the #includes field. This is a hash of ` => ` and makes it easy to grab links. This hash is added to lazily as you enumerate the pages. See the {WCC::Contentful::SimpleClient} documentation for more details. ### Accessing the APIs within application code The Model API is best exposed by defining your own model classes in the `app/models` directory which inherit from the WCC::Contentful models. ```ruby # app/models/page.rb class Page < WCC::Contentful::Model::Page # You can add additional methods here end # app/controllers/pages_controller.rb class PagesController < ApplicationController def show @page = Page.find_by(slug: params[:slug]) raise Exceptions::PageNotFoundError, params[:slug] unless @page end end ``` The {WCC::Contentful::Services} singleton gives access to the other configured services. You can also include the {WCC::Contentful::ServiceAccessors} concern to define these services as attributes in a class. ```ruby class MyJob < ApplicationJob include WCC::Contentful::ServiceAccessors def perform Page.find(...) store.find(...) client.entries(...) end end ``` ## Test Helpers To use the test helpers, include the following in your rails_helper.rb: ```ruby require 'wcc/contentful/rspec' ``` This adds the following helpers to all your specs: ```ruby ## # Builds a in-memory instance of the Contentful model for the given content_type. # All attributes that are known to be required fields on the content type # will return a default value based on the field type. instance = contentful_create('my-content-type', my_field: 'some-value') # => # instance.my_field # => "some-value" instance.other_required_field # => "default-value" instance.other_optional_field # => nil instance.not_a_field # NoMethodError: undefined method `not_a_field' for # ## # Builds a rspec double of the Contentful model for the given content_type. # All attributes that are known to be required fields on the content type # will return a default value based on the field type. dbl = contentful_double('my-content-type', my_field: 'other-value') # => # dbl.my_field # => "other-value" dbl.not_a_field # => # received unexpected message :not_a_field with (no args) ## # Builds out a fake Contentful entry for the given content type, and then # stubs the Model API to return that content type for `.find` and `.find_by` # query methods. stubbed = contentful_stub('my-content-type', id: '1234', my_field: 'test') WCC::Contentful::Model.find('1234') == stubbed # => true MyContentType.find('1234') == stubbed # => true MyContentType.find_by(my_field: 'test') == stubbed # => true ``` ## Development After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org). ## Contributing Bug reports and pull requests are welcome on GitHub at https://github.com/watermarkchurch/wcc-contentful. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. ## License The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT). ## Code of Conduct Everyone interacting in the WCC::Contentful project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/watermarkchurch/wcc-contentful/blob/master/CODE_OF_CONDUCT.md).