README.md in wcc-contentful-0.4.0.pre.rc vs README.md in wcc-contentful-1.0.0.pre.rc1
- old
+ new
@@ -1,10 +1,10 @@
-[](https://badge.fury.io/rb/wcc-contentful)
-[](https://circleci.com/gh/watermarkchurch/wcc-contentful)
+[](https://rubygems.org/gems/wcc-contentful)
+[](https://travis-ci.org/watermarkchurch/wcc-contentful)
[](https://coveralls.io/github/watermarkchurch/wcc-contentful?branch=master)
-Full documentation: https://www.rubydoc.info/github/watermarkchurch/wcc-contentful
+Full documentation: https://www.rubydoc.info/gems/wcc-contentful
# WCC::Contentful
## Installation
@@ -12,36 +12,48 @@
```ruby
gem 'wcc-contentful', require: 'wcc/contentful/rails'
```
-And then execute:
+If you're not using rails, exclude the `require:` parameter.
- $ bundle
+```ruby
+gem 'wcc-contentful'
+```
+And then execute:
+```
+ $ bundle
+```
Or install it yourself as:
-
+```
$ gem install wcc-contentful
+```
## Configure
+Put this in an initializer:
```ruby
+# config/initializers/wcc_contentful.rb
WCC::Contentful.configure do |config|
config.access_token = <CONTENTFUL_ACCESS_TOKEN>
config.space = <CONTENTFUL_SPACE_ID>
end
WCC::Contentful.init!
```
+All configuration options can be found [in the rubydoc](https://www.rubydoc.info/gems/wcc-contentful/WCC/Contentful/Configuration) under
+{WCC::Contentful::Configuration}
+
## 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!
+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
@@ -162,11 +174,12 @@
# ...}
```
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.
+through to the API to set the page size. If you truly want a limited subset of
+response items, use [`response.items.take(n)`](https://ruby-doc.org/core-2.5.3/Enumerable.html#method-i-take)
Entries included via the `include` parameter are made available on the #includes
field. This is a hash of `<entry ID> => <raw entry>` and makes it easy to grab
links. This hash is added to lazily as you enumerate the pages.
@@ -209,10 +222,14 @@
client.entries(...)
end
end
```
+## Architecture
+
+
+
## Test Helpers
To use the test helpers, include the following in your rails_helper.rb:
```ruby
@@ -237,11 +254,11 @@
instance.other_optional_field
# => nil
instance.not_a_field
-# NoMethodError: undefined method `not_a_field' for #<Menu:0x00007fbac81ee490>
+# NoMethodError: undefined method `not_a_field' for #<MyContentType:0x00007fbac81ee490>
##
# 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.
@@ -249,10 +266,13 @@
# => #<Double (anonymous)>
dbl.my_field
# => "other-value"
+dbl.other_optional_field
+# => nil
+
dbl.not_a_field
# => #<Double (anonymous)> received unexpected message :not_a_field with (no args)
##
# Builds out a fake Contentful entry for the given content type, and then
@@ -268,15 +288,84 @@
MyContentType.find_by(my_field: 'test') == stubbed
# => true
```
+## Advanced Configuration Example
-## Development
+Here's an example containing all the configuration options, and a sample setup for
+automatic deployment to Heroku. This is intended to make you aware of what is possible,
+and not as a general recommendation of what your setup should look like.
-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.
+```ruby
+# config/initializers/wcc_contentful.rb
+WCC::Contentful.configure do |config|
+ config.access_token = ENV['CONTENTFUL_ACCESS_TOKEN']
+ config.space = ENV['CONTENTFUL_SPACE_ID']
+ config.environment = ENV['CONTENTFUL_ENVIRONMENT']
+ config.preview_token = ENV['CONTENTFUL_PREVIEW_ACCESS_TOKEN']
-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).
+ # You may or may not want to provide this to your production server...
+ config.management_token = ENV['CONTENTFUL_MANAGEMENT_TOKEN'] unless Rails.env.production?
+
+ config.app_url = "https://#{ENV['HOSTNAME']}"
+ config.webhook_username = 'my-app-webhook'
+ config.webhook_password = Rails.application.secrets.webhook_password
+ config.webhook_jobs << MyOnWebhookJob
+
+ config.store = :lazy_sync, Rails.cache if Rails.env.production?
+ # config.store = MyCustomStore.new
+
+ # Use a custom Faraday connection
+ config.connection = Faraday.new do |builder|
+ f.request :retry
+ f.request MyFaradayRequestAdapter.new
+ ...
+ end
+ # OR implement some adapter like this to use another HTTP client
+ config.connection = MyNetHttpAdapter.new
+
+ config.update_schema_file = :never
+end
+
+WCC::Contentful.init!
+```
+
+For Heroku:
+
+```yaml
+# Procfile
+web: bundle exec rails s
+worker: bundle exec sidekiq
+release: bin/release
+```
+
+```sh
+# bin/release
+#!/bin/sh
+
+set -e
+
+echo "Migrating database..."
+bin/rake db:migrate
+
+echo "Migrating contentful..."
+migrations_to_be_run=$( ... ) # somehow figure this out
+node_modules/.bin/contentful-migration \
+ -s $CONTENTFUL_SPACE_ID -a $CONTENTFUL_MANAGEMENT_TOKEN \
+ -y -p "$migrations_to_be_run"
+
+echo "Updating schema file..."
+rake wcc_contentful:download_schema
+```
+
+All configuration options can be found [in the rubydoc](https://www.rubydoc.info/gems/wcc-contentful/WCC/Contentful/Configuration) under
+{WCC::Contentful::Configuration}
+
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
## 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.