Markup Extensions

Skip to end of metadata
Go to start of metadata

 

Overview

Gigya’s markup extensions provide flexibility beyond the Screen-Sets UI Builder tool, allowing you to design custom HTML forms and use dynamic markup extensions that enable Gigya to power the rest. The Screen-Sets UI Builder is essentially a markup generator, so the simplest way to get started is by using the Screen-Sets UI Builder, exporting the generated code, pasting it to your web page and tweaking the markup code to meet your specific design and flow needs.

The idea behind our markup extensions is that with simple markup and no code you can define sophisticated UI and logic of user management and registration flows. Basically you define a set of screens, such as a Login screen, a Registration screen, an Update Profile screen etc. The layout and design of the screens are defined using standard HTML and CSS, whereas the functionality behind the screens, the flow, server side logic, and database access are all generated automatically through the usage of Gigya's proprietary HTML classes and attributes.

Example of a Single Screen:

 

Note: The code above is a code extract representing the single screen, and not the fully functioning code. You may find a complete working code example in the Screen-Set on Page Demo You may see the screens  in action, and you may view/copy the code.

In the example above you can find classes such as "gigya-screen", "gigya-social-login", "gigya-error-display", etc. You can also find attributes such as "data-switch-screen", "data-bound-to". These Gigya predefined classes and attributes are interpreted by Gigya's engine into functionality and binding to Gigya's Storage. This functionality is described farther ahead in this document. In addition you may use these classes in your CSS file to override the default style.

Using Screen-sets

A group of screens that are connected logically and are all defined on a single web page within a <div> known as a "screen-set". Gigya will render a single screen at a time and switch between screens, according to the predefined logic and flow defined within the screen-set. There are two options for where to place the screen-set definition:

  1. On the page where the screens are displayed.
  2. Hosted on Gigya's server. This option is recommended if the screen-set may be shown on many different pages of the site. To host a screen-set on Gigya's server, go to the Screen-Sets page after logging into Gigya's site. The page presents a list of predefined screen-sets. You may use these screen-sets or define new ones. Each screen-set saved using this tool is automatically hosted on Gigya's server. You can import manually written screen-set markup code to Gigya server using the Import/Export Code dialog.

After you have placed the screen-set, either on page or on our server, you display the screens on a page using the accounts.showScreenSet API method. You can define whether the screens are rendered embedded within the page, or within a pop-up (dialog).

Markup Elements

  • Screen-Set and Screens - These are the basic building blocks. You define a screen-set that enfolds a group of related screens.
  • Forms - Screens are primarily made up of forms. The forms are defined just like standard HTML forms, with the addition of Gigya's proprietary classes, attributes and fields.
  • Form Fields - Gigya-defined special form fields with extra functionality.
  • Containers - This includes a group of form fields. The group of fields may be displayed or hidden according to the container's attributes.
  • Anchors
  • Widgets - Gigya provides several widgets that you may include in your screens.
  • Error State and Error Messages - These are elements that can be added to your screens to inform the user of errors (e.g., if the user filled in a form incorrectly).

Screen-Set and Screens

A screen-set is a group of logically connected user interaction screens. Technically a screen-set is defined as a <div> element with class="gigya-screen-set". The screen-set <div> enfolds a list of <div> elements, each representing a single screen. A screen <div> is defined using class="gigya-screen".

This is illustrated in the code snippet bellow:

 

<div class="gigya-screen-set" id="my-screens" style="display:none">
    <div class="gigya-screen" id="screen1">  ...  </div>
    <div class="gigya-screen" id="screen2">  ...  </div>
    <div class="gigya-screen" id="screen3">  ...  </div>
    ...
</div>  

gigya-screen-set

The class "gigya-screen-set" defines a set of screens to be managed by Gigya and can be used to specify which screen should be loaded. To display a screen from a different screen-set use the format <another-screen-set/screen-name>, if the screen is in the currently loaded screen-set then the screen-name is sufficient. Use <another-screen-set/> to open another screen-set and display its default screen.

The "gigya-screen-set" <div> declaration includes several attributes:

  • id (required) - A unique identifier (name) for the screen-set. You may provide any unique string. The id will be used as a reference to the screen-set when calling the accounts.showScreenSet API method (this is further explained below). Screen and screen-set ids can contain letters (A-Z, a-z), numerals (0-9), underscores (_) and hyphens (-). 
  • data-caption (optional) - The caption of the screen-set.
  • data-on-existing-login-identifier-screen (optional) - A screen to which to go when the email of the socially logged-in user belongs to a different account. This would typically take the user to an "account linking" screen.
  • data-on-missing-loginid-screen (optional) - A screen which to go to in order to add a login-identifier and password following a social login if the policy requires that. Learn more about the policies.
  • data-on-pending-password-change  (optional) - A screen which to go to when there is a pending password change error from the server.
  • data-on-pending-registration-screen (optional) - Defines which screen to switch to in order to complete the registration process.
    This is sometimes required when new users use Social Login (gigya-social-login widget) to register for your site, so should always be set. The social data that you receive from the social network may not satisfy your site's needs, assuming one or more required user data fields are missing, for example: Twitter does not provide an email address. In this case, the user needs to be redirected to a form in order to fill in the required fields (email in this case). Set this attribute with the ID of the screen for filling-in required fields and completing the registration process.
  • data-on-pending-verification-screen  (optional) - A screen to which to go in order to resend an email verification if the user hasn't got it.

The following attributes are relevant only if the screen-set is presented on a dialog, and are ignored if the screen-set is displayed embedded inside the page:

  • data- width (required) - The width of the screen-set.
  • data- height (required) - The height of the screen-set.
  • data-responsive (optional) - Enables responsive design in the screen-set. If responsive design is enabled, it means that if there is not enough space for two columns to be side by side, they will collapse to be one above the other.

Whether the screen-set is displayed on a dialog or embedded is specified through the containerID parameter of the accounts.showScreenSet method.

Make sure to define  style="display:none" within the screen-set declaration (see the code above). Gigya will render one screen of the screen-set at a time according to the logic defined within the screen-set. Gigya will switch between the screens in the set based on transition rules defined within the set.

gigya-screen

Class "gigya-screen" defines a single screen, defined within an enfolding screen-set. The "gigya-screen" <div> declaration has the same attributes as the "gigya-screen-set" above. 

 

Default Screen-Sets

Gigya provides four default screen-sets for use on both web and mobile devices.

  • Names of the default screen-sets:
    • Default-RegistrationLogin 
    • Default-LinkAccounts 
    • Default-ProfileUpdate 
    • Default-ReAuthentication

Each screen-set consists of a series of screens, whose names and descriptions are listed here. To view screen-set code see the Gigya console (login required).

 

Responsive Screen-Sets

gigya-conditional:

The gigya-conditional attribute allows you to set how you would like your Screens to appear on various screen sizes by evaluating a JavaScript condition and sets the attribute according to the result.

Supported Parameters for the attribute expression

  • screenset.width (plugin computed width)
  • screenset.height (plugin computed height)
  • viewport.height (screen computed height)
  • viewport.width (screen computed width)
  • viewport.orientation (screen orientation in degrees)

Note: Though the screenset.width or screenset.height can be defined as percents, the above attributes, when returned (with the exception of .orientation which is degrees), are always in pixels.

 

Format Example

gigya-conditional:<attributeName>="<js_condition>?<true_value>:<false_value>"

 

Code Example

<div gigya-conditional:class="screenset.width>400?wide:narrow"></div>

 

Conditions can be nested within the false_value portion in order to support multiple switching points.

An example of this would be:

<div gigya-conditional:class="screenset.width<100?tiny:screenset.width<300?small:screenset.width<500?medium:large"></div>

The condition may omit the else portion if it has no value, i.e., <input gigya-conditional:disabled="screenset.width<100?disabled:" /> is the same as <input gigya-conditional:disabled="screenset.width<100?disabled" />.

Any condition that results in an empty value will revert to the attribute with no condition set (if it is present), otherwise it will remove the attribute if the attribute was not present. The two following examples illustrate this:

  • <div gigya-conditional:readonly="screenset.width<500?:readonly"></div> - If the screenset.width is less than 500px the readonly attribute will be deleted.
  • <div class="initial" gigya-conditional:class="screenset.width<500?narrow:"></div> - If the screenset.width is less than 500px the class will be narrow, otherwise it will revert to initial.

 

When used within a Widget, the supported conditional is only on the value attribute, see the example below:

<div class="gigya-social-login">
  <param name="enabledProviders" value="facebook,twitter,yahoo" gigya-conditonal:value="screenset.width<200?facebook,twitter" />
</div>

 

Forms

The forms are basically standard HTML forms, with the addition of defining a form class with associated attributes. In addition you may add within a form special Fields and Gigya proprietary Widgets.
Gigya defines several form classes. The class defines the type of the form, which determines what kind of business logic Gigya binds with this form. Each class has associated attributes. The attributes act like parameters passed to the class object implementing the form's logic.

The form class is defined within a <form> tag, for example:

<form class="gigya-login-form" >  ...  </form>

gigya-login-form

Represents a login form, where the user is expected to enter his credentials for identification. This class implementation encapsulates a call to accounts.login.

Special Field Names: 

Gigya looks for the following reserved field names within this form, and uses the values of these fields as parameters of the login process:

  • loginID  
  • password
  • remember

    The  loginID and password are required fields. The remember  field is optional and signifies whether the user checked the "Remember me" checkbox. The "Remember me" checkbox can be added to your form by adding the remember field to your code with the name "remember" and type "checkbox". This field influences the amount of time that the login session is kept valid. The site Policies sessionExpiration and rememberSessionExpiration fields define the amount of time that the login session is kept valid with/without checking the "Remember me" checkbox.

You may find more information about Form Fields below.

Note: When a gigya-login-form is successfully submitted and processed, Gigya fires an onLogin event. Use the accounts.addEventHandlers API method to register to the onLogin event. You can use this event handler to create your login session cookie.

Represents an account linking form, where the user is expected to enter the credentials of an existing account in order to link it to a newly logged in social account. This class implementation encapsulates a call to accounts.linkAccounts (both fields are required). 

Special Field Names:

Gigya looks for:

  • loginID 
  • password

    These are reserved field names within this form and the values of these fields are used as parameters of the linking accounts process. You may find more information about Form Fields below.

gigya-profile-form

Represents a generic form bound to the user profile, it can be used to collect additional information about the user (such as in a second registration screen) or to edit the user's profile data (such as in "edit profile" screen). This class implementation encapsulates a call to accounts.getAccountInfo and accounts.setAccountInfo.

Special Field Names:

Gigya looks for the following reservedfield names within this form, and uses the values of these fields as parameters of the updating profile dataprocess:

  • username
  • password
  • newPassword
  • passwordRetype
  • addLoginEmails
  • removeLoginEmails

You may find more information about Form Fields below.

For more complex uses of profile forms see Progressive Profiling and Conditional Workflows .

gigya-reauthentication-form

Represents an account authentication form, where the user is expected to prove ownership of an account by logging in. This class implementation encapsulates a call to accounts.login with the loginMode set to "reAuth". 

Special Field Names:

Gigya looks for:

  • loginID
  • availableProviders

    These are reserved field names within this form, and values of these fields are used as parameters in the logging-in process. You may find more information about Form Fields below.

gigya-register-form

Represents a registration form, where the user is expected to specify his credentials and potentially additional information. This class implementation encapsulates a call to accounts.register.

Special Field Names:

 Gigya looks for the following reserved field names within this form, and uses the values of these fields as parameters of the registration process:

  • loginID
  • password
  • passwordRetype

Both loginID and password are required fields. You may find more information about Form Fields below.

gigya-resend-verification-code-form

Represents a form where the user can request an email verification link to be resent to his mail box, in case he didn't get it before or in case it has expiredThis class implementation encapsulates a call to accounts.resendVerificationCode

Special Field Name:

Gigya looks for:

  • email

A reserved field name within this form, and uses the values of this field as a parameter of the resending verification email process (the  email field is required). You may find more information about Form Fields below.

gigya-reset-password-form

Represents a password recovery form, where the user is expected to  enter identifying information. As a consequence, a "reset password" email will be sent to him. This class implementation encapsulates a call to accounts.resetPassword.

Special Field Names:

  Gigya  looks for the following reserved   field names within this form, and uses the values of these fields as parameters of the reset password process:

  • loginID
  • email

The loginID  field is required. You may find more information about Form Fields  below.

 

Attributes

The <form> element accepts several attributes, all attributes are optional. Some of the form attributes may override the corresponding attribute defined in the screen-set declaration.

To reference a screen from a different screen-set use the format <another-screen-set>screen-ID. To open another screen-set without specifying a screen, use the format <another-screen-set/>. If the requested screen is within the currently loaded screen-set (collection) then the screen ID is sufficient. 

The form attributes are defined within the <form> tag, for example:

<form class="gigya-login-form" data-on-success-screen="welcome-screen">  ...  </form>

The available attributes:

  • id - The form's unique identifier. If not specified then the ID of the form is its class name.
  • data-auto-skip - A boolean attribute with a default value "false". When the value is set to "true" and all the required fields in the form have data (from the database), the form is automatically skipped and behaves as if it was successfully submitted and processed. Gigya loads the data-on-success-screen if defined, or finishes the flow and hides the screen-set. The data-auto-skip logic also takes into consideration the data-empty-fields settings, so a screen may not be skipped if it has a container that has missing required fields and passes all other defined conditions (so the container is visible).
    Note: This attribute is mostly relevant to the gigya-profile-form, in a case when this form is used after social registration to fill in required fields. If this attribute is set to "true" and all the required fields are available (from the social data), the screen is skipped and the registration process completes successfully.
  • data-on-auto-skip-screen - When specified, this attribute overrides the data-on-success next screen attribute and allows specifying a different next screen when the form is successfully submitted vs. when the screen is auto-skipped. If this attribute is not specified then the next screen for both cases is determined by the data-on-success attribute.
  • data-on-screenset-skipped-screen - Indicates the next screen to display when a screen in a different screen-set was skipped, returning control to the current screen-set.
  • data-on-success-screen - Defines which screen to switch in case of successful submission and processing of the form. If not specified, after successful processing of the form, the flow finishes and Gigya hides the screen-set (see also Removing the Screen-set section). 
    Weighted next screens are also supported. This means that only one of the defined screens will be selected randomly, with probability distributed according to the weight of each possible next screen. The extended format will be a comma-separated list of "<next screen>:". For example:

    data-on-success="extra_screen_one:3,extra_screen_two:5"

    If a weight is not specified then the default weight is "1".

     

Attributes that override the parallel screen-set attributes:

  • data-on-missing-loginid-screen - A screen to go to in order to add a login-identifier (e.g., email) following a Social Login, if required by site policy.

 

For an example of the use of attributes see Progressive Profiling.

Form Fields

Standard HTML input elements that reside within a Gigya  Form , are automatically equipped with extra functionality. The  HTML input elements that receive Gigya's extra functionality are: <input /><textarea>, and  <select>Gigya also provides these fields  with a predefined default design that you may override.

An input field that resides within a Gigya  Form , is automatically bound to a corresponding field in the user's account. The binding between a form input field and a user account (database) field is done based on the field's name. 

For example, the following input field is bound to the " email " field in the user's profile:

<input type="text" name="email"/>

Custom Fields

Custom data fields are site specific fields, which are not part of Gigya's predefined core Profile fields. Custom data fields must be preceded with "data.", for example: "data.newsletter". To define custom fields for use in the form element use the accounts.setSchema API or add fields in the Screen-Sets  tool and map them to the Data object.  

Field names may contain hierarchies, for example: "data.moreInfo.bio". Form fields with custom field names are automatically bound to a corresponding data field in the user's account, just like Gigya's predefined core profile fields.

Special Fields

The following field names are Gigya reserved names:

  • addLoginEmails
  • availableProviders
  • email
  • loginID 
  • newPassword
  • password
  • passwordRetype
  • remember
  • removeLoginEmails 
  • username

Using these field names adds extra functionality to the field. In specific forms Gigya looks for specific field names as part the execution of the form functionality. For example: in the gigya-login-form, Gigya looks for loginID and password field names, and uses the values of these fields as parameters of the login process.

Field Attributes

Adding Gigya-reserved attributes to a field adds special predefined behavior to the field.
For example: Adding the show-valid-checkmark='true' attribute will display a checkmark that indicates the validity of the input in relation to the field's definition in the schema.

data-display-name Attribute

A user friendly name for this field. If specified, the data-display-name attribute is used in error messages bound to this field. If not specified the name attribute is used instead, without the namespace.

For example:

<input type="text" name="data.moreInfo.homeAddress" data-display-name="Home Address"/>

A related error message would look something like: "Missing required field: Home Address". Without specifying the data-display-name  attribute in the above example, the message would be:  " Missing required field: homeAddress ".

show-valid-checkmark Attribute

A boolean attribute that adds a checkmark on a focus out event if the validation is successful. The behavior of this attribute may change according to the input name:

  • loginID -  should not be empty, should be validated as a valid email (if the loginID is email), the loginID should be available.
  • password - should pass the password complexity policy
  • Everything else -  should pass the validation as defined in the schema
<input type='email' name='email' show-valid-checkmark='true'/>

data-gigya-placeholder

Adds (or changes) placeholder text for an input field (text fields only).

It is important to note that defining placeholder text within a text box will override the native HTML placeholder attribute values of the screen-set.

 

Example code:

<input type="text" name="profile.email" data-gigya-placeholder="Email" />

show-password-strength Attribute

Adds a password strength widget  that appears as a bubble near the password input field as the password is being typed. Select the position of the bubble via the drop-down in the right-hand Properties pane.

Applicable values for the bubble orientation are:

  • Up (default)
  • Down
  • Left
  • Right
  • Disabled

While up and down are the only values supported in mobile view.

The show-password-strength property is only available for Password and New Password fields (Password confirmation and Old Password are not supported).

<input type='password' name='password' show-password-strength='right'/>

Fields Write Access

By default all the data fields in the DB have a "serverOnly" write access, which means that only signed requests coming from server are allowed to write into these fields. This is defined in the default Accounts Storage schema. When using the UI Builder tool Gigya automatically changes the schema: for every field you add to the screens, the write access is automatically changed to "clientModify" thus enabling the screens to write into these fields.
If you are not using the UI Builder tool and writing the screens manually, you will need to change the schema, by calling the accounts.setSchema API method, prior to using the screens. Otherwise you will receive the following response when attempting to write into the profile fields:

"errorMessage": "Schema validation failed",
  "errorDetails": "write access mode violation: email",
  "statusCode": 400,
  "errorCode": 400020,

Required Fields

In some forms there are fields that are predefined by Gigya to be required. For example: loginID  and password  are required fields in the registration form.  When submitting a registration form, if a required field has not been filled in by the user, the registration fails, the field is in an 'error state' and a proper error message is generated (learn more about  Error State and Error Messages below).

In addition to the default required fields, you may define other fields to be required, thus producing the same behavior. To define required fields you may use the UI Builder tool (highlight the field and check the "Required" checkbox). Alternatively, you may call the accounts.setSchema API method. 

If a certain field is required in the schema, a red asterisk is displayed next to the field; you can automatically show/hide an asterisk next to the relevant input by using  gigya-required-display widget, f or example: 

 

<div class="gigya-required-display" data-bound-to="terms" >*</div>

 

Containers

Using containers you may conditionally display or hide sections of forms, based on various conditions. This can be used for content-based data collection, e.g. you may ask a different question based on the user's age. This mechanism can also be used for incrementally collecting additional profile data after each login, in order to reduce the amount of data that the user must provide at the initial registration. 

 

Class gigya-container

A conditional container class that can be applied only to a <div>, which is then displayed or hidden according to various conditions.

The gigya-container class must be inside a form. The container will be displayed if all its specified conditions are true.

The class gigya-container can only be used with <div> elements.

 

Attributes that can be used to condition gigya-container:

  • data-apikeys  - A comma-separated list of API keys. The condition will be true only when the screen is loaded using one of these API keys.
  • data-after-date  - A date/time specification in ISO 8601 format, e.g., 2013-11-21T16:45:30.022+01:00. The condition becomes true if the current time is after the specified date.
  • data-before-date  - A date/time specification in ISO 8601 format, e.g., 2013-11-21T16:45:30.022+01:00. The condition becomes true if the current time is before the specified date.
  • data-condition  - A valid JavaScript Boolean expression that defines the condition for displaying based on profile fields, data fields or any other data of the page. For example:

    data-condition="profile.gender=='m' && data.newsletter==true && window.myGlobalVar == 'john'"

    The conditions to display or hide a container are evaluated after every field is modified, so for example, when the user selects his/her gender, a container that depends on that field immediately appears or disappears.

  • data-display-cap  - The total number of times this container may be displayed. The condition becomes true as long as the cap has not been reached. This attribute requires the container to have a name, and is just for registered users.
  • data-display-freq  - The minimum frequency in seconds between displaying the container. The condition becomes true after the specified time since the last display has passed. This attribute requires the container to have a name, and is just for registered users.
  • data-domains - A comma-separated list of domain names or *.domain.name (for all subdomains of the parent domain). The condition becomes true only when the screen is loaded on a matching domain.
  • data-empty-fields - Indicates which of the fields contained in the container are required to have data. This can be a list of field names or the special value "*" (asterisk), which means all fields within the container are required. The condition will become true if any of the required fields are null or empty.

    Note that this attribute is unrelated to the setting of required fields in the site's schema, it only dictates whether the current container should be displayed based upon whether data is missing from any, all, or only the specified field(s) contained within it.

    When using required fields, whether they are required by the site schema or you designate them as required using HTML markup; these fields can not be hidden using conditional workflows. Any required fields are always displayed in the current screen.

  • data-login-identities - A comma-separated list of provider names. The container will be displayed if any of the providers exist and allow login. Can also use the following special values:
    • site : The user is a registered site user.
    • site-only : Only registered site users.
    • social : Any social network identity.
    • social-only : Only social network identities.
    • site-and-social : The user has a site identity and a social network identity.
    • + : Use the "+" sign to indicate that a condition or set of conditions are required: "+site, +social" indicates a user who has a site account and (&&) a connected social network (same as 'site-and-social').  
  • data-prob : A probability value in the range 0-1 that the condition will be true. 

For examples of using gigya-container see Progressive Profiling and Conditional Workflows.

Note: If a schema required field is included in a container and that field is empty the container is displayed regardless of the other conditions.

Anchors

Standard HTML Anchors may have a special attribute:

  • data-switch-screen - Specifies to which screen to switch, when the anchor is clicked. The value is the ID of a screen within the current Screen-Set.

For example: 

 data-switch-screen = "registration-screen"

Use the format data-switch-screen = "screen-set/screen-set-Id"  to specify a screen in a different screen-set. 

Important: When calling a screen from a different screen-set collection, the incoming screen becomes a child of the original screen-set. When the screen is completed it returns to it's actual parent and will continue the current flow. This may cause errors if calling screens out of context.

For best practice, you should only call screens from the same collection within a single session.

 

Widgets

gigya - social-login

A wrapper around Gigya's Login pluginThe plugin's parameters may be specified using <param> sub-elements.

For example: 

<div class="gigya-social-login">
    <param name="buttonsStyle" value="fullLogo">
    <param name="width" value="313">
    <param name="showTermsLink" value="false">
</div>
 
The output of the above code is:

gigya-captcha

A CAPTCHA component that is implemented using Google's reCAPTCHA freeware. The CAPTCHA's parameters may be specified using <param> sub-elements.

For example: 

<div class="gigya-captcha">
    <param name="lang" value="en">
    <param name="theme" value="clean">
</div>

The output of the above code is:

For the list of customization parameters please refer to the RecaptchaOptions Reference table in the Customizing the Look and Feel of reCAPTCHA page.

If you want the CAPTCHA to be displayed after a number of failed login attemps use the data-error-flags = "captchaNeeded". When the flag is returned, the CAPTCHA widget will be displayed:

<div class="gigya-error-display" data-error-flags="captchaNeeded" data-bound-to="gigya-login-form">
   <div class="gigya-captcha">
      <param name="theme" value="white">
   </div>
   <span class="gigya-error-msg" data-bound-to="captchaText"></span>            
</div>

show-valid-checkmark

Adds a checkmark   to a text field upon successful entry of the requested data.

Checking the Validity indication box for a field in the UI Builder turns on this feature.

gigya-password-strength

A widget for providing generic indication of password strength. The widget is automatically connected logically to an input field with name="password" in the same form. When the user types into the password input field, the widget is shown and is automatically updated according to the string that the user has typed. 

For example:

Password: <input type="password" name="password">  <div class="gigya-password-strength"></div>

The output of the above code (after the user has typed a relatively weak password):


 
The widget accepts the following attributes:
 
  1. data-on-focus-bubble

    If this attribute is set to "true", the widget will appear within a floating bubble, only when the password field is focused. For example:

    <div class="gigya-password-strength" data-on-focus-bubble="true"></div>

    The above code will produce the following output, when the password field is focused:

  2. data-display-mode Attribute

    The attribute specifies one of three options of what is to be displayed on the widget. The attribute accepts the following values:

      • meter - the widget will only show a password strength meter.

      • policy - the widget will only display the minimum requirements, based on the password policy.

      • combined (default) - the widget displays a combination of both the strength meter and the minimum requirements.
    Note: If the policies for "Min Length" and "Min Character Groups" (see  Password Strength Policies ) have both been set to 0, the widget will  not  display any minimum requirements text. Instead:
    • If data-display-mode is set to "combined", the widget will only show the password strength meter.
    • If data-display-mode is set to "policy", the password strength widget will not be displayed at all.
  3. data-bubble-orientation Attribute


    The attribute specifies four options for the orientation of the widget as follows:
    • right (default) - The widget will have right orientation.
    • left - The widget will have left orientation.
    • up - Place the widget above the password field
    • down - Place the widget below the password field
    * up and down orientations are mainly used for displaying the widget on mobile devices properly. 

gigya-loginID-availability (Deprecated)

 

gigya-loginID-availability has been replaced with the Show ID Availability property parameter (show-valid-checkmark).

 

Show Id Availability markup example:

User name: <input type="text" name="username" show-valid-checkmark="true" />

 

The gigya-loginID-availability Widget is for checking and displaying whether a username/email that the user has typed is available. A username/email is available if it is unique in this user management system. The widget is displayed when the user stops typing for more than 500ms or when the user focuses out of the username/email input field.  

For example:

User name: <input type="text" name="username"><div class="gigya-loginID-availability"></div>

The output of the above code (after the user has typed a user name which is not unique in the system):

The widget accepts a data-bound-to attribute to specify the input field to which the widget relates. The bound to fields may be either a username or an email field. By default, if the  data-bound-to  attribute is not defined, Gigya looks for an input field with  name="username" and binds the widget to it. If there is no name="username" input field in the form, Gigya looks for an input field with  name="email" and binds the widget to it.

The  gigya-loginID-availability  widget must be placed within the initial Registration screen only. Placement within any other screen of the RegistrationLogin Screen-Set will cause an error.

gigya-image

Adds an image to any of the Gigya screens. For example:

<div class="gigya-image" data-src="http://image-url/img.jpg" data-background-size="fit" data-width="100" data-height="100" aria-label="Describe image"></div>

These are the widget's attributes: 

  • data-src: the URL source of the image. If you specify an HTTP image, and the web page to which the image is loaded is HTTPS, the image will automatically be redirected through an HTTPS proxy so that it will display on the page. 
  • data-background-size: the way the image is displayed inside the designated frame. Possible values: 
    • fit: the image is shown in full within the frame. 
    • fit-horizontally: the image's height is cropped to fit the designated width. 
    • fit-vertically: the image's width is cropped to fit the designated height. 
    • stretch: the image is stretched to fit the frame. 
  • data-width: the width of the image frame, in pixels. May also be described as a percentage. 
  • data-height: the height of the image frame, in pixels. 
  • aria-label: an ARIA label, used by screen-readers. 

gigya-myPhoto

A widget that can be used both for displaying a photo of the current user and for uploading a new photo. The widget supports two modes - "display" (displaying the photo only) and "upload" (allows the user to upload a new photo). Photos are retrieved from the Profile object's photoURL field. If no photo exists, a default photo is used instead.

The code for use within Screen-Sets:

<div class="gigya-myPhoto">
  <param name="height" value="100">
  <param name="width" value="100">
  <param name="mode" value="upload">
</div>

The output of the above code:


          

 

Supported File Types

The supported upload filetypes for gigya-myPhoto are:

  • JPG/jpg

  • GIF/gif

  • PNG/png

Upload File size is limited to 3MB or less.

 

  • The gigya-myPhoto widget replaces both the gigya-profile-photo and gigya-upload-photo widgets (below), which have been deprecated, however, you may continue using the older plugins in existing screen-sets.
  • If a user is not either logged in or on the registration screen, the myPhoto widget is always in display mode and not active, regardless of settings.

 

 

gigya-profile-photo (Deprecated)

A widget for displaying a photo of the current user. Photos are retrieved from the Profile object 's photoURL field.

The code:

<div class="gigya-profile-photo"></div>

The output of the above code:

gigya-photo-upload (Deprecated)

A photo upload widget. This widget may not be specified on the first registration screen (before a user has been registered and a UID has been created).

Photos are uploaded to the Profile object 's photoURL field.  A thumbnail will be created from the photo and stored in profile.thumbnailURL. For more information see the profilePhoto parameter in accounts.setPolicies .

The code:

<div class="gigya-photo-upload"></div>

The output of the above code:

gigya-tfa

A widget for two-factor authentication (TFA) component. The widget supports three modes:

  • verify
  • register
  • edit

For example: 

<div class="gigya-tfa" data-mode="register"></div>

The output of the above code is (with data-mode "register"):

When the data-mode is verify the following screen appears:

When the data-mode is "edit" the following screen appears:

Error State and Error Messages

Gigya defines for each of our Markup Elements, that it can be in an error state. An example for that can be an email field in which the user has filled a string that is not a valid email address. Another example is when a user submits a form without filling-in some Required Fields.

Form validity: Gigya checks the validity of a form after the submission of the form.

Form Fields validity: Gigya checks the validity of a form field after the user has focused on the field and then focused-out of the field. Gigya gives a different style for a field that is in an error state. For example:

Note: To override the default design of the error state of a form field, override the gigya-error CSS class.

The validation rules for some Markup Elements, such as the email field, are predefined by Gigya. 

Gigya defines two types of error-related objects:  gigya-error-display and gigya-error-msg. Error-related objects can be bound to any Markup Element and are initially hidden. When a Markup Element comes to be in an error state Gigya will display the error objects bound to it. For example:

This example shows an email input field. The user has entered an invalid email and then focused-out of the field. The email field is shown in its error state style (red frame), and the two error objects that are bound to it are displayed.

The code of the above example: 

 

Email address: <input type="text" name="email">&nbsp;&nbsp;
<img class="gigya-error-display" data-bound-to="email" src="images/error.jpg">&nbsp;&nbsp;
<span class="gigya-error-msg" data-bound-to="email"></span> 

 

The two error related classes are:

  • gigya-error-display
  • gigya-error-msg

gigya-error-display

May be applied to any HTML element. Indicates that this element is bound to an error state of the bound object. The element will be automatically displayed when the bound object is in error state and hidden when the bound object is not in error state. The attributes associated with this class:

  • data-bound-to  (required) - Indicates the object to which this error object is bound. A bound object may be:
    • Any field name within the same form as this error object. In such a case, the error object will be displayed on focus-out of the bound field if it is in an error state.
    • A form ID. In such a case, the object will be displayed when the form is submitted and its operation fails.
  • data-scope (optional) - Attribute indicating the scope of this object. This attribute is relevant only when this error object is bound to a form. This attribute may receive one of the following values:
    • bound-object-error (default) - only errors of the bound object itself will cause this object to be displayed.
    • any-error - the error object will be displayed if there is an error in any of the fields within the bound form.
  • data-error-codes (optional) - A list of error codes. When specified, the container will only be displayed if one of the specified error codes were returned by the bound element.

 

<form class="gigya-login-form">
	<p>User Name:</p>
		<input type="text" name="loginID" style="width:300">
			<div class="gigya-error-msg" data-bound-to="loginID"></div>
	<p>Password:</p>
		<input type="password" name="password" style=" width:300">
	
			<!-- ***************THE NEXT LINE OF CODE GENERATES THE CUSTOM ERROR*************** -->
			<!-- **************The code "403042" specifies a login/password error************** -->
			<!-- *************You MUST bind this error to the FORM,  not the field************* -->
			<div class="gigya-error-display" data-bound-to="gigya-login-form" data-error-codes="403042" data-scope="bound-object-error">&nbsp; CUSTOM ERROR MESSAGE GOES HERE! &nbsp;</div>
		</br>
	<input type="submit" value="Login" style="float: right;"></p>
</form>

The above code will produce the following error when a username or password is not filled in correctly:

gigya-error-msg

A container for automatically generated error messages. May be applied to a <div> or a <span>  element. The element will be automatically displayed when the bound object is in error state and hidden when the bound object is not in error state.  This object behaves similar to the gigya-error-display object, except it also displays a predefined error message or an error message that comes from the server. The attributes associated with this class:

  • data-bound-to    (required)  - Indicates the object to which this error object is bound.
    A bound object may be:
    • Any field name within the same form as this error object. In such a case, the error object will be displayed on focus-out of the bound field if it is in an error state.
    • A form ID. In such a case, the object will be displayed when the form is submitted and its local validation or server operation fails.
  • data-scope  (optional) -Attribute indicating the scope of this object. This attribute is relevant only when this error object is bound to a form. This attribute may receive one of the following values:
    • bound-object-error (default) - only errors of the bound object itself will cause this object to be displayed.
    • all-errors - The object will display a list of all the error messages for all the fields within the bound form (checked locally before actually submitting the form) and the error received from the server. This option gives you the possibility to display all the errors of the form in one location. 
    • first-error - same as all-errors but instead of displaying all the errors it only displays the first one.
  • data-error-codes  (optional) - A list of error codes. When specified, the container will only be displayed if one of the specified error codes were returned by the bounded element.

Error Handling - Best Practice

As a best practice, Gigya recommends that RaaS form errors be caught and logged to your internal systems. This will enable you to be alerted to potential issues before hearing about them from your end-users. This can be accomplished by registering an event handler to the onError event, and having the handler send the response object to your server for logging/alerting.

See the code example below:

...
<script type="text/javascript">
function logErrorEvent(err) {

            // Set up the XMLHttpRequest object which we'll use to send the error data
            var xht = new XMLHttpRequest();
            var url = "loggingPage.php"; // The page on your server that will log the error and/or alert someone
            var data = "event=" + err.eventName + "&screen=" + err.screen + "&response=" + err.response;
            xht.open("POST", url, true);

            // Set request headers
            xht.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
            xht.setRequestHeader("Content-length", data.length);
            xht.setRequestHeader("Connection", "close");

            // Send the data to be logged (i.e., the error data)
            xht.send(data);
        }
function loadScreenSet() {
            var screenSetparams = {
                screenSet: "my-screen-set",
                containerID: "regDiv",
                onError: logErrorEvent
            };
            gigya.accounts.showScreenSet(screenSetparams);
        }
</script>
...

Presenting the Screen-Set

To display a screen-set call the accounts.showScreenSet JS API method. The method receives a screen-set identifier and renders the initial screen of the screen-set.
You can choose whether the screens are rendered within a pop-up (dialog), or embedded within the page. To embed the screens within the page use the containerID parameter.

For example:

...
<div id="userScreensDiv"><!-- the screens are displayed here --></div> 
...
<script>
gigya.socialize.showScreenSet({
    screenSet: "my-screen-set",  // The ID of the screen-set to load
    containerID:"userScreensDiv" // Display the screen-set in the "userScreensDiv" container
});
</script>

When calling the accounts.showScreenSet method, by default Gigya renders the first screen that is defined within the screen-set. You can override this behavior by passing the startScreen parameter to the method.

For example:

...
<!-- the screen-set definition -->
<div  class="gigya-screen-set"  id="my-screen-set"  data-start-screen="screen1" style="display:none">
    <div class="gigya-screen"  id="loginScreen">   ...  </div>
    <div class="gigya-screen"  id="registrationScreen" >   ...  </div>
    ...
</div> 
...
<script>
gigya.socialize.showScreenSet({
    screenSet: "my-screen-set",  // The ID of the screen-set to load
    startScreen:"registrationScreen" // Display the "registrationScreen" initially
});
</script>

In the above example the "registrationScreen" will be displayed initially. If we remove the startScreen:"registrationScreen" parameter from the above example, the "loginScreen"  will be displayed initially. You can use this option, for example, if you have on your page two different links, "Login" and "Register" (see the  working Screen-Set on Page Demo).

Removing the Screen-Set

There are few situations in which the screen-set flow terminates and is cleared from the page:

  • When a form submission completes successfully, and the  data-on-success-screen attribute is not specified for this form. 
  • Using the _finish  reserved screen ID. You can use the  _finish ID as a value of any attribute that expects a screen ID. 
    For example:

    <a data-switch-screen="_finish">Close</a>

    Clicking the "Close" link will close the screen-set.

  • Calling the accounts.hideScreenSet API method.
  • If the screen-set is displayed in a dialog - when the user clicks on the close button of the dialog.

All the above are equivalent, in all cases Gigya clears the container in which the screen-set is displayed or closes the dialog.

Events

Global Events

Gigya defines the accounts.addEventHandlers JS API method for registering to global events fired by Gigya. The supported events include the onLogin  event that  is fired when a gigya-login-form  is successfully submitted and processed.  You can use this event to create your login session cookie.
The onLogin  event is also fired after a user clicks on one of the social network buttons within one of Gigya's 
Engagement Add-Ons.

Screen-Set Events

The  accounts.showScreenSet  API method generates the following Screen-Set related events: onErroronBeforeSubmitonAfterSubmitonBeforeScreenLoadonFieldChanged
Learn more in the accounts.showScreenSet  method reference.

Putting it All Together

In the Screen-Set on Page demo you may find a complete working example that shows a simple screen-set implemented on the page. The screen-set includes three screens: Login, Registration, and Update Profile. You may see the page in action, use the screens, and then you may view/copy the code.

Console Logging

Using the JavaScript Console tool, you may view the browser console and find warnings for errors in your markup code, in particular, configuration errors like referenced fields or forms that cannot be found, as well as user-related errors such as failed validation or server side errors.

To view the console (in Google Chrome), click the Settings icon on the top right-hand corner, then click Tools, then JavaScript console (or CTRL+SHIFT+J):