chargify/chargify_api_ares — pull request #86 by jeremywrowe (2014-08-20 14:34:32+00:00)
Title: [feature] Adds metafields and metadata

* Adds CustomerMetafield and SubscriptionMetafield resources
* Updates to activeresource 3.2.16+ for bugfixes and to allow metafield
resources.

This is a pre-release that adds customer and subscription metafield
endpoints.

Example usage:

(all examples work with SubscriptionMetafield or CustomerMetafield I
chose to show CustomerMetafield for brevity)

Creating a field

```ruby
field = CustomerMetafield.build(name: 'shoe size')
field.on_hosted_pages = product_id_1, product_id_2
field.on_csv_export = false
```

Note that build is being used here instead of create. the `on_*` methods
are helper methods. Without them it is painful to modify the scope of
the metafield.

Updating a field

```ruby
metafields = CustomerMetafield.all
field = metafields.first

field.name = "new name"
field.on_hosted_pages = product_id_1, product_id_2, ...
field.on_csv_export = true

field.save
```

Deleting a field

```ruby
metafields = CustomerMetafield.all
field = field.first
field.destroy
```

Note: finding an indivdual metafield is not supported. You will have to
either create a record or use `all` and then find the record that way.

It also might surprise you if you use `create` passing the `current_name`
attribute for an existing field it will update the record instead of
create a new one. Please see the API documentation for further information.

This adds a handful of new methods to `Chargify::Subscription`

`create_metadata` - allows you to create or update a metadata object for a
subscription. It will be saved to the server as soon as it is called.

Example

```ruby
subscription = Chargify::Subscription.find(123)
metadata = subscription.create_metadata(:name => 'Shirt Size', :value => 'M')
metadata.persisted? # => true
```

`build_metadata` - allows you to create a new metadata object for a
subscription *without* saving it. This is useful if you want to build up
a metadata object and do some things with your internal application
logic and then save it later.

Example

```ruby
subscription = Chargify::Subscription.find(123)
metadata = subscription.build_metadata(:name => 'Shirt Size')

metadata.persisted? # => false
...

metadata.value = 'L'
metadata.save
```

`metadata` - fetches all of your metadata for a given subscription. (A
collection of metadata)

Example

```ruby
subscription = Chargify::Subscription.find(123)
data = subscription.metadata # => [data1, data2, ... datan]
```

Important things to note about metadata

To update a piece of metadata fetch it set it's value and save it. If
you want to change the metadata name use the `name` field to update it
after it is fetched. You'll notice that there is a `current_name` that
is used for internal purposes to track changes. For mor information
about metadata [see](https://docs.chargify.com/api-metadata)