Using Defined Arguments

Description

A common design practice is to filter a grid based on the value of an argument. A common design pattern is to print out the value of that argument in a freeform region that you place above or below the grid.

This example will show how this can be accomplished in Alpha Anywhere, using a freeform region above a filtered grid. First it will define two arguments and look at how to place those arguments in a filter expression. Next it will cover how to print the value from this expression to your grid. Finally it will cover how to put this information in a Client-side event.

To Start With: 

  1. Open Alphasports and the Grid Builder

  2. Select DBF under Data Source and in Query select the Customer Table.

Define an Argument: 

  1. In the Define Arguments dialog click Insert Argument .

  2. In the New Argument dialog give this argument the Argument Name 'st' and set its Data Type to Character . Click OK

  3. Under Argument Definition set the ' Get Argument Value from ' setting to ' Get value from variable '.

  4. Under Variable click the Variable button and open the New Variable dialog.

  5. Click Add New Variable . Next to Variable Name type pgstate. Click the Scope dropdown set the scope to ' Page Variable '. Click OK to close the new variable dialog.

  6. Now back in the Default Arguments Dialog, Go to the Variable settings and set the Default value to ma.

Define a Second Argument: 

  1. Click Insert Argument again to insert a second argument into the Default Arguments dialog's Existing Arguments list.

  2. In the New Argument dialog, give this argument the Argument Name 'ln'. Set its Data Type to Character . Click OK

  3. Under Argument Definition set the ' Get Argument Value from ' setting to ' Get value from variable '.

  4. Under Variable click the Variable button and open the New Variable dialog.

  5. Click Add New Variable . In Variable Name type 'varin'. Set the Scope drop-down to ' Page Variable '. Click OK to close the new variable dialog.

  6. In the Default Arguments Dialog, Set the Variable settings Default value to 'a'.

  7. Click OK to exit the Define Arguments Dialog.

    If these arguments had been bound to session variables the techniques used here could still be used but would not be necessary. Because they are bound to page variables the problem becomes more difficult.

Place the Arguments in a Filter Expression 

  1. On the Filter shown in the Design > Grid > Query page of your Grid Builder click the button to open the Expression Builder .

  2. Next double click on ' Argument ' in the Expression Builder menu, or hit F10 .

  3. From Insert Arguments dialog select 'st', click on it so that it is highlighted in blue. Then click OK

  4. Click the .AND. button in the Expression Builder to add this to your expression.

  5. Hit F2 and add a second field, this time select ' Lastname'.

  6. Place a greater than sign in the Expression , either via the keyboard or by clicking the greater than button.

  7. Finally, add you second Argument. Hit F10 opening the Insert Arguments dialog, and select 'ln' then click Insert . The Expression should look like this.

  8. Click OK to close the Expression Builder and add the Expression to your Query page.

Print the Value to the Grid. 

  1. On the Grid Builder's Design page menu click on Grid > Properties and open the Properties page.

  2. Scroll down to the Freeform Edit Regions properties and select the Above Grid Property. Click the button on the Above Grid row.

  3. This will open the Freeform Edit Region dialog. Copy and paste the following HTML into the edit region.

    Showing records in state:
    This html will show some text on the grid. Inside of the text there is also a a span with id of statename. This span will hold the value of the 'state' argument.
  4. Go to the Grid > Fields page in the Design menu. Open the page.

  5. Click the Insert... written below the Available Fields list to open the Insert Special Control dialog.

  6. Click [Button] control and then click OK .

  7. In the Field Properties list on the right side of the Grid > Fields page scroll down until you reach the Javascript Properties.

  8. Select the onClick property and click the button next to it.

  9. The Edit onClick Event Editor will appear. From the radio buttons at the top of the editor select Text mode .

  10. Copy and Paste the following code into the edit area. Click Save.

    var x = {Grid.object}.argumentValue('st');  
    alert(x);  
    $('statename').innerHTML = x;
    • When the button is clicked it will call a method called argumentValue(). This method gets the value of an argument that was passed into the Grid, i.e. an argument that you want to retrieve. You can see the argumentValue() method by first clicking the ' Insert grid method... ' at the bottom of the Edit onClick Event Editor. Start typing the name of the method into the filter and it should appear from the list of methods. In this example we are converting our argument into a javascript variable called x and then alerting it. We then set the innerHtml of the span (that had an id of 'statename') equal to x. Ultimately will put this into a client-side event.

  11. Now go to Working Preview. Notice the text 'Showing Records in State' at the top of the grid. Click on the Button that you created. A message with 'ma' will appear. Click OK .

  12. Now the Javascript fires, retrieves the value of the argument 'ma', and then sets the value of the span tag. You should see a 'ma' next to the Showing records in state text.

Put the Value of an Argument in a Client-side Event. 

  1. Go back to the Design tab and return to the Grid > Fields page. Go to the Field Properties > Javascript section and click on the button next to the onClick Event.

  2. Erase the code that you placed in the Edit onClick Event Editor and click Save.

  3. In the Design page menu, under Code , click on Client-side Events and open the Client-side Events page.

  4. Scroll down the list of Client-side Events until you find the onGridRenderComplete event near the bottom of the page. Highlight it.

  5. In the Javascript Event Handlers work area Paste the same code that you placed in the Edit onClick Event Editor. Delete the alert(x); so the code looks like this...

    var x = {Grid.object}.argumentValue('st');  
    $('statename').innerHTML = x;
  6. Click Save and run the Grid in Working Preview . You should see the value of the argument, 'ma' at the top of the screen.

    This shows how you can use a method of the grid object to retreive the value of any argument that was passed into the grid and has been used in the grid filter.

See Also