onLogin

Description

Fires after the user has been authenticated.

Discussion

The onLogin event is triggered when the user logins in using the integrated login feature in the UX Component. The event fires regardless of whether the authentication was successful or not.

The e.loginSucceeded flag indicates if the login was successful or not. An important use of this event is to force a reload of the component on login. See the discussion below on 'Forcing a Reload of the UX Component After Login' for more details.

This event can also be used to set the 'friendly user name'. The 'friendly user name' is made available in client-side 'afterLogin' event. It can also be used in client-side watch expressions.

Variables 

Variables in the 'e' object include:

e.username

user name entered by user to log in

e.loginSucceeded

either .t. or .f. depending on whether the user was successfully logged in or not.

e.flagUserWasAlreadyLoggedIn

if the user was already logged in when the page was initially loaded, this flag is .t.

e.errorText

error message if login failed

e.tmpl

definition of the UX component

Your event handler can set these variables:

e.userNameFriendly

This is the value that will be used in the 'FriendlyName' property passed to the client-side 'afterLogin' event.

e.javascript

any Javascript you want to execute

e.url

(optional) the target URL after a successful login. TIP: To reload the current component after a successful login, set e.url to '<thisComponent>'

e._state

(optional) a dot variable used to set/create state variables. The value of any state variables will be available in all subsequent ajax callbacks.

e.arguments

SQL::Arguments object with values for each of the arguments defined in this component. To read a value from arguments: e.arguments.find("argumentName").data. You can also set the value of an argument. For example: e.arguments[e.arguments.ArgumentNumber("country")].data = "portugal"

e._set

(optional) Used to set property values for controls in the UX Component.

e.control

(optional) Used to set the initial value of any field by setting the property

Forcing a Reload of the UX Component After Login 

After the user has logged in you might want to force the UX component to reload. Consider the following scenario which explains a use case for this option:

Assume that the application you have built is a single UX component, and it has integrated login functionality. Assume also that this component has certain controls that have security on them (for example a 'Set Salary' button that is only visible to member of the 'Manager' group).

When the UX is initially loaded, the 'Set Salary' button will not be visible (because the user is not yet logged in).

Now assume that the user enters their username and password and clicks the login button. This will fire an Ajax callback and the user will be authenticated. Assume that the user is now authenticated and is part of the 'Manager' group.

This user should now see the 'Set Salary' button, but does not because when the UX was originally rendered, the user was not logged in.

However, by forcing a reload after login, the component will be re-rendered on the server and the user will see the 'Set salary' button.

The way in which you force a reload of the UX component after login is by setting the e.url property in the onLogin server-side event. For example, you could add this code to the onLogin server-side event:

e.url = "<thisComponent>"
If you are forcing a reload after the UX component loads, you will likely also want to set the 'Logout does full page reload' property to true.

Setting State Variables 

State variables can be set in the onLogin event. State variables can be added to the e._state variable. State variables are available in subsequent Ajax callbacks.

e._state.loginTime = time("dd/MM/yyyy 0h:0m am", now())

Example: Setting Arguments and Control Properties 

' set the value of Arg1 to Portugal:
e.arguments[e.arguments.ArgumentNumber("Arg1")].data = "Portugal"

' set the value property for the field1 control:
e._set.field1.value = "foo"

Example: Setting the Initial Value for Controls 

You can set the initial value of any field by setting the property e.control.<fieldname>. For example:

e.control.firstname = "Fred"
e.control.lastname = "Jones"

For multi-valued controls (such as checkbox, List control configured as multi-select, etc.) you can set the value to a cr-lf list of values or use the special array() syntax. Either of the following two methods will work:

e.control.colors = "array(red,green)"
e.control.colors = comma_to_crlf("red,green")