Arguments

Description

Define arguments. Arguments can be bound to page, session and cookie variables. Argument values are passed into all server-side Xbasic event handlers in the component.

On the UX Properties page, clicking the button next to the Arguments property opens the 'Define Arguments' dialog.

The Arguments property
The Define Arguments dialog

Clicking the 'Insert New Argument' button will open the 'New Argument' dialog. Give the argument a name, choose a 'Data type', select Argument binding, and click OK to add an argument to the Existing Arguments list.

Adding a new argument to a UX

Now that there exist a defined argument, the Argument definition and Argument Binding settings will be unlocked.

An added argument named 'arg1'

 Using an IN Clause with Array Arguments in a SQL Statement

Once you have defined an argument you can then use it in a UX Component. The example below takes a countries list, generated from the NorthWinds database, and displays all of the customers for selected countries in a separate list. This is done using an IN clause and array arguments. You can also see this example on this video.

  1. Create a new UX component. Under the Select UX Component Template page choose "Start with a blank UX Component"

  2. Open the UX Controls page. Under the Data controls menu click on the [List] control.

    List control
  3. Give the list control the name "list_country" and click OK to add it to the component

  4. Add a second list control. Give this control the name "list_customer"

  5. Open the 'Other Controls' menu and click on [Static Text] control.

  6. The Static text control will appear. Find the 'Static Text Properties' section of the control properties list on the right side of the screen. Under this section, find the 'Static text' property and enter the following text "Select one or more countries".

  7. Go to the Defined Controls menu and double click the 'List-Record Count' control. This will also add a button to your component.

  8. Under the 'Other Controls' menu click on the [Button] control to add a button to the UX. In the control properties list under 'Button Properties' section, find the 'Button text' property and next to it write 'Clear selections'.

  9. Highlight an individual control and use the blue arrows in the toolbar to position it.

    The blue arrows
  10. Position the five controls in the following order.

  11. Highlight the bottom two controls and in the Containers menu click the [Container] control option.

  12. In the 'Insert Container' dialog leave the Container type set at 'None' and click OK.

  13. Now select the top three controls and place a second container around these. Your UX component should now look like this.

  14. Highlight the 'list_country' list control that you defined. In the control properties list find the 'List properties' Section. In this section find the "List properties" property and click the button next to it.

  15. Open the 'Data Source' tab. Under the Data Source Type: menu select SQL.

  16. Define the SQL Data Source using the following settings.

    • Under the connection string property connect to the Northwinds database.

    • Leave the 'Method for defining SQL query' set at 'Fields from table'.

    • For the Table name property click the button and select the 'Customers' table.

    • For the 'Field list' property select the 'Country' field.

    • For Order select 'Country' as well.

    • Check the 'Distinct' property checkbox. Your settings should look like this:

      The 'Distinct' property makes the SQL statement use a DISTINCT clause.
  17. Still on the Data Source page, scroll down to the 'Return Value' section. Click the button next to the 'Return field' property and set the return field to 'Country'

  18. Open the List Builder's 'List Properties' tab.

  19. In the List Properties section find the 'Multi-select' property and check it.

  20. In the same section, click the Multi-select mode dropdown and select "Click" (as opposed to Control-click).

  21. Open the List Layout tab and move Country from the Available Fields: list to Columns in List:

  22. Click on the 'List Events...' button at the bottom of the List Builder.

  23. Scroll down the events list until you get to the onClick event. Add the following Javascript to the work area

    {dialog.object}.refreshListData('list_customer');
  24. Click OK to close the events dialog and OK to close the List Builder.

  25. Back on the UX Controls page, highlight the [list_customer] list control that you defined.

  26. Again go to the List Properties section and click the button next to the 'List properties' property. The List Builder will open.

  27. On the Data Source tab Set the Data Source Type: to SQL.

  28. Find the Arguments section on the Data Source tab.

  29. Click the next to the arguments property. Click the 'Insert New Argument' button and create an argument named 'array_country'.

    • Create a new argument
  30. Set the value of the argument to "{list_country}"

  31. Configure the rest of the Data Source tab using the following settings.

    • Set the Method for defining SQL query to 'FieldsFromTable'

    • Set the 'Table name' to Customers

    • Select the following fields under Field list: 'CustomerID', 'CompanyName', 'Contact Name', 'City', and 'Country'

    • Under Filter create the filter Country IN (array_country)

    • Order should be set to 'Country'

  32. On the List Layout tab move the 'CustomerID', 'CompanyName', 'Contact Name', 'City', and 'Country' fields from 'Available Fields'' list to 'Columns in List'. Click OK to close the List Builder.

  33. Go to Live Preview and run your UX Component

    Countries clicked in the lefthand list will display customers from those countries and info on the right.

For more on arguments see 'Using Defined Arguments' in a grid component page and the SQL 'Using Arguments' section of the documentation.