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
-
.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.
-
.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.
-
#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.
363 364 365 |
# File 'lib/grape_entity/entity.rb', line 363 def initialize(object, = {}) @object, @options = object, end |
Class Attribute Details
._nested_attribute_names_hash ⇒ Object
Returns the value of attribute _nested_attribute_names_hash.
192 193 194 |
# File 'lib/grape_entity/entity.rb', line 192 def _nested_attribute_names_hash @_nested_attribute_names_hash end |
._nested_exposures_hash ⇒ Object
Returns the value of attribute _nested_exposures_hash.
193 194 195 |
# File 'lib/grape_entity/entity.rb', line 193 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.
231 232 233 234 235 236 237 238 239 240 241 242 243 244 |
# File 'lib/grape_entity/entity.rb', line 231 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 raise ArgumentError, 'You may not use the :as option on multi-attribute exposures.' if [:as] raise ArgumentError, 'You may not use block-setting on multi-attribute exposures.' if block_given? end raise 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.
179 180 181 182 183 184 185 186 187 188 189 |
# File 'lib/grape_entity/entity.rb', line 179 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.
272 273 274 275 |
# File 'lib/grape_entity/entity.rb', line 272 def self.format_with(name, &block) raise 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.
278 279 280 281 282 283 284 285 286 |
# File 'lib/grape_entity/entity.rb', line 278 def self.formatters @formatters ||= {} if superclass.respond_to? :formatters @formatters = superclass.formatters.merge(@formatters) end @formatters end |
.nested_attribute_names ⇒ Object
203 204 205 206 207 208 209 210 211 212 213 |
# File 'lib/grape_entity/entity.rb', line 203 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
195 196 197 |
# File 'lib/grape_entity/entity.rb', line 195 def nested_attribute_names_hash self._nested_attribute_names_hash ||= {} end |
.nested_exposures ⇒ Object
215 216 217 218 219 220 221 222 223 224 225 |
# File 'lib/grape_entity/entity.rb', line 215 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
199 200 201 |
# File 'lib/grape_entity/entity.rb', line 199 def nested_exposures_hash self._nested_exposures_hash ||= {} 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.
345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 |
# File 'lib/grape_entity/entity.rb', line 345 def self.represent(objects, = {}) if objects.respond_to?(:to_ary) inner = objects.to_ary.map { |object| new(object, { collection: true }.merge()) } inner = inner.map(&:serializable_hash) if [:serializable] else inner = new(objects, ) inner = inner.serializable_hash if [:serializable] end root_element = if .key?(:root) [:root] else objects.respond_to?(:to_ary) ? @collection_root : @root end root_element ? { root_element => inner } : inner end |
.root(plural, singular = nil) ⇒ Object
This allows you to set a root element name for your representation.
327 328 329 330 |
# File 'lib/grape_entity/entity.rb', line 327 def self.root(plural, singular = nil) @collection_root = plural @root = singular end |
.with_options(options) ⇒ Object
Set options that will be applied to any exposures declared inside the block.
170 171 172 173 174 |
# File 'lib/grape_entity/entity.rb', line 170 def self.() (@block_options ||= []).push(()) yield @block_options.pop end |
Instance Method Details
#documentation ⇒ Object
377 378 379 |
# File 'lib/grape_entity/entity.rb', line 377 def documentation self.class.documentation end |
#exposures ⇒ Object
367 368 369 |
# File 'lib/grape_entity/entity.rb', line 367 def exposures self.class.exposures end |
#formatters ⇒ Object
381 382 383 |
# File 'lib/grape_entity/entity.rb', line 381 def formatters self.class.formatters 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.
392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 |
# File 'lib/grape_entity/entity.rb', line 392 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.kind_of?(Array) && !partial_output.map { |o| o.respond_to? :serializable_hash }.include?(false) partial_output.map { |o| o.serializable_hash } elsif partial_output.kind_of?(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
417 418 419 420 |
# File 'lib/grape_entity/entity.rb', line 417 def to_json( = {}) = .to_h if && .respond_to?(:to_h) MultiJson.dump(serializable_hash()) end |
#to_xml(options = {}) ⇒ Object
422 423 424 425 |
# File 'lib/grape_entity/entity.rb', line 422 def to_xml( = {}) = .to_h if && .respond_to?(:to_h) serializable_hash().to_xml() end |
#valid_exposures ⇒ Object
371 372 373 374 375 |
# File 'lib/grape_entity/entity.rb', line 371 def valid_exposures exposures.reject { |_, | [:nested] }.select do |attribute, | valid_exposure?(attribute, ) end end |