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.set("country", "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>"
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.set("Arg1", "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")