Class: Pod4::Model

Inherits:
BasicModel show all
Defined in:
lib/pod4/model.rb

Overview

The parent of all models.

Models & Interfaces

Note that we distinguish between ‘models’ and ‘interfaces’:

The model represents the data to your application, in the format that makes most sense to your application: that might be the same format that it is stored in on the database, or it might not. The model doesn’t care about where the data comes from. Models are all subclasses of Pod4::Model.

An interface encapsulates the connection to whatever is providing the data.# it might be a wrapper for calls to the Sequel ORM, for example. Or it could be a making a series of calls to a set of Nebulous verbs. It only cares about dealing with the data source, and it is only called by the model.

An interface is a seperate class, which is defined for each model. There are parent classes for most of the data sources you will need, but failing that, you can always create one from the ultimate parent, Pod4::Interface.

Simple Example

The most basic example model (and interface):

class ExampleModel < Pod4::Model

  class ExampleInterface < Pod4::SequelInterface
    set_table :example
    set_id_fld :id
  end

  set_interface ExampleInterface.new($db)
  attr_columns :one, :two, :three
end

In this example we have a model that relies on the Sequel ORM to talk to a table ‘example’. The table has a primary key field ‘id’ and columns which correspond to our three attributes one, two and three. There is no validation or error control.

Here is an example of this model in use:

# find record 14; raise error otherwise. Update and save.
x = ExampleModel.new(14).read.or_die
x.two = "new value"
x.update

# create a new record from the params hash -- unless validation fails.
y = ExampleModel.new
y.set(params)
y.create unless y.model_status == :error

Overriding Column Representation

If you want to represent information differently on the model than it is stored on the data source, there are four methods you potentially need to know about and override:

  • set – used by you to set model column values

  • to_ot – used by you to get model column values

  • map_to_model – used by the model to set column values from the interface

  • map_to_interface – used by the model to set interface values

See the methods themselves for more detail.

Constant Summary

Constants inherited from BasicModel

BasicModel::STATII

Instance Attribute Summary

Attributes inherited from BasicModel

#model_id, #model_status

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from BasicModel

#alerts, #clear_alerts, #initialize, #interface, interface, #raise_exceptions, set_interface

Methods included from Metaxing

#define_class_method, #metaclass

Constructor Details

This class inherits a constructor from Pod4::BasicModel

Class Method Details

.attr_columns(*cols) ⇒ Object

You should call this in your model definition to define model ‘columns’ – it gives you exactly the functionality of ‘attr_accessor` but also registers the attribute as one that `to_ot`, `map_to_model` and `map_to_interface` will try to help you with.



87
88
89
90
91
92
 
# File 'lib/pod4/model.rb', line 87

def attr_columns(*cols)
  c = columns.dup
  c += cols
  define_class_method(:columns) {c}
  attr_accessor *cols
end

.columns ⇒ Object

Returns the list of columns from attr_columns



98
99
100
 
# File 'lib/pod4/model.rb', line 98

def columns 
  []
end

.fail_no_id ⇒ Object

Raises:



150
151
152
 
# File 'lib/pod4/model.rb', line 150

def fail_no_id
  raise Pod4Error, "ID field missing from record", caller
end

.fail_no_id_fld ⇒ Object

Raises:



145
146
147
 
# File 'lib/pod4/model.rb', line 145

def fail_no_id_fld
  raise Pod4Error, "No ID field defined in interface", caller
end

.list(params = nil) ⇒ Object

Call this to return an array of record information.

What you actually get depends on the interface, but it must include a recognisable record ID in each array element.

For the purposes of Model we assume that we can make an instance out of each array element, and we return an array of instances of the model.# Override this method if that is not true for your Interface.

Note that list should ALWAYS return an array, and array elements should always respond to :id – otherwise we raise a Pod4Error.



116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/pod4/model.rb', line 116

def list(params=nil)
  fail_no_id_fld unless interface.id_fld

  interface.list(params).map do |ot|
    key = ot[interface.id_fld]; fail_no_id unless key

    rec = self.new(key)
    rec.map_to_model(ot) # seperately, in case model forgot to return self
    rec 
  end

end

.test_for_invalid_status(action, status) ⇒ Object

Raises:



137
138
139
140
141
 
# File 'lib/pod4/model.rb', line 137

def test_for_invalid_status(action, status)
  raise( Pod4Error, "Invalid model status for an action of #{action}", caller ) \
    if [:empty, :deleted].include? status

end

.test_for_octo(param) ⇒ Object

Raises:

  • (ArgumentError) 


130
131
132
133
134
 
# File 'lib/pod4/model.rb', line 130

def test_for_octo(param)
  raise( ArgumentError, 'Parameter must be a Hash or Octothorpe', caller ) \
    unless param.kind_of?(Hash) || param.kind_of?(Octothorpe)

end

Instance Method Details

#columns ⇒ Object

Syntactic sugar; pretty much the same as self.class.columns, which returns the ‘attr_columns` array.



162
 
# File 'lib/pod4/model.rb', line 162

def columns; self.class.columns.dup; end

#create ⇒ Object

Call this to write a new record to the data source.

Note: create needs to set @id. But interface.create should return it, so that’s okay.



170
171
172
173
174
175
176
 
# File 'lib/pod4/model.rb', line 170

def create
  validate
  @model_id = interface.create(map_to_interface) unless @model_status == :error

  @model_status = :okay if @model_status == :empty
  self
end

#delete ⇒ Object

Call this to delete the record on the data source.

Note: does not delete the instance…



214
215
216
217
218
219
220
 
# File 'lib/pod4/model.rb', line 214

def delete
  Model.test_for_invalid_status(:delete, @model_status)
  clear_alerts; validate 
  interface.delete(@model_id) 
  @model_status = :deleted
  self
end

#map_to_interface ⇒ Object

used by the model to get an OT of column values for the interface.

Don’t use this to get model values in your code; use ‘to_ot`, instead.# This is called by model.create and model.update when it needs to write to the data source.

By default this behaves exactly the same as to_ot. Override it if you want the model to represent data differently than the data source – in which case you also need to override ‘map_to_model`.

Bear in mind that any attribute could be nil, and likely will be when ‘map_to_interface` is called from the create method.

See also: ‘to_ot`, `set`.



301
302
303
 
# File 'lib/pod4/model.rb', line 301

def map_to_interface
  Octothorpe.new(to_h)
end

#map_to_model(ot) ⇒ Object

Used by the interface to set the column values on the model.

Don’t use this to set model attributes from your code; use ‘set`, instead.

By default this does exactly the same as ‘set`. Override it if you want the model to represent data differently than the data source does – but then you will have to override `map_to_interface`, too, to convert the data back.

See also: ‘to_ot`, `map_to_model’



279
280
281
282
283
 
# File 'lib/pod4/model.rb', line 279

def map_to_model(ot)
  merge(ot)
  validate
  self
end

#read ⇒ Object

Call this to fetch the data for this instance from the data source



182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/pod4/model.rb', line 182

def read
  r = interface.read(@model_id)

  if r.empty?
    add_alert(:error, "Record ID '#@model_id' not found on the data source")
  else
    map_to_model(r)
    @model_status = :okay if @model_status == :empty
  end

  self
end

#set(ot) ⇒ Object

Set instance values on the model from a Hash or Octothorpe.

This is what your code calls when it wants to update the model. Override it if you need it to set anything not in attr_columns, or to control data types, etc.

You might want to put validation here, too, if what you are validating is something that isn’t actually stored on the model. You can call add_alert from here just fine.

See also: ‘to_ot`, `map_to_model`, `map_to_interface`



250
251
252
253
 
# File 'lib/pod4/model.rb', line 250

def set(ot)
  merge(ot)
  self
end

#to_ot ⇒ Object

Return an Octothorpe of all the attr_columns attributes.

Override if you want to return any extra data. (You will need to create a new Octothorpe.)

See also: ‘set`, `map_to_model’, ‘map_to_interface’



263
264
265
 
# File 'lib/pod4/model.rb', line 263

def to_ot
  Octothorpe.new(to_h)
end

#update ⇒ Object

Call this to update the data source with the current attribute values



199
200
201
202
203
204
205
206
 
# File 'lib/pod4/model.rb', line 199

def update
  Model.test_for_invalid_status(:update, @model_status)

  clear_alerts; validate 
  interface.update(@model_id, map_to_interface) unless @model_status == :error

  self
end

#validate ⇒ Object

Call this to validate the model.

Override this to add validation - calling ‘add_alert` for each problem.

Note that you can only validate what is actually stored on the model. If you want to check the data being passed to the model in ‘set`, you need to override that routine.

Also, you don’t have any way of telling whether you are currently creating a new record or updating an old one: override ‘create` and `update` respectively.



234
235
236
 
# File 'lib/pod4/model.rb', line 234

def validate
  # Holding pattern. All models should use super, in principal
end