Class: Grape::Entity
- Inherits:
-
Object
- Object
- Grape::Entity
- Defined in:
- lib/grape_entity/entity.rb
Overview
An Entity is a lightweight structure that allows you to easily represent data from your application in a consistent and abstracted way in your API. Entities can also provide documentation for the fields exposed.
Entities are not independent structures, rather, they create representations of other Ruby objects using a number of methods that are convenient for use in an API. Once you've defined an Entity, you can use it in your API like this:
Defined Under Namespace
Modules: DSL
Class Attribute Summary collapse
-
._nested_attribute_names_hash ⇒ Object
Returns the value of attribute _nested_attribute_names_hash.
-
._nested_exposures_hash ⇒ Object
Returns the value of attribute _nested_exposures_hash.
Instance Attribute Summary collapse
-
#object ⇒ Object
readonly
Returns the value of attribute object.
-
#options ⇒ Object
readonly
Returns the value of attribute options.
Class Method Summary collapse
-
.documentation ⇒ Object
Returns a hash, the keys are symbolized references to fields in the entity, the values are document keys in the entity's documentation key.
-
.expose(*args, &block) ⇒ Object
This method is the primary means by which you will declare what attributes should be exposed by the entity.
-
.exposures ⇒ Object
Returns a hash of exposures that have been declared for this Entity or ancestors.
-
.format_with(name, &block) ⇒ Object
This allows you to declare a Proc in which exposures can be formatted with.
-
.formatters ⇒ Object
Returns a hash of all formatters that are registered for this and it's ancestors.
- .nested_attribute_names ⇒ Object
- .nested_attribute_names_hash ⇒ Object
- .nested_exposures ⇒ Object
- .nested_exposures_hash ⇒ Object
-
.present_collection(present_collection = false, collection_name = :items) ⇒ Object
This allows you to present a collection of objects.
-
.represent(objects, options = {}) ⇒ Object
This convenience method allows you to instantiate one or more entities by passing either a singular or collection of objects.
-
.root(plural, singular = nil) ⇒ Object
This allows you to set a root element name for your representation.
- .unexpose(attribute) ⇒ Object
-
.with_options(options) ⇒ Object
Set options that will be applied to any exposures declared inside the block.
Instance Method Summary collapse
- #documentation ⇒ Object
- #exposures ⇒ Object
- #formatters ⇒ Object
-
#initialize(object, options = {}) ⇒ Entity
constructor
A new instance of Entity.
- #presented ⇒ Object
-
#serializable_hash(runtime_options = {}) ⇒ Object
(also: #as_json)
The serializable hash is the Entity's primary output.
- #to_json(options = {}) ⇒ Object
- #to_xml(options = {}) ⇒ Object
- #valid_exposures ⇒ Object
Constructor Details
#initialize(object, options = {}) ⇒ Entity
Returns a new instance of Entity.
430 431 432 |
# File 'lib/grape_entity/entity.rb', line 430 def initialize(object, = {}) @object, @options = object, end |
Class Attribute Details
._nested_attribute_names_hash ⇒ Object
Returns the value of attribute _nested_attribute_names_hash.
196 197 198 |
# File 'lib/grape_entity/entity.rb', line 196 def _nested_attribute_names_hash @_nested_attribute_names_hash end |
._nested_exposures_hash ⇒ Object
Returns the value of attribute _nested_exposures_hash.
197 198 199 |
# File 'lib/grape_entity/entity.rb', line 197 def _nested_exposures_hash @_nested_exposures_hash end |
Instance Attribute Details
#object ⇒ Object (readonly)
Returns the value of attribute object.
45 46 47 |
# File 'lib/grape_entity/entity.rb', line 45 def object @object end |
#options ⇒ Object (readonly)
Returns the value of attribute options.
45 46 47 |
# File 'lib/grape_entity/entity.rb', line 45 def @options end |
Class Method Details
.documentation ⇒ Object
Returns a hash, the keys are symbolized references to fields in the entity, the values are document keys in the entity's documentation key. When calling
docmentation, any exposure without a documentation key will be ignored.
235 236 237 238 239 240 241 242 243 244 245 246 247 248 |
# File 'lib/grape_entity/entity.rb', line 235 def self.documentation @documentation ||= exposures.inject({}) do |memo, (attribute, )| unless [:documentation].nil? || [:documentation].empty? memo[key_for(attribute)] = [:documentation] end memo end if superclass.respond_to? :documentation @documentation = superclass.documentation.merge(@documentation) end @documentation end |
.expose(*args, &block) ⇒ Object
This method is the primary means by which you will declare what attributes should be exposed by the entity.
126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 |
# File 'lib/grape_entity/entity.rb', line 126 def self.expose(*args, &block) = (args.last.is_a?(Hash) ? args.pop : {}) if args.size > 1 fail ArgumentError, 'You may not use the :as option on multi-attribute exposures.' if [:as] fail ArgumentError, 'You may not use block-setting on multi-attribute exposures.' if block_given? end fail ArgumentError, 'You may not use block-setting when also using format_with' if block_given? && [:format_with].respond_to?(:call) [:proc] = block if block_given? && block.parameters.any? @nested_attributes ||= [] args.each do |attribute| unless @nested_attributes.empty? orig_attribute = attribute.to_sym attribute = "#{@nested_attributes.last}__#{attribute}" nested_attribute_names_hash[attribute.to_sym] = orig_attribute [:nested] = true nested_exposures_hash[@nested_attributes.last.to_sym] ||= {} nested_exposures_hash[@nested_attributes.last.to_sym][attribute.to_sym] = end exposures[attribute.to_sym] = # Nested exposures are given in a block with no parameters. if block_given? && block.parameters.empty? @nested_attributes << attribute block.call @nested_attributes.pop end end end |
.exposures ⇒ Object
Returns a hash of exposures that have been declared for this Entity or ancestors. The keys are symbolized references to methods on the containing object, the values are the options that were passed into expose.
183 184 185 186 187 188 189 190 191 192 193 |
# File 'lib/grape_entity/entity.rb', line 183 def self.exposures return @exposures unless @exposures.nil? @exposures = {} if superclass.respond_to? :exposures @exposures = superclass.exposures.merge(@exposures) end @exposures end |
.format_with(name, &block) ⇒ Object
This allows you to declare a Proc in which exposures can be formatted with. It take a block with an arity of 1 which is passed as the value of the exposed attribute.
276 277 278 279 |
# File 'lib/grape_entity/entity.rb', line 276 def self.format_with(name, &block) fail ArgumentError, 'You must pass a block for formatters' unless block_given? formatters[name.to_sym] = block end |
.formatters ⇒ Object
Returns a hash of all formatters that are registered for this and it's ancestors.
282 283 284 285 286 287 288 289 290 |
# File 'lib/grape_entity/entity.rb', line 282 def self.formatters @formatters ||= {} if superclass.respond_to? :formatters @formatters = superclass.formatters.merge(@formatters) end @formatters end |
.nested_attribute_names ⇒ Object
207 208 209 210 211 212 213 214 215 216 217 |
# File 'lib/grape_entity/entity.rb', line 207 def nested_attribute_names return @nested_attribute_names unless @nested_attribute_names.nil? @nested_attribute_names = {}.merge(nested_attribute_names_hash) if superclass.respond_to? :nested_attribute_names @nested_attribute_names = superclass.nested_attribute_names.deep_merge(@nested_attribute_names) end @nested_attribute_names end |
.nested_attribute_names_hash ⇒ Object
199 200 201 |
# File 'lib/grape_entity/entity.rb', line 199 def nested_attribute_names_hash self._nested_attribute_names_hash ||= {} end |
.nested_exposures ⇒ Object
219 220 221 222 223 224 225 226 227 228 229 |
# File 'lib/grape_entity/entity.rb', line 219 def nested_exposures return @nested_exposures unless @nested_exposures.nil? @nested_exposures = {}.merge(nested_exposures_hash) if superclass.respond_to? :nested_exposures @nested_exposures = superclass.nested_exposures.deep_merge(@nested_exposures) end @nested_exposures end |
.nested_exposures_hash ⇒ Object
203 204 205 |
# File 'lib/grape_entity/entity.rb', line 203 def nested_exposures_hash self._nested_exposures_hash ||= {} end |
.present_collection(present_collection = false, collection_name = :items) ⇒ Object
This allows you to present a collection of objects.
When false (default) every object in a collection to present will be wrapped separately into an instance of your presenter.
387 388 389 390 |
# File 'lib/grape_entity/entity.rb', line 387 def self.present_collection(present_collection = false, collection_name = :items) @present_collection = present_collection @collection_name = collection_name end |
.represent(objects, options = {}) ⇒ Object
This convenience method allows you to instantiate one or more entities by passing either a singular or collection of objects. Each object will be initialized with the same options. If an array of objects is passed in, an array of entities will be returned. If a single object is passed in, a single entity will be returned.
407 408 409 410 411 412 413 414 415 416 417 418 419 420 |
# File 'lib/grape_entity/entity.rb', line 407 def self.represent(objects, = {}) if objects.respond_to?(:to_ary) && ! @present_collection root_element = @collection_root inner = objects.to_ary.map { |object| new(object, { collection: true }.merge()).presented } else objects = { @collection_name => objects } if @present_collection root_element = @root inner = new(objects, ).presented end root_element = [:root] if .key?(:root) root_element ? { root_element => inner } : inner end |
.root(plural, singular = nil) ⇒ Object
This allows you to set a root element name for your representation.
331 332 333 334 |
# File 'lib/grape_entity/entity.rb', line 331 def self.root(plural, singular = nil) @collection_root = plural @root = singular end |
.unexpose(attribute) ⇒ Object
161 162 163 |
# File 'lib/grape_entity/entity.rb', line 161 def self.unexpose(attribute) exposures.delete(attribute) end |
.with_options(options) ⇒ Object
Set options that will be applied to any exposures declared inside the block.
174 175 176 177 178 |
# File 'lib/grape_entity/entity.rb', line 174 def self.() (@block_options ||= []).push(()) yield @block_options.pop end |
Instance Method Details
#documentation ⇒ Object
444 445 446 |
# File 'lib/grape_entity/entity.rb', line 444 def documentation self.class.documentation end |
#exposures ⇒ Object
434 435 436 |
# File 'lib/grape_entity/entity.rb', line 434 def exposures self.class.exposures end |
#formatters ⇒ Object
448 449 450 |
# File 'lib/grape_entity/entity.rb', line 448 def formatters self.class.formatters end |
#presented ⇒ Object
422 423 424 425 426 427 428 |
# File 'lib/grape_entity/entity.rb', line 422 def presented if [:serializable] serializable_hash else self end end |
#serializable_hash(runtime_options = {}) ⇒ Object Also known as: as_json
The serializable hash is the Entity's primary output. It is the transformed hash for the given data model and is used as the basis for serialization to JSON and other formats.
459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 |
# File 'lib/grape_entity/entity.rb', line 459 def serializable_hash( = {}) return nil if object.nil? opts = .merge( || {}) valid_exposures.inject({}) do |output, (attribute, )| if conditions_met?(, opts) partial_output = value_for(attribute, opts) output[self.class.key_for(attribute)] = if partial_output.respond_to? :serializable_hash partial_output.serializable_hash() elsif partial_output.is_a?(Array) && !partial_output.map { |o| o.respond_to? :serializable_hash }.include?(false) partial_output.map(&:serializable_hash) elsif partial_output.is_a?(Hash) partial_output.each do |key, value| partial_output[key] = value.serializable_hash if value.respond_to? :serializable_hash end else partial_output end end output end end |
#to_json(options = {}) ⇒ Object
484 485 486 487 |
# File 'lib/grape_entity/entity.rb', line 484 def to_json( = {}) = .to_h if && .respond_to?(:to_h) MultiJson.dump(serializable_hash()) end |
#to_xml(options = {}) ⇒ Object
489 490 491 492 |
# File 'lib/grape_entity/entity.rb', line 489 def to_xml( = {}) = .to_h if && .respond_to?(:to_h) serializable_hash().to_xml() end |
#valid_exposures ⇒ Object
438 439 440 441 442 |
# File 'lib/grape_entity/entity.rb', line 438 def valid_exposures exposures.reject { |_, | [:nested] }.select do |attribute, | valid_exposure?(attribute, ) end end |