Class: GrapeEntity::Entity
- Inherits:
-
Object
- Object
- GrapeEntity::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
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.
-
.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.
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
Constructor Details
#initialize(object, options = {}) ⇒ Entity
Returns a new instance of Entity.
287 288 289 |
# File 'lib/grape_entity/entity.rb', line 287 def initialize(object, = {}) @object, @options = object, end |
Instance Attribute Details
#object ⇒ Object (readonly)
Returns the value of attribute object.
42 43 44 |
# File 'lib/grape_entity/entity.rb', line 42 def object @object end |
#options ⇒ Object (readonly)
Returns the value of attribute options.
42 43 44 |
# File 'lib/grape_entity/entity.rb', line 42 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.
156 157 158 159 160 161 162 163 164 165 166 167 168 169 |
# File 'lib/grape_entity/entity.rb', line 156 def self.documentation @documentation ||= exposures.inject({}) do |memo, value| unless value[1][:documentation].nil? || value[1][:documentation].empty? memo[value[0]] = value[1][: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.
123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 |
# File 'lib/grape_entity/entity.rb', line 123 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? args.each do |attribute| exposures[attribute.to_sym] = 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.
143 144 145 146 147 148 149 150 151 |
# File 'lib/grape_entity/entity.rb', line 143 def self.exposures @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.
199 200 201 202 |
# File 'lib/grape_entity/entity.rb', line 199 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.
205 206 207 208 209 210 211 212 213 |
# File 'lib/grape_entity/entity.rb', line 205 def self.formatters @formatters ||= {} if superclass.respond_to? :formatters @formatters = superclass.formatters.merge(@formatters) end @formatters 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.
entity. Pass nil or false to represent the object or objects with no root name even if one is defined for the entity.
272 273 274 275 276 277 278 279 280 281 282 283 284 285 |
# File 'lib/grape_entity/entity.rb', line 272 def self.represent(objects, = {}) inner = if objects.respond_to?(:to_ary) objects.to_ary().map{|o| self.new(o, {:collection => true}.merge())} else self.new(objects, ) end root_element = if .has_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.
254 255 256 257 |
# File 'lib/grape_entity/entity.rb', line 254 def self.root(plural, singular=nil) @collection_root = plural @root = singular end |
Instance Method Details
#documentation ⇒ Object
295 296 297 |
# File 'lib/grape_entity/entity.rb', line 295 def documentation self.class.documentation end |
#exposures ⇒ Object
291 292 293 |
# File 'lib/grape_entity/entity.rb', line 291 def exposures self.class.exposures end |
#formatters ⇒ Object
299 300 301 |
# File 'lib/grape_entity/entity.rb', line 299 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.
310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 |
# File 'lib/grape_entity/entity.rb', line 310 def serializable_hash( = {}) return nil if object.nil? opts = .merge( || {}) exposures.inject({}) do |output, (attribute, )| if (.has_key?(:proc) || object.respond_to?(attribute)) && conditions_met?(, opts) partial_output = value_for(attribute, opts) output[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} else partial_output end end output end end |
#to_json(options = {}) ⇒ Object
331 332 333 334 |
# File 'lib/grape_entity/entity.rb', line 331 def to_json( = {}) = .to_h if && .respond_to?(:to_h) MultiJson.dump(serializable_hash()) end |
#to_xml(options = {}) ⇒ Object
336 337 338 339 |
# File 'lib/grape_entity/entity.rb', line 336 def to_xml( = {}) = .to_h if && .respond_to?(:to_h) serializable_hash().to_xml() end |