dato 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aa6cd26ac346a262967adba55486b614dec900d2
-  data.tar.gz: 5df73d12129516a164298059aee45ee57c21a98f
+  metadata.gz: a123bdb067779fadf0d29ab434db81b9f33f48d7
+  data.tar.gz: af8b3f7ce4632f450b3081040f900ba8fa1146ef
 SHA512:
-  metadata.gz: b251136ad1db77b6ba2d98adb07a8557980ca829871f11726a9cc8c0881265212eb2783c9fc2768cbd7096527515aa89f8b6a8369e3dbba37e73533becb6320a
-  data.tar.gz: ce4c415f552fdafefaea3ba81b158b34e17e86fc669ffb7d0a3f417134e22294ae88056ffd4c69df822f7cea9d6ee9b3af42018f8277fde281a60c76592342ce
+  metadata.gz: 7dd0d16ffb9cabf60d28c3805099af9fe36ebfa162d4c59d61d1e57d58948fbf3f5863b34393205e3e1a611333ae9a4cd6bba12b76f9fb0aa2c3256aa155b8a1
+  data.tar.gz: 49362731b3cb91401b040601daad608ca09baaf68cb22fb522a3751ab54772ad01927deebde0484e7107e3756eeec554d93aa113b08dab38c6506974fddbee90

data/README.md

@@ -1,69 +1,23 @@
 # DatoCMS Ruby Client
 
-[![Build Status](https://travis-ci.org/datocms/ruby-datocms-client.svg?branch=master)](https://travis-ci.org/datocms/ruby-datocms-client)
+[![Build Status](https://travis-ci.org/datocms/ruby-datocms-client.svg?branch=master)](https://travis-ci.org/datocms/ruby-datocms-client) [![Gem Version](https://badge.fury.io/rb/dato.svg)](https://badge.fury.io/rb/dato)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/dato`. To experiment with that code, run `bin/console` for an interactive prompt.
+Ruby client for the DatoCMS API.
 
-TODO: Delete this and the text above, and describe your gem
+[DatoCMS](https://www.datocms.com/) is a fully customizable administrative area for your static websites:
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'dato'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install dato
+1. Use your favorite static website generator (Middleman, Hugo, Jekyll, and many others);
+2. Let your clients publish new content independently;
+3. Let your site build with any Continuous Deployment service (Netlify, Gitlab, CircleCI, etc.);
+4. Host the site anywhere you like (Amazon S3, Netlify, Surge.sh, etc.)
 
 ## Usage
 
-```ruby
-client = Dato::Site::Client.new("YOUR_SITE_API_TOKEN")
-
-article_type = client.item_types.create(
-  name: "Article",
-  singleton: false,
-  sortable: false,
-  api_key: "article"
-)
-
-client.fields.create(
-  article_type[:id],
-  api_key: "title",
-  field_type: "string",
-  appeareance: { type: "title" },
-  label: "Title",
-  localized: false,
-  position: 99,
-  hint: "",
-  validators: { required: {} },
-)
-
-client.fields.create(
-  article_type[:id],
-  api_key: "image",
-  field_type: "image",
-  appeareance: nil,
-  label: "Image",
-  localized: false,
-  position: 99,
-  hint: "",
-  validators: { required: {} },
-)
-
-client.items.create(
-  item_type: article_type[:id],
-  title: "First post!",
-  image: client.upload_image("http://i.giphy.com/NXOF5rlaSXdAc.gif")
-)
-```
+This gem can be used in different ways, so the documentation is split up in different files:
+
+* [I want to use the content of a DatoCMS site in my static website (Hugo, Jeckyll, etc.)](https://github.com/datocms/ruby-datocms-client/blob/master/docs/dato-cli.md);
+* [I want to edit the contents of an existing DatoCMS site  programmatically](https://github.com/datocms/ruby-datocms-client/blob/master/docs/site-api-client.md);
+* [I want to create new DatoCMS sites programmatically](https://github.com/datocms/ruby-datocms-client/blob/master/docs/account-api-client.md).
 
 ## Development
 
@@ -71,11 +25,14 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 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).
 
+### Updating the client when the API changes
+
+The DatoCMS API provides an always up-to-date [JSON Hyperschema](http://json-schema.org/latest/json-schema-hypermedia.html): the code of this gem is generated automatically starting from the schema running `rake regenerate`.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/dato. 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).

data/Rakefile

@@ -10,7 +10,7 @@ RSpec::Core::RakeTask.new(:spec)
 task default: :spec
 
 desc 'Regenerates the client starting from the JSON Hyperschema'
-task :build_repos do
+task :regenerate do
   BuildClient.new(
     open('https://site-api.datocms.com/docs/site-api-hyperschema.json').read,
     'site',

data/docs/account-api-client.md

@@ -0,0 +1,53 @@
+# Create/edit sites within a DatoCMS account 
+
+With this gem, you can easily create, edit and destroy DatoCMS sites, as well as editing your account settings.
+
+# Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'dato'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install dato
+
+## Usage
+
+```ruby
+require "dato"
+
+# fetch existing sites
+sites = client.sites.all
+
+# create a new site
+site = client.sites.create(name: 'Foobar')
+
+# update an existing site
+client.sites.update(site[:id], site.merge(name: 'Blog'))
+
+# destroy an existing site
+client.sites.destroy(new_site[:id])
+```
+
+## List of client methods
+
+```ruby
+client.account.find
+client.account.create(resource_attributes)
+client.account.update(resource_attributes)
+client.account.reset_password(resource_attributes)
+
+client.sites.find(site_id)
+client.sites.all
+client.sites.create(resource_attributes)
+client.sites.update(site_id, resource_attributes)
+client.sites.destroy(site_id)
+client.sites.duplicate(site_id, resource_attributes)
+```

data/docs/dato-cli.md

@@ -0,0 +1,226 @@
+# Integrating DatoCMS with your static website generator
+
+[DatoCMS](https://www.datocms.com) is working hard to provide the easiest way to enable non-technical editors to update a completely static website — without the intervention of a developer — from the comfort of a user-friendly web interface, just like they're used with Wordpress and such.
+
+Middleman, Hugo, Jekyll, Hexo, Pelican, Octopress, GatsbyJS... the list of static site generators is [almost endless](https://www.staticgen.com/) and keeps on growing.
+
+This gem provides an easy way to integrate content coming from a DatoCMS into virtually any static website generator.
+
+# How it works
+
+All the websites built with a static website generator are made of:
+
+* Static files which represent the actual content of the pages (usually written in Markdown + [front matter](https://jekyllrb.com/docs/frontmatter/), YAML, JSON or Toml);
+* Some HTML templates that use these files to generate the actual static HTML pages you will upload online.
+
+That means that, up until now, even the most basic change to a static website could only be performed by a tech-savvy user, as too many things had to be known (Git, Markdown syntax, proper editing of YAML/JSON/Toml files).
+
+DatoCMS works differently:
+
+1. You create a web administrative interface for your editors that fits exactly the needs of your static website;
+2. Editors can make changes to the content of the website from that CMS interface you prepared;
+3. Using this gem, all the data stored in your DatoCMS administrative interface can be transformed into local Markdown/YAML/JSON/Toml files, so that can be "digested" by the static website generator just as they were written by hand.
+
+The process of translating the data coming from the API into static files can be performed both on your machine during the development process of the website, and in your Continuous Deployment service anytime the editors request a new "build" pressing a "Publish" button on the web interface.
+
+Now your static website isn't static anymore! Isn't this awesome?! :-) 
+
+## Installing the CLI tool
+
+Once you have a working Ruby environment, you can use the CLI tool running these commands within your static website directory:
+
+```
+gem install bundler
+bundle init
+echo 'gem "dato"' >> Gemfile
+bundle install
+```
+
+If everything worked correctly, you should now run `bundle exec dato` and see something like this:
+
+```
+$ bundle exec dato
+DatoCMS commands:
+  dato dump --token=TOKEN  # dumps DatoCMS contents into local files
+  dato help [COMMAND]      # Describe available commands or one specific command
+```
+
+Hurray!!
+
+## Step-by-step integration guide
+
+Now, just to make things more down-to-heart, suppose we're working with a Hugo website with the following structure:
+
+```
+.
+├── config.toml
+├── content
+|   ├── post
+|   |   ├── first-post.md
+|   |   └── ...
+|   └── quote
+|   |   ├── first-quote.md
+|   |   └── ...
+├── data
+|   └── author
+|       ├── mark.toml
+|       └── ...
+├── layouts
+|   └── ...
+└── static
+    └── ...
+```
+
+Our job is to generate the Markdown files in the `content` directory from the data contained in our DatoCMS site. Also the Toml files contained in the in the `data` directory need the same treatment.
+
+### Set up the site
+
+Using the DatoCMS web interface, we first create the following Item types:
+
+* post
+  - title (string, required, title)
+  - publication_date (date, required)
+  - body (text, required)
+
+* author
+  - name (string, required, title)
+  - bio (text, required)
+
+* quote
+  - content (text, required)
+  - author (link to author, required)
+
+### Writing the config file
+
+We then define how content stored in DatoCMS needs to be translated into local files using a config file placed in your project root folder called `dato.config.rb`.
+
+Let's start with posts:
+
+```ruby
+directory "content/post" do
+  dato.posts.each do |item|
+    create_post "#{item.slug}.md" do
+      frontmatter :toml,
+        title: item.title,
+        date: item.publication_date.to_s
+
+      content item.body
+    end
+  end
+end
+```
+
+The DSL is quite terse! Basically we're declaring that:
+
+1. we want to take possess of the directory `content/post` and manage it programmatically from now on;
+2. we then iterate over each post stored in DatoCMS and...
+3. for each post, we create a local markdown file:
+  - named after the slugified version of the post title;
+  - that contains the post body;
+  - decorated with a Toml front matter with a `title` and `date` keys; 
+
+Now we can run the following command:
+
+```
+$ bundle exec dato dump --token=SITE_READONLY_TOKEN 
+```
+
+And see the `content/post` directory emptied from previous content and filled with new files:
+
+```
+.
+└── content
+    └── post
+        ├── lorem-ipsum.md
+        ├── dolor-sit-amet.md
+        ├── consectetur-adipisci.md
+        └── ...
+```
+
+Let's open one of those Markdown files:
+
+```
++++
+title = "Lorem ipsum"
+date = "2001-02-03"
++++
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
+
+Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 
+```
+
+Awesome!! We can now continue using Hugo just like we're used to.
+
+### A more complete config file
+
+The config file let us declare different kind of "operations":
+
+| Command | Description |
+| --- | --- |
+| `create_post` | Generate Markdown + Frontmatter files |
+| `create_data_file` | Generate plain Toml/YAML files |
+| `add_to_data_file` | Add some keys to an existing Toml/YAML file |
+
+In fact, this is a more complete version of our `dato.config.rb` file:
+
+```ruby
+directory "content/post" do
+  dato.posts.each do |item|
+    create_post "#{item.slug}.md" do
+      frontmatter :toml,
+        title: item.title,
+        date: item.publication_date.to_s
+
+      content item.body
+    end
+  end
+end
+
+directory "content/quote" do
+  dato.quotes.each_with_index do |item, i|
+    create_post "#{item.id}.md" do
+      frontmatter :toml,
+        title: "Quote number #{i}",
+        weight: i
+
+      content item.content
+    end
+  end
+end
+
+directory "data/authors" do
+  dato.authors.each do |item|
+    create_data_file "#{item.name.slug}.toml", :toml,
+      name: item.name,
+      bio: item.bio
+    end
+  end
+end
+```
+
+### How to fetch data from DatoCMS
+
+Using the `dato` method you can access to any item stored in your site grouped by item type. That is, if your site has an Item Type with `post` as API identifier, you can get the complete array of items with `dato.posts` (the pluralized API identifier).
+
+If a Item Type is marked as "single instance" (ie. `about_page`) you don't need to pluralize and a call to `dato.about_page` directly returns the item (or `nil`, if still hasn't been created within the CMS).
+
+You can query an item's field value with a method called like the field API identifier.
+
+An item also features a `.slug` method:
+
+* if an item type has a field of type `string` with a "Title" Presentation mode, than the method returns the slugified version of the title itself;
+* otherwise, it just returns the unique identifier of the item;
+
+Complex field types (ie. `image`, `file`, `video`, `seo`) implement specific methods you can use as well within the config file:
+
+```
+article = dato.articles.first
+
+article.cover_image.file.width(500).fit('crop').to_url
+article.video.iframe_embed(800, 600)
+```
+
+### Need more help?
+
+Just ask! Send us an email to [support@datocms.com](mailto:support@datocms.com) and we'll be happy to guide you.

data/docs/site-api-client.md

@@ -0,0 +1,123 @@
+# Edit the contents of an existing DatoCMS site
+
+With this gem, you can easily create, edit and destroy any object within a DatoCMS site:
+
+* Item types
+* Fields
+* Items
+* Menu items
+* Users
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'dato'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install dato
+
+## Usage
+
+```ruby
+require "dato"
+
+# create a DatoCMS client
+client = Dato::Site::Client.new("YOUR_SITE_API_READWRITE_TOKEN")
+
+# create a new Article item type
+article_type = client.item_types.create(
+  name: "Article",
+  singleton: false,
+  sortable: false,
+  api_key: "article"
+)
+
+# add a Title field to the Article item type
+client.fields.create(
+  article_type[:id],
+  api_key: "title",
+  field_type: "string",
+  appeareance: { type: "title" },
+  label: "Title",
+  localized: false,
+  position: 99,
+  hint: "",
+  validators: { required: {} },
+)
+
+# add an Image field to the Article item type
+client.fields.create(
+  article_type[:id],
+  api_key: "image",
+  field_type: "image",
+  appeareance: nil,
+  label: "Image",
+  localized: false,
+  position: 99,
+  hint: "",
+  validators: { required: {} },
+)
+
+# create a new Article
+client.items.create(
+  item_type: article_type[:id],
+  title: "My first article!",
+  image: client.upload_image("http://i.giphy.com/NXOF5rlaSXdAc.gif")
+)
+
+# fetch and edit an existing Article
+article = client.items.find("1234")
+client.items.update("1234", article.merge(title: "New title"))
+
+# destroy an existing article
+client.items.destroy("1234")
+```
+
+## List of client methods
+
+```ruby
+client.fields.create(item_type_id, resource_attributes)
+client.fields.update(field_id, resource_attributes)
+client.fields.all(item_type_id)
+client.fields.find(field_id)
+client.fields.destroy(field_id)
+
+client.items.create(resource_attributes)
+client.items.update(item_id, resource_attributes)
+client.items.all(filters = {})
+client.items.find(item_id)
+client.items.destroy(item_id)
+
+client.item_types.create(resource_attributes)
+client.item_types.update(item_type_id, resource_attributes)
+client.item_types.all
+client.item_types.find(item_type_id)
+client.item_types.destroy(item_type_id)
+
+client.menu_items.create(resource_attributes)
+client.menu_items.update(menu_item_id, resource_attributes)
+client.menu_items.all
+client.menu_items.find(menu_item_id)
+client.menu_items.destroy(menu_item_id)
+
+client.site.find
+client.site.update(resource_attributes)
+
+client.upload_image(path_or_url)
+client.upload_file(path_or_url)
+
+client.users.create(resource_attributes)
+client.users.update(user_id, resource_attributes)
+client.users.all
+client.users.find(user_id)
+client.users.reset_password(resource_attributes)
+client.users.destroy(user_id)
+```

data/lib/dato/dump/format/yaml.rb

@@ -7,7 +7,7 @@ module Dato
     module Format
       module Yaml
         def self.dump(value)
-          YAML.dump(value).chomp.gsub(/^\-+\n/, '')
+          YAML.dump(value.deep_stringify_keys).chomp.gsub(/^\-+\n/, '')
         end
 
         def self.frontmatter_dump(value)

data/lib/dato/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module Dato
-  VERSION = '0.1.8'
+  VERSION = '0.1.9'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dato
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.9
 platform: ruby
 authors:
 - Stefano Verna
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-08-23 00:00:00.000000000 Z
+date: 2016-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -296,6 +296,9 @@ files:
 - bin/console
 - bin/setup
 - dato.gemspec
+- docs/account-api-client.md
+- docs/dato-cli.md
+- docs/site-api-client.md
 - exe/dato
 - lib/dato.rb
 - lib/dato/account/client.rb