README.md in alba-3.1.0 vs README.md in alba-3.2.0
- old
+ new
@@ -90,11 +90,11 @@
Alba is easy to use because there are only a few methods to remember. It's also easy to understand due to clean and small codebase. Finally it's easy to extend since it provides some methods for override to change default behavior of Alba.
### Feature rich
-While Alba's core is simple, it provides additional features when you need them, For example, Alba provides [a way to control circular associations](#circular-associations-control), [root key and association resource name inference](#root-key-and-association-resource-name-inference) and [supports layouts](#layout).
+While Alba's core is simple, it provides additional features when you need them. For example, Alba provides [a way to control circular associations](#circular-associations-control), [root key and association resource name inference](#root-key-and-association-resource-name-inference) and [supports layouts](#layout).
### Other reasons
- Dependency free, no need to install `oj` or `activesupport` while Alba works well with them
- Well tested, the test coverage is 99%
@@ -361,11 +361,11 @@
end
FooResource.new(Foo.new).serialize
# => '{"bar":"This is Foo"}'
```
-
+
#### Params
You can pass a Hash to the resource for internal use. It can be used as "flags" to control attribute content.
```ruby
@@ -1515,12 +1515,41 @@
# Now `LibraryResource` works!
```
Within `helper` block, all methods should be defined without `self.`.
-`helper`
+### Experimental: modification API
+Alba now provides an experimental API to modify existing resource class without adding new classes. Currently only `transform_keys!` is implemented.
+
+Modification API returns a new class with given modifications. It's useful when you want lots of resource classes with small changes. See it in action:
+
+```ruby
+class FooResource
+ include Alba::Resource
+
+ transform_keys :camel
+
+ attributes :id
+end
+
+# Rails app
+class FoosController < ApplicationController
+ def index
+ foos = Foo.where(some: :condition)
+ key_transformation_type = params[:key_transformation_type] # Say it's "lower_camel"
+ # When params is absent, do not use modification API since it's slower
+ resource_class = key_transformation_type ? FooResource.transform_keys!(key_transformation_type) : FooResource
+ render json: resource_class.new(foos).serialize # The keys are lower_camel
+ end
+end
+```
+
+The point is that there's no need to define classes for each key transformation type (dash, camel, lower_camel and snake). This gives even more flexibility.
+
+There are some drawbacks with this approach. For example, it creates an internal, anonymous class when it's called, so there is a performance penalty and debugging difficulty. It's recommended to define classes manually when you don't need high flexibility.
+
### Caching
Currently, Alba doesn't support caching, primarily due to the behavior of `ActiveRecord::Relation`'s cache. See [the issue](https://github.com/rails/rails/issues/41784).
### Extend Alba
@@ -1657,10 +1686,24 @@
formatted_time_attributes :updated_at
end
end
```
+You can also pass options to your helpers.
+
+```ruby
+module AlbaExtension
+ def time_attributes(*attrs, **options)
+ attrs.each do |attr|
+ attribute(attr, **options) do |object|
+ object.__send__(attr).iso8601
+ end
+ end
+ end
+end
+```
+
### Debugging
Debugging is not easy. If you find Alba not working as you expect, there are a few things to do:
1. Inspect
@@ -1693,10 +1736,10 @@
```ruby
module Logging
# `...` was added in Ruby 2.7
def serialize(...)
puts serializable_hash
- super(...)
+ super
end
end
FooResource.prepend(Logging)
FooResource.new(foo).serialize