Reference Manual

The Model Module

Attention not to mistake ' . ' with ' : ' in Lua. ' : ' is a syntatic sugar when using Object-Orientated Programming, it means that the object itself will be sent as an argument to the function before the other arguments. Example: model.find_by_id( model, id ) = model:find_by_id( id ). To use these functions you will need first to generate the model through the built-in function sailor.model( ).

model:count( )

Returns the amount of objects of a desired model stored in the database. Returns a number.

Example:

-- In this case there must be a file inside /model called user.lua
local User = sailor.model( 'user' ) 
local n = User:count()

model:delete( )

Deletes the row corresponding to this object from the database.

Example:

-- In this case there must be a file inside /model called user.lua
local User = sailor.model( 'user' ) 
-- This will find the user with the id equal to 2.
local u = User:find_by_id( 2 )
-- This will delete this user from the db
u:delete()

model:find( where_string )

(NOT ESCAPED, DO NOT USE THIS FUNCTION UNLESS YOU WRITE THE WHERE_STRING YOURSELF) Finds an object based on the given part of the SQL query after the WHERE. Returns the object found or nil.

  • where_string: string that will go after 'WHERE' on your query.

Example:

-- In this case there must be a file inside /model called user.lua
local User = sailor.model( 'user' ) 
-- This will find the first user with age greater or equal than 42, ordered by descending order.
local u = User:find( "age >= 42 ORDER BY age DESC" )

model:find_all( )

(NOT ESCAPED, DO NOT USE THIS FUNCTION UNLESS YOU WRITE THE WHERE_STRING YOURSELF) Finds all objects based on the given part of the SQL query after the WHERE. Returns a table with the objects found or an empty table.

  • where_string: string that will go after 'WHERE' on your query.

Example:

-- In this case there must be a file inside /model called user.lua
local User = sailor.model( 'user' ) 
-- This will find all users with age greater or equal than 42, ordered by descending order.
local u = User:find_all( "age >= 42 ORDER BY age DESC" )

model:find_by_attributes( attributes )

(The values inside the table will be escaped) Finds one object with the given attributes. Returns the object found or nil. * attributes: table. Contains the attributes and the values to be used in the query.

Example:

-- In this case there must be a file inside /model called user.lua
local User = sailor.model( 'user' ) 
-- This will find one user with the attribute name equal to Carolina and age equal to 42.
local u = User:find_by_attributes( { name = 'Carolina', age = 42 } )

model:find_by_id( id )

(The alue passed will be escaped) Finds one object with the given id. Returns the object found or nil.

  • id: string or number. The id that will be compared to whatever attribute name that is set on your model as db.key.

Example:

-- In this case there must be a file inside /model called user.lua
local User = sailor.model( 'user' ) 
-- This will find the user with the id equal to 2.
local u = User:find_by_id( 2 )

model.generate_CRUD( model_name )

This will need the model module to be required. Generates a CRUD based on the given model, model must already exist. This function is used in the autogen module and will not correctly intepretate how plurals work in English so you might have to rename some things after the CRUD is created.

  • model_name: string, the name of the model.

Generated files are:

/controller/model_name.lua
/views/model_name/index.lp
/views/model_name/create.lp
/views/model_name/update.lp
/views/model_name/view.lp

model.generate_model( table_name )

This will need the model module to be required. Generates a model based on a given table. This function is used in the autogen module and will not autogenerate model's relations or attributes' rules. A file with the same name of the table will be created under /model.

  • table_name, the name of the table

model:get_post( POST )

Will read through POST and search for information posted via sailor's form module and apply them to object. Works based on the fact that input names generated by the form module follow a certain format.

  • POST: table containing the post information. Usually page.POST.

Example:

-- In this case there must be a file inside /model called user.lua
local User = sailor.model( 'user' ) local u = User:new( )
u:get_post( page.POST )
if u:save() then 
    --do something
end

model:new( )

Returns an instantiated object based on a given model.

Example:

-- In this case there must be a file inside /model called user.lua
local User = sailor.model( 'user' ) 
local u = User:new( )

model:save( validate )

Persists the model to the database. If the object is a new object it will insert, otherwise it will update. Returns a boolean to indicate if the object was saved and a table containing validation errors.

  • validate: boolean. Default is true. Set to false if you wish to skip validating before saving.

Example:

-- In this case there must be a file inside /model called user.lua
local User = sailor.model( 'user' ) 
local u = User:new( )
-- And this model must have an attribute called name. 
u.name = 'Geronimo'local saved, err = u:save( )

model:validate( )

Verifies if object's attributes comply to specified rules on model. Returns a boolean to indicate if its valid or not and a table with validation errors.

Example:

-- In this case there must be a file inside /model called user.lua
-- Let's suppose your model has an attribute called email with a validation rule saying it needs to be a valid email.
local User = sailor.model( 'user' ) local u = User:new( )
u.email = 'aaaaa'local valid, err = u:validate( ) -- false, {"email is not a valid email address."}
u.email = 'aaa@aaa.com'local valid, err = u:validate( ) -- true, {}