a5_mergeDataIntoTemplate Function

Syntax

C Result = a5_mergeDataIntoTemplate(C template ,* dataSource [,* mergeResult [,* localFunctions ]])

Arguments

template: HTML temple
dataSource: Data source
mergeResult: (optional) Pointer variable to return .hasErrors, .t. or .f., and .errorText, a list of errors that were encountered. Defaults to a null value.
localFunctions: *

Description

Merge data into a template.

Data source can be:

a) An Xbasic property array
b) A pointer to an open .dbf table,
c) An SQL result set.

Template uses {ds.data("fieldname")} to reference a field from the data source. Can include Xbasic expressions in { }. E.g

{ut(ds.data("fieldname"))}, {date())

When merging data into an HTML template, use the a5_html_label() function to escape HTML characters. For example:

{a5_html_label(ds.data("Notes"))}

Use {rowNumber} for current row. mergeResult.rows = number of rows that were merged

The template can include any Xbasic function between curly brackets. To reference a field from the passed-in data source, the template uses this syntax:

{ds.data("fieldname")}

For example, assume that the passed-in data source has a field called 'firstname'. To get the value of the firstname field, your template would use this syntax:

{ds.data("firstname")}

To convert firstname to uppercase, you would add the upper() function to the template:

{ut(ds.data("firstname"))}

If the template was HTML and you wanted to escape HTML characters in the data, you would use this:

{a5_html_label(ds.data("firstname"))}

You can include expressions in curly brackets that have nothing to do with data, for example, to put today's data in the template:

{date()}

The most common reason for using the mergeResult pointer is to detect templates that refer to fields that are not in the data source, often because of a typo.

The following examples show how to use the function:

template = <<%html%
<li>
    Name: {ut(ds.data("firstname"))} {ds.data("lastname")}
</li>
%html%


dim dataSource[0] as p
i = dataSource.append()
dataSource[i].firstname = "John"
dataSource[i].lastname = "Jones"
 
i = dataSource.append()
dataSource[i].firstname = "Richard"
dataSource[i].lastname = "Smith"

'Merge data into the template. Array has a size of 2, so template will appear
'twice (with merged data) in the output.
 
dim htmlstring as c
htmlstring = a5_mergeDataIntoTemplate(template,dataSource)

If you examine htmlstring you see:

<li>
    Name: JOHN Jones
</li>
<li>
    Name: RICHARD Smith
</li>

In this next example, the data source is an AlphaDAO resultset.

delete cn 
dim cn as sql::Connection
cn.open("firstname")
?cn.Execute("firstname")
= .T.
rs = cn.ResultSet
dim html as c 
html =a5_mergeDataIntoTemplate(template,rs)

In this next example, the data source is a .dbf table:

dim tbl as p
dim res as p
tbl = table.open("::Name::mysql_alphasports")
tbl.query_create("select * from customer where bill_city = 'boston'")
dim html as c 
html =a5_mergeDataIntoTemplate(template,tbl,res)
if res.hasErrors then
    ui_dlg_box("customer",res.errorText)
end if

In this next example, the data source is a string of JSON data:

dim jsonTxt as c
jsonTXT = <<%txt%
{firstname : 'John', lastname : 'Jones'},
{firstname: 'Richard', lastname: 'Smith'}
%txt%
 
dim html as c 
html =a5_mergeDataIntoTemplate(template,jsonTxt)

In this final example, we demonstrate the use of user-defined local Xbasic functions:

'Create a string with some locally defined functions
dim Xbasic as c 
Xbasic = <<%code%
    function myxb1 as c (data as c )
        myxb1 = "XXX:" + data 
    end function 

    function myUT as c (data as c)
        myUT = ut(data)
    end function 
%code%
 
'Compile the local functions
dim lf as p
lf = compile_template(Xbasic)
 
'The template references the local functions. Note that in order to reference
'a locally defined function, the function name is prefixed with 'lf.' 
template = <<%html%
<li>
Name: {lf.myUT(ds.data("firstname"))} {lf.myxb1(ds.data("lastname"))}
</li>
%html%

dim dataSource[0] as p
i = dataSource.append()
dataSource[i].firstname = "John"
dataSource[i].lastname = "Jones"

i = dataSource.append()
dataSource[i].firstname = "Richard"
dataSource[i].lastname = "Smith"
 
dim result as p 
dim htmlstring as c
'call the a5_mergeDataIntoTemplate() function and pass in a pointer to the
'locally defined functions
htmlstring = a5_mergeDataIntoTemplate(template,dataSource,result,lf)

Htmlstring will look like this:

<li>
Name: JOHN XXX:Jones
</li>
<li>
Name: RICHARD XXX:Smith
</li>