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.

images/arg1.png
The Arguments property
images/arg2.png
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.

images/arg4.png
Adding a new argument to a UX

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

images/arg3.png
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 Northwind 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.

    images/argstep15.png
    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.

    images/argstep16.png
    The blue arrows
  10. Position the five controls in the following order.

    images/argstep.png
  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.

    images/argstep2.png
  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.

    images/argstep4.png
  16. Define the SQL Data Source using the following settings.

    • Under the connection string property connect to the Northwind 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:

      images/argstep3.png
      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'

    images/argstep5.png
  18. Open the List Builder's 'List Properties' tab.

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

    images/argstep7.png
  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');
    images/argstep8.png
  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.

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

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

    • images/argstep11.png
  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'

      images/argstep13.png
  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

    images/argstep14.png
    Countries clicked in the list on the left 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.

Creating an Argument for the Current User's ID or Security Groups

When you define Arguments, you can bind an argument to the id of the currently logged in user or the security groups of the currently logged in user.

In the case where you bind an argument to the security groups for the logged in user, you must define an array argument. A user can be a member of multiple groups. By defining an array argument (the argument name must start with ARRAY_), the argument can be used in a SQL IN clause. For example

SELECT * FROM tasklist WHERE group IN (:ARRAY_UserSecurityGroups)

If you are using Active Directory, or IIS (with the Alpha Anywhere plugin), the Security Groups are the actual names of the security groups. In the case of the classic Alpha Anywhere server, the security groups are the GUIDs for each group.

To specify that an argument gets its value from the currently logged in user, set the Get argument value from property to Get value for current logged in user. Then set the Value property to one of the following options.

Value Option
Description
CurrentLoggedInUserName

The user ID for the currently logged in user.

CurrentLoggedInUserGroups

The groups for the currently logged in user. A user may belong to multiple groups. Specify the Argument as an array argument by prefixing the argument's name with ARRAY_. E.g. ARRAY_UserSecurityGroups.

/documentation/pages/images/general/args_currentuser1.jpg

Using Extended User Information in Arguments

If you have defined an Extended User Information Table for the current project, the Select Field dialog for the Value property will include fields defined in the Extended User Information Table. You can bind an argument to any value from the Extended User Information Table. The available fields will be listed after the CurrentLoggedInUserName and CurrentLoggedInUserGroups choices.

/documentation/pages/images/general/args_currentuser2.jpg

See Also