Overriding parameter values
The general idea is to make data sets, fragments, templates, etc. more reusable.
Example to illustrate this:
Let's say we have a database with two tables in it: "Company" and "Employee" linked by one-to-many relationship.
Now we want to create two documents:
- "EmployeesDocument" - listing all employees of the company specified by the $P{companyId} parameter.
- "CompaniesDocument" - listing all companies and for each of them listing its employees (nested iteration), no parameters required in this case.
So, for the first document (EmployeesDocument), we need to create a data set, let's say "employeesDs1", defined as: select * from Employee where company_id=$P{companyId}
and then in the document we would have something like:
$iterateRows{employeesDs1}
<oo table>
Now, for the second document (CompaniesDocument), we need to create another two data sets, more or less like that:
"companiesDs" : select * from Company
"employeesDs2" : select * from Employee where
company_id=$F{companiesDs.companyId}
and in the document "CompaniesDocument" we would have:
$iterateRows{companiesDs}
<oo table>
$iterateRows{employeeDs2}
<oo table>
The drawback of this is that we had to create two almost identical data sets: "employeesDs1" and "employeesDs2", which differ only by the "object" used in the "where" clause which is $P{companyId} in the first case and $F{companiesDs.company_id} in the second one. The same problem applies to fragments and templates (especially when a table template "content of a cell" is to be used). For instance, at the moment it isn't possible to create a letter fragment, let's say showing user details, and use it (include it) twice for two different users in a single document; two separate letter fragments must to be created.
One possible way of solving that would be to introduce a new handler, e.g. $params{...}, that could be passed as an argument to any other handler (as long as it makes sense). This new handler ($params) would change the parameter values for the scope of a handler that it's been passed to. The syntax could be: $params{param_name_1:new_value_1,
param_name_2:param_value_2, ...}
So, for the example above, instead of defining two data sets (employeeDs1 and employeeDs2) we could define just one: employeeDs =
select * from Employee where company_id=$P{companyId}
and in the second document (CompaniesDocument) we could use it like this:
$iterateRows{companiesDs}
<oo table>
$iterateRows{employeeDs, $params{companyId:$F{companiesDs.companyId} }
<oo table>
Or, in case of letter fragments, we would use something like:
$fragment{userDetails, $params{userId:$P{userId1} }
...
$fragment{userDetails, $params{userId:$P{UserId2} }
instead of creating two or more separate letter fragments (one for each user) and referring to them as:
$fragment{userDetails1} , $fragment{userDetails2}, etc...
In case the $params argument wouldn't be passed to a handler everything would work as it was before, i.e. parameter values would be retrieved from the "original context".
