Parent | Child | Previous | Next
 

Custom Alternate View

Description

The custom alternate Grid view allows you create expressions that will be processed from the data in the grid display and an Xbasic function to turn the arrays of expression values into an actual view. This is the infrastructure that allowed Alpha Software to turn a Google Map Component into a Google Map alternate view.

Before you define an alternate view, you need to know what you're defining. Once you've got your goal in mind, you can list the data you'll need to collect, and figure out how you'll process the data to display the alternate view. In many cases, you will want to use a predefined widget that has a JavaScript API, and you will generate the HTML to house the JavaScript widget as well as the JavaScript to add the collected data to the widget .

  1. The first step in defining the alternate view to Alpha Anywhere is to check Has Alternate View in the grid properties.

    images/has_alternate_views.png

  2. In the Alternate View Builder, add an alternate view and select Custom for your Alternate View type.

    images/01_AlternateViewCustom1.png

  3. Click on the Xbasic function property

  4. The alternate view definition is a combination of one or more data expressions for collecting the data and an Xbasic function for processing the collected data.

    images/01_AlternateViewCustom2.png

  5. Once you type in the name of the Xbasic function you want to use, the "Show function prototype" link will be enabled. Click on that link and Alpha Anywhere will generate a commented prototype function for you.

    • images/01_AlternateViewCustom3.png
    • images/01_AlternateViewCustom4.png
    It is worthwhile reading the prototype function carefully so that you can understand the flow of data in the alternate view.

  6. Click on the "Copy to clipboard" button, close the function prototype,

    images/01_AlternateViewCustom5.png

  7. click on "Open Xbasic Function Declarations",

    images/01_AlternateViewCustom6.png

  8. and paste your function. You can edit your Xbasic function to generate the required HTML and JavaScript for your view. It's a good idea to create sample data and a sample function call that you can use to test your function. When your function is working properly, you can comment out the sample data and sample function call.

    images/01_AlternateViewCustom7.png

  9. You'll also have to create one or more data expressions. The next section explains why data expressions are necessary.

Custom Alternate View Data

When the Grid is rendered, Alpha Anywhere performs these steps:

  1. Execute a query to find records that satisfy the search criteria.

  2. Navigate to the correct starting record in the query (for example, if the Grid is showing 20 records per page, and you navigate to page 3, the starting record will be record number 41).

  3. Loop over the records in query, generating the HTML to show the Grid (This is called the 'Main Loop').

  4. The loop continues until you have generated the desired number of rows (based in the 'Rows per page' property), or you reach the last record in the query.

While the Main Loop is executing, you can capture additional information from each record in the query.

The way in which you specify what additional information you want to capture is by specifying one or more expressions that should be evaluated in the Main Loop.

The expressions are evaluated, and the expression results are placed into arrays (called 'value arrays'). There will be one value array for each expression that you specify. Each value array will have one entry for each row that is displayed in the Grid. So, for example, if the Grid is set to display 20 rows per page, each array will have 20 entries.

Once the Main Loop has completed, the Xbasic function that you specified for the Alternate View is called and the value arrays are passed into the Xbasic function. The Xbasic function can then use the data in the value arrays to compute the HTML to display in the Alternate View.

When you specify the expressions that you want to evaluate, you can define several types of expressions:

  • Regular Xbasic expressions. Use this syntax to reference a field value in the query: tbl.data("fieldname")
  • Templates. The template is a text string that can include Xbasic expressions. For example: {tbl.data("fieldname")}. The data enclosed in the curly brackets can be any Xbasic expression.
  • Function. Specify the name of an Xbasic function that will return the value you want to capture. The function prototype will be: YourFunctionName (e)

Alternate View Xbasic Data Expressions

Alternate View expressions are written in Xbasic. Your expression will typically need to reference field values from the Grid query. To reference a field value in the current Grid query, i.e. data from the row, use this syntax:

tbl.data("fieldname")
The field value that you read using the above syntax is correctly typed. For example, it will be a character, numeric, time, date, etc. value.

Here are some example expressions:

tbl.data("firstname") + ", " + tbl.data("lastname")
upper(tbl.data("lastname"))
time ("Mon dd yyy", tbl.data("orderDate"))
"User Name:" + upper(tbl.data("lastname"))

Alternate View Data Templates

A data template is a string of HTML, XML, or JSON that contains placeholders for fields from the current row in the Grid query. Placeholders can be added for both fields and Xbasic expressions.

To insert a placeholder for a field/expression into the template, enclose the expression in curly braces. For example, to insert a field into a template:

{tbl.data("fieldname")}

Note that the field value is referenced using an Xbasic expression:

tbl.data("fieldname")

The expression enclosed in the curly braces can be arbitrarily complex. For example, the expression shown below demonstrates adding 10 days to an order date:

Your order will ship on {tbl.data("orderDate") + 10}

Here are some example templates:

<tr><td>{upper(tbl.data("lastname") + ", " + tbl.data("firstname"))}</td></tr>
Customer Name: {tbl.data("firstname") + " " + tbl.data("lastname")}

Alternate View Data Functions

In most cases, a data expression or template is sufficient to capture the necessary information from the current record in the Grid query. However, there are situations where more control is needed over how the data from the current row is captured. An Xbasic function can be defined to create the data expression.

To use an Xbasic function, specify the name of the Xbasic function to call when defining the data expression:

images/01_AlternateViewCustom_func1.png

The function must be defined in the Xbasic Function Declarations section for the Grid Component. The Function prototype link can be used to create a function prototype after you enter the function name in the text box. The function prototype can be copied and then pasted into the Xbasic Code section using the Open Xbasic Function Declarations link.

images/data_collector_function_prototype.png

The function prototype takes a single argument, e (which is of type P). The e object contains a pointer to the tbl object, which can be used to access data in the table/result set for the current row in the Grid query.

The following example shows a custom Xbasic function to capture data from the current row in the Grid query:

function MySpecialFunction as c (e as p)
    dim tlb as P
    tbl = e.tbl

    dim txt as C = ""

    if (tbl.data("company") = "") then
        txt = "Company name not specified"
    else
        txt = "Company Name: " + tbl.data("company")
    end if

    MySpecialFunction = txt
end function