Copyright © Yariv Sadan 2006-2007
Authors: Yariv Sadan (yarivsblog@gmail.com) [web site: http://yarivsblog.com)].
| to_recs/2 | to_recs/2 helps process POST requests containing fields that belong to multiple records from one or more ErlyDB models. |
| validate/3 | validate/3 helps validate the inputs of arbitary forms. |
| validate1/3 | validate1/3 is similar to validate/3, but it expects the parameter list to match the field list both in the number of elements and in their order. |
| validate_rec/2 | When a form has fields that correspond to the fields of an ErlyDB record, validate_rec/2 helps validate the values of the record's fields. |
to_recs(A::arg() | [{ParamName::string(), ParamVal::term()}], ModelDescs::[{Prefix::string(), Model::atom()}]) -> [Record::tuple()]
to_recs/2 helps process POST requests containing fields that belong to multiple records from one or more ErlyDB models.
This function is useful when erlydb_base:new_fields_from_strs/3
isn't sufficient because the latter is only designed to map POST
parameters to the fields of a single record.
This function expects each form field to be mapped to its corresponding record by being named with a unique prefix identifying the record to which the form field belongs.
For example, suppose you have to process an HTML form whose fields represent a house and 2 cars. The house's fields have the prefix "house_" and the cars' fields have the prefixes "car1_" and "car2_". The arg's POST parameters are[{"house_rooms", "3"}, {"car1_year", "2007"}, {"car2_year", "2006"}].
With such a setup, calling to_recs(A, [{"house_", house}, {"car1_", car},
{"car2_", car}])
returns the list [House, Car1, Car2], where house:rooms(House) == "3",
car:year(Car1) == "2007" and car:year(Car2) == "2006". All other
fields are undefined.
validate(A::arg() | proplist(), Fields::[string()], Fun::function()) -> {Values::[term()], Errors::[term()]} | exit({missing_param, Field})
validate/3 helps validate the inputs of arbitary forms. It accepts a Yaws arg (or the arg's POST data in the form of a name-value property list), a list of parameter names to validate, and a validation function, and returns a tuple of the form {Values, Errors}. 'Values' contains the list of values for the checked parameters and 'Errors' is a list of errors returned from the validation function. If no validation errors occured, this list is empty.
If the name of a field is missing from the arg's POST data, this function calls exit({missing_param, Name}).
The validation function takes two parameters: the parameter name and its value, and it may return one of the following values:
- ok means the parameter's value is valid
- {ok, Val} means the parameter's value is valid, and it also lets you
set the value inserted into 'Values' for this parameter.
- {error, Err} indicates the parameter didn't validate. Err is inserted
into 'Errors'.
- {error, Err, Val} indicates the parameter didn't validate. Err is
inserted into 'Errors' and Val is inserted into 'Values' instead of
the parameter's original value.
to_recs/2.
validate1(Params::proplist() | arg(), Fields::[string()], Fun::function()) -> {Vals, Errs} | exit({missing_params, [string()]}) | exit({unexpected_params, proplist()}) | exit({unexpected_param, string()})
validate1/3 is similar to validate/3, but it expects the parameter list to match the field list both in the number of elements and in their order. validate1/3 is more efficient and is also stricter than validate/3.
See also: validate/3.
validate_rec(Rec::erlydb_record(), Fun::function()) -> {Rec1::erlydb_record(), Errs::[term()]}
When a form has fields that correspond to the fields of an ErlyDB record, validate_rec/2 helps validate the values of the record's fields.
validate_rec/2 accepts an ErlyDB record and a validation function.
It folds over all the fields of the record (obtained by calling
erlydb_base:db_field_names/0), calling the validation function
with each field's existing value. The validation function's
return value indicates if the field's value is valid,
and it may also define the record field's final value.
The result of validate_rec/2 is a tuple of the form {Rec1, Errs}, where
the first element is the modified record and the second element is
a list of errors accumulated by the calls to the validation function.
The validation function takes 3 parameters: the field name (an atom),
the current value (this can be any term, but it's usually a string,
especially if the record came from to_recs/2), and the record
after folding over all the previous fields. It returns
ok, {ok, NewVal}, {error, Err}, or {error, Err, NewVal}.
to_recs/2.
A common pattern is to create the records for the submitted form using
to_recs/2 and then validate their fields using validate_rec/2.