+Show TOC
×Hide TOC

LoginBox

Kind of class:	public class
Package:	com.smartfoxserver.smartfoxbits.bits
Inherits from:	UIComponent
Version:	1.0
Author:	The gotoAndPlay() Team http://www.smartfoxserver.com http://www.gotoandplay.it
Classpath:	com.smartfoxserver.smartfoxbits.bits.LoginBox
File last modified:	Wednesday, 15 April 2009, 19:01:18

The LoginBox class provides the public APIs to interact with the SmartFoxBits LoginBox control at author-time and run-time.

The SmartFoxBits Connector control let the user log in to the specified "zone" on the currently connected SmartFoxServer instance.
The control contains two textfields to input a username and a password, and a login button. As for all the other SmartFoxBits controls, these form items are Flex controls which can be accessed to set their properties (check the Flex documentation for controls styling operations).
The LoginBox can be customized by setting the form layout (seven different layouts available) and the text inputs labels, and by hiding the password field. You can also make it invisible until a connection with the server is set, and make it disappear after a successful login.

The LoginBox doesn't feature advanced, database driven user identification on its own, but it can make use of an external custom server-side validation system.
Set the customLoginPage property to the url of a server-side page which can perform the access validation and return the result to the LoginBox. Please notice that this validation is performed before attempting the SmartFoxServer login.

Both username and password are optional. If no username is provided, the server automatically creates a name for the user using the format "guest_n", where n is a progressive number.
You can avoid this behavior and force users to enter their own nickname by setting the noGuestLoginMsg property to display an error message.
If a password is provided, username and password are checked against the moderators list (configured in the SmartFoxServer config.xml file on the server side) and, if matching, the user is set as a Moderator.

NOTE: in the provided examples, loginBox always indicates a LoginBox instance.

Usage:

Add the "SmartFoxBits base Pack.swc" file to the Library Path in your Flex project properties: the SmartFoxBits category will appear in the Flex Components panel.
Drag the LoginBox control from the Components panel and drop it in the Flex Design View. The LoginBox properties can be set in Flex Properties panel or in the Source View (by editing the MXML tag) at author-time.
The LoginBox instance can also be created and its properties set at run-time, using ActionScript.
The LoginBox communicates with SmartFoxServer through the Connector control: read the Connector's class description for additional informations.
During run-time usage, as soon as a connection is available, the form fields are enabled and the user can enter his/her own credentials and hit the button (or the Enter key) to login.
If an error occurs (username already existing, for example) an error message is displayed (NOTE: if the zone property is not set, or it is set to a wrong value, no error is displayed).
Styling
The following styles are available for the LoginBox control:
gap
paddingBottom
paddingLeft
paddingRight
paddingTop
Styles can be applied using the standard Flex styling systems. Check the Flex documentation for additional informations.

Example:

To instantiate the LoginBox at author-time via MXML, write the following:

<sfb:LoginBox id="loginBox" zone="simpleChat" />

To instantiate the LoginBox at run-time write the following:

import com.smartfoxserver.smartfoxbits.bits.LoginBox

// Create LoginBox instance
var loginBox:LoginBox = new LoginBox()

// Set the SmartFoxServer zone to connect to
loginBox.zone = "simpleChat"

// Add LoginBox instance to the display list
addChild(loginBox)

Summary

Constructor

LoginBox

Constants

LAYOUT_ROW : String
- Login form layout: input fields and button in a row with labels above the input fields, left aligned.
LAYOUT_COLUMN_LEFT : String
- Login form layout: input fields, labels and button draw up in column, left aligned.
LAYOUT_COLUMN_CENTER : String
- Login form layout: input fields, labels and button draw up in column, center aligned.
LAYOUT_COLUMN_RIGHT : String
- Login form layout: input fields, labels and button draw up in column, right aligned.
LAYOUT_SIDE_TOP : String
- Login form layout: input fields and labels draw up in column, left aligned; login button on their right side, aligned to the username input field.
LAYOUT_SIDE_MIDDLE : String
- Login form layout: input fields and labels draw up in column, left aligned; login button on their right side, centered between the input fields.
LAYOUT_SIDE_BOTTOM : String
- Login form layout: input fields and labels draw up in column, left aligned; login button on their right side, aligned to the password input field.

Instance properties

noGuestLoginMsg : String
- The error message to be displayed in case of guest login attempt.
autoHide : Boolean
- Hide the LoginBox control before connection to SmartFoxServer and after a successful login.
customLoginPage : String
- The custom server-side page url for access credentials validation.
formLayout : String
- The layout of the login form controls.
usernameLabelText : String
- The text of the label located above the username text input.
passwordLabelText : String
- The text of the label located above the password text input.
buttonText : String
- The label of the "login" button.
restrict : String
- The set of characters that a user may or may not enter into the username and password text inputs.
zone : String
- The SmartFoxServer zone (application) to log in to.
showPassword : Boolean
- Show/hide the password text input and label.
usernameLabel : Label
- A reference to the "username" Label control.
passwordLabel : Label
- A reference to the "password" Label control.
loginButton : Button
- A reference to the "login" Button control.
usernameTextInput : TextInput
- A reference to the "username" TextInput control.
passwordTextInput : TextInput
- A reference to the "password" TextInput control.
errorTextField : UITextField
- A reference to the "error" UITextField component.

Instance methods

destroy : void
- Destroy the LoginBox instance.

Constructor

LoginBox

public function LoginBox (

)

LoginBox constructor.

Example:

See the example in the class description.

See also:

formLayout

LAYOUT_SIDE_MIDDLE

public static const LAYOUT_SIDE_MIDDLE:String = "side-middle"

(read)

Login form layout: input fields and labels draw up in column, left aligned; login button on their right side, centered between the input fields.

See also:

formLayout

LAYOUT_SIDE_TOP

public static const LAYOUT_SIDE_TOP:String = "side-top"

(read)

Login form layout: input fields and labels draw up in column, left aligned; login button on their right side, aligned to the username input field.

See also:

formLayout

Instance properties

autoHide

public autoHide:Boolean

(read,write)

Hide the LoginBox control before connection to SmartFoxServer and after a successful login.
If set to true, the LoginBox won't be visible until a connection to SmartFoxServer is made available (through the Connector control), and will disappear again after a successful login.

Example:

To make the LoginBox disappear after a successful login using MXML:
```
<sfb:LoginBox autoHide="true" />
```
To make the LoginBox disappear after a successful login using ActionScript:
```
loginBox.autoHide = true
```

Component metadata:

Bindable	"autoHideChanged"
Inspectable	category: "Common" defaultValue: false name: "Auto hide" type: Boolean

buttonText

public buttonText:String

(read,write)

The label of the "login" button.

Example:

To set the login button label in MXML:
```
<sfb:LoginBox buttonText="Click here" />
```
To set the login button label in ActionScript:
```
loginBox.buttonText = "Click here"
```

See also:

Component metadata:

Inspectable	category: "Common" defaultValue: "" name: "Button text"

customLoginPage

public customLoginPage:String

(read,write)

The custom server-side page url for access credentials validation.
If this property is set, before attempting the SmartFoxServer login, the LoginBox will send the entered username and password to the provided url for validation.
Two parameters are passed to the custom server-side page via POST: name (the entered username) and pass (the entered password). The page must return res=OK if the credentials are valid or res=KO if the credentials are invalid.

Example:

To set the server-side page for custom login in MXML:

<sfb:LoginBox customLoginPage="http://localhost/sfsLogin.php" />

To set the server-side page for custom login in ActionScript:

loginBox.customLoginPage = "http://localhost/sfsLogin.php"

Component metadata:

Bindable	"customURLChanged"
Inspectable	category: "Common" defaultValue: "" name: "Custom server page for access validation"

errorTextField

public errorTextField:UITextField

(read)

A reference to the "error" UITextField component.
This property allows you to get a reference to the error Flex UITextField component, to set its properties (for example text styling). Check the Flex Components documentation for additional details.

Example:

To access the error UITextField component in ActionScript:

import mx.core.UITextField

var tf:UITextField = loginBox.errorTextField
tf.setStyle("color", 0xFFCC00)

formLayout

public formLayout:String

(read,write)

The layout of the login form controls.
Username and password input fields, their labels and the login button can be rearranged according to seven predefined layouts:

LAYOUT_ROW: input fields and button in a row with labels above the input fields, left aligned;
LAYOUT_COLUMN_LEFT: input fields, labels and button draw up in column, left aligned;
LAYOUT_COLUMN_CENTER: input fields, labels and button draw up in column, center aligned;
LAYOUT_COLUMN_RIGHT: input fields, labels and button draw up in column, right aligned;
LAYOUT_SIDE_TOP: input fields and labels draw up in column, left aligned; login button on their right side, aligned to the username input field (this is the default layout);
LAYOUT_SIDE_MIDDLE: input fields and labels draw up in column, left aligned; login button on their right side, centered between the input fields;
LAYOUT_SIDE_BOTTOM: input fields and labels draw up in column, left aligned; login button on their right side, aligned to the password input field.

Valid MXML values are row, column-left, column-center, column-right, side-top, side-middle and side-bottom; in ActionScript, you can use the above constants to set this property.
NOTE: if password input field is hidden, the side- layouts look all the same.

Example:

To set the LoginBox layout in MXML:

<sfb:LoginBox formLayout="column-center" />

To set the LoginBox layout in ActionScript:

loginBox.formLayout = LoginBox.LAYOUT_COLUMN_CENTER

See also:

Component metadata:

Inspectable	category: "Common" defaultValue: "side-top" enumeration: "row,column-left,column-center,column-right,side-top,side-middle,side-bottom" name: "Form layout" type: Array

loginButton

public loginButton:Button

(read)

A reference to the "login" Button control.
This property allows you to get a reference to the login Flex Button control, to set its properties (for example size). Check the Flex Components documentation for additional details.

NOTE: if you change the Button control size, you then have to call the LoginBox.invalidateDisplayList method to rearrange the LoginBox view accordingly.

Example:

To access the login Button control in ActionScript:

import mx.controls.Button

var button:Button = loginBox.loginButton
button.height = 100

loginBox.invalidateDisplayList()

noGuestLoginMsg

public noGuestLoginMsg:String

(read,write)

The error message to be displayed in case of guest login attempt.
At login, if no username is provided, SmartFoxServer automatically creates a name for the client using the format "guest_n" (where n is a progressive number).
Setting this property prevents the LoginBox to accept an empty username, showing the error message if the login button is pressed.

Example:

To set the "No guest login" message in MXML:

<sfb:LoginBox noGuestLoginMsg="Please enter a username" />

To set the "No guest login" message in ActionScript:

loginBox.noGuestLoginMsg = "Please enter a username"

Component metadata:

Bindable	"guestMessageChanged"
Inspectable	category: "Common" defaultValue: "" name: "'No guest login' message"

passwordLabel

public passwordLabel:Label

(read)

A reference to the "password" Label control.
This property allows you to get a reference to the password Flex Label control, to set its properties (for example text styling). Check the Flex Components documentation for additional details.

Example:

To access the password Label control in ActionScript:

import mx.controls.Label

var label:Label = loginBox.passwordLabel
label.setStyle("color", 0xFFCC00)

passwordLabelText

public passwordLabelText:String

(read,write)

The text of the label located above the password text input.

Example:

To set the password label in MXML:

<sfb:LoginBox passwordLabelText="Enter your password:" />

To set the password label in ActionScript:

loginBox.passwordLabelText = "Enter your password:"

See also:

Component metadata:

Bindable	"passwordLabelChanged"
Inspectable	category: "Common" defaultValue: "Password

passwordTextInput

public passwordTextInput:TextInput

(read)

A reference to the "password" TextInput control.
This property allows you to get a reference to the password Flex TextInput control, to set its properties (for example text styling). Check the Flex Components documentation for additional details.

Example:

To access the password TextInput control in ActionScript:

import mx.controls.TextInput

var ti:TextInput = loginBox.passwordTextInput
ti.setStyle("color", 0xFFCC00)

restrict

public restrict:String

(read,write)

The set of characters that a user may or may not enter into the username and password text inputs.
Check the Flex TextInput control documentation for a description and usage examples of this property.
By default, tag delimiters ("<" and ">" characters) are not allowed, to prevent possible html textfields corruption.

Component metadata:

Inspectable	category: "Common" defaultValue: "

showPassword

public showPassword:Boolean

(read,write)

Show/hide the password text input and label.
If you need to implement the Moderator feature in your application, then this property should be set to true.
In the LoginBox control, the entered password is checked against the Moderator list only, cointained in the SmartFoxServer config.xml file.
For an external, server-side validation, check the customLoginPage property.

Example:

To make the password input field visible using MXML:
```
<sfb:LoginBox showPassword="true" />
```
To make the password input field visible using ActionScript:
```
loginBox.showPassword = true
```

Component metadata:

Inspectable	category: "Common" defaultValue: false name: "Show password field" type: Boolean

usernameLabel

public usernameLabel:Label

(read)

A reference to the "username" Label control.
This property allows you to get a reference to the username Flex Label control, to set its properties (for example text styling). Check the Flex Components documentation for additional details.

Example:

To access the username Label control in ActionScript:

import mx.controls.Label

var label:Label = loginBox.usernameLabel
label.setStyle("color", 0xFFCC00)

usernameLabelText

public usernameLabelText:String

(read,write)

The text of the label located above the username text input.

Example:

To set the username label in MXML:

<sfb:LoginBox usernameLabelText="Enter your username:" />

To set the username label in ActionScript:

loginBox.usernameLabelText = "Enter your username:"

See also:

Component metadata:

Bindable	"usernameLabelChanged"
Inspectable	category: "Common" defaultValue: "Username

usernameTextInput

public usernameTextInput:TextInput

(read)

A reference to the "username" TextInput control.
This property allows you to get a reference to the username Flex TextInput control, to set its properties (for example text styling). Check the Flex Components documentation for additional details.

Example:

To access the username TextInput control in ActionScript:

import mx.controls.TextInput

var ti:TextInput = loginBox.usernameTextInput
ti.setStyle("color", 0xFFCC00)

zone

public zone:String

(read,write)

The SmartFoxServer zone (application) to log in to.

Example:

To set the SmartFoxServer zone in MXML:
```
<sfb:LoginBox zone="simpleChat" />
```
To set the SmartFoxServer zone in ActionScript:
```
loginBox.zone = "simpleChat"
```

Component metadata:

Bindable	"loginZoneChanged"
Inspectable	category: "Common" defaultValue: "" name: "Server zone to log into"

Instance methods

destroy

public function destroy (

) : void

Destroy the LoginBox instance.
This method should be called to make the LoginBox eligible for garbage-collection in the Flash Player.
When called, this methods removes the listeners to the SmartFoxClient events added during initialization.

Example:

To destroy the LoginBox instance:
```
loginBox.destroy()
```