Class: Bronto::Base

Inherits:
Object show all
Defined in:
lib/bronto/base.rb

Direct Known Subclasses

Contact, Delivery, Field, List, Message

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) ⇒ Base

Accepts a hash whose keys should be setters on the object.



150
151
152
153
 
# File 'lib/bronto/base.rb', line 150

def initialize(options = {})
  self.errors = Errors.new
  options.each { |k,v| send("#{k}=", v) if respond_to?("#{k}=") }
end

Instance Attribute Details

#errors ⇒ Object

Returns the value of attribute errors.



3
4
5
 
# File 'lib/bronto/base.rb', line 3

def errors
  @errors
end

#id ⇒ Object

Returns the value of attribute id.



3
4
5
 
# File 'lib/bronto/base.rb', line 3

def id
  @id
end

Class Method Details

.api ⇒ Object

Sets up the Savon SOAP client object (if necessary) and returns it.



39
40
41
42
43
44
45
46
 
# File 'lib/bronto/base.rb', line 39

def self.api
  return @api unless @api.nil?

  @api = Savon::Client.new do
    wsdl.endpoint = "https://api.bronto.com/v4"
    wsdl.namespace = "http://api.bronto.com/v4"
  end
end

.api_key ⇒ Object 



10
11
12
 
# File 'lib/bronto/base.rb', line 10

def self.api_key
  @@api_key
end

.api_key=(api_key) ⇒ Object

Getter/Setter for global API Key.



6
7
8
 
# File 'lib/bronto/base.rb', line 6

def self.api_key=(api_key)
  @@api_key = api_key
end

.create(*objs) ⇒ Object

Tells the remote server to create the passed in collection of Bronto::Base objects. The object should implement ‘to_hash` to return a hash in the format expected by the SOAP API.

Returns the same collection of objects that was passed in. Objects whose creation succeeded will be assigned the ID returned from Bronto.



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/bronto/base.rb', line 88

def self.create(*objs)
  objs = objs.flatten

  resp = request(:add) do
    soap.body = {
      plural_class_name => objs.map(&:to_hash)
    }
  end

  objs.each { |o| o.errors.clear }

  Array.wrap(resp[:return][:results]).each_with_index do |result, i|
    if result[:is_new] and !result[:is_error]
      objs[i].id = result[:id]
    elsif result[:is_error]
      objs[i].errors.add(result[:error_code], result[:error_string])
    end
  end

  objs
end

.destroy(*objs) ⇒ Object

Destroys a collection of Bronto::Base objects on the remote server.

Returns the same collection of objects that was passed in. Objects whose destruction succeeded will have a nil ID.



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/bronto/base.rb', line 129

def self.destroy(*objs)
  objs = objs.flatten

  resp = request(:delete) do
    soap.body = {
      plural_class_name => objs.map { |o| { id: o.id }}
    }
  end

  Array.wrap(resp[:return][:results]).each_with_index do |result, i|
    if result[:is_error]
      objs[i].errors.add(result[:error_code], result[:error_string])
    else
      objs[i].id = nil
    end
  end

  objs
end

.find(filter = Bronto::Filter.new, page_number = 1) ⇒ Object

Finds objects matching the ‘filter` (a Bronto::Filter instance).



75
76
77
78
79
80
81
 
# File 'lib/bronto/base.rb', line 75

def self.find(filter = Bronto::Filter.new, page_number = 1)
  resp = request(:read) do
    soap.body = { filter: filter.to_hash, page_number: page_number }
  end

  Array.wrap(resp[:return]).map { |hash| new(hash) }
end

.plural_class_name ⇒ Object

Simple helper method to convert class name to downcased pluralized version (e.g., Field -> fields).



15
16
17
 
# File 'lib/bronto/base.rb', line 15

def self.plural_class_name
  self.to_s.split("::").last.downcase.pluralize
end

.request(method, refresh_header = false, &_block) ⇒ Object

The primary method used to interface with the SOAP API. This method automatically adds the required session header and returns the actual response section of the SOAP response body.

If a symbol is passed in, it is converted to “method_plural_class_name” (e.g., :read => read_lists). A string method is used as-is. Pass in a block and assign a hash to soap.body with a structure appropriate to the method call.



25
26
27
28
29
30
31
32
33
34
35
36
 
# File 'lib/bronto/base.rb', line 25

def self.request(method, refresh_header = false, &_block)
  _soap_header = self.soap_header(refresh_header)

  method = "#{method}_#{plural_class_name}" if method.is_a? Symbol

  resp = api.request(:v4, method.to_sym) do
    soap.header = _soap_header
    evaluate(&_block) if _block # See Savon::Client#evaluate; necessary to preserve scope.
  end

  resp.body["#{method}_response".to_sym]
end

.save(*objs) ⇒ Object

Saves a collection of Bronto::Base objects. Objects without IDs are considered new and are ‘create`d; objects with IDs are considered existing and are `update`d.



62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/bronto/base.rb', line 62

def self.save(*objs)
  objs = objs.flatten
  updates = []
  creates = []

  objs.each { |o| (o.id.present? ? updates : creates) << o }

  update(updates) if updates.count > 0
  create(creates) if creates.count > 0
  objs
end

.soap_header(refresh = false) ⇒ Object

Helper method to retrieve the session ID and return a SOAP header. Will return a header with the same initial session ID unless the ‘refresh` argument is `true`.



50
51
52
53
54
55
56
57
58
 
# File 'lib/bronto/base.rb', line 50

def self.soap_header(refresh = false)
  return @soap_header if !refresh and @soap_header.present?

  resp = api.request(:v4, :login) do
    soap.body = { api_token: self.api_key }
  end

  @soap_header = { "v4:sessionHeader" => { session_id: resp.body[:login_response][:return] } }
end

.update(*objs) ⇒ Object

Updates a collection of Bronto::Base objects. The objects should exist on the remote server. The object should implement ‘to_hash` to return a hash in the format expected by the SOAP API.



112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/bronto/base.rb', line 112

def self.update(*objs)
  objs = objs.flatten

  resp = request(:update) do
    soap.body = {
      plural_class_name => objs.map(&:to_hash)
    }
  end

  objs.each { |o| o.errors.clear }
  objs
end

Instance Method Details

#create ⇒ Object

Creates the object. See ‘Bronto::Base.create` for more info.



188
189
190
191
 
# File 'lib/bronto/base.rb', line 188

def create
  res = self.class.create(self)
  res.first
end

#destroy ⇒ Object

Destroys the object. See ‘Bronto::Base.destroy` for more info.



199
200
201
 
# File 'lib/bronto/base.rb', line 199

def destroy
  self.class.destroy(self).first
end

#reload ⇒ Object 



165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/bronto/base.rb', line 165

def reload
  return if self.id.blank?

  # The block below is evaluated in a weird scope so we need to capture self as _self for use inside the block.
  _self = self

  resp = request(:read) do
    soap.body = { filter: { id: _self.id } }
  end

  resp[:return].each do |k, v|
    self.send("#{k}=", v) if self.respond_to? "#{k}="
  end

  nil
end

#request(method, &block) ⇒ Object

Convenience instance method that calls the class ‘request` method.



161
162
163
 
# File 'lib/bronto/base.rb', line 161

def request(method, &block)
  self.class.request(method, &block)
end

#save ⇒ Object

Saves the object. If the object has an ID, it is updated. Otherwise, it is created.



183
184
185
 
# File 'lib/bronto/base.rb', line 183

def save
  id.blank? ? create : update
end

#to_hash ⇒ Object

‘to_hash` should be overridden to provide a hash whose structure matches the structure expected by the API.



156
157
158
 
# File 'lib/bronto/base.rb', line 156

def to_hash
  {}
end

#update ⇒ Object

Updates the object. See ‘Bronto::Base.update` for more info.



194
195
196
 
# File 'lib/bronto/base.rb', line 194

def update
  self.class.update(self).first
end