UI Builder

Skip to end of metadata
Go to start of metadata

 

The UI Builder for Screen-Sets is a powerful web-based tool for creating and implementing user management workflows on your site. The UI Builder comes with an easy to use drag-and-drop interface for building and editing login, registration, and profile management screens, which gives you the flexibility to match the look-and-feel of your site and to tailor your implementation in terms of design, structure, fields and content and, if necessary, also optimize screens for mobile environments, if you want to collect unique data from mobile users (such as the phone number of the device).

Additionally, by using Screen-Sets in conjunction with site Policies, you can enable a wide range of capabilities such as CAPTCHA, email verification, and password strength requirements. 

Note: The Screen-Set are part of the Registration-as-a-Service (RaaS) package, which is a premium platform that requires separate activation. If it is not part of your site package please contact your Gigya Account Manager or contact us by filling in a support form on our site. You can also access the support page by clicking "Support" on the upper menu of Gigya's site.

Overview

The Gigya UI Builder is a WYSIWYG canvas where you edit your Screen-Sets, designed to make implementing Registration-as-a-Service (RaaS) as fast and easy as possible. The UI Builder includes: 

  • Drag-and-drop visual editing
  • Preview on multiple devices
  • Localization canvas for handling language translations
  • Field mapping that supports a dynamic schema
  • CSS and HTML editor for custom designs
  • JavaScript editor for handling events related to the screen-set

All accounts that have RaaS enabled have a default collection of Screen-Sets automatically installed. You can add additional Screen-Set Collections at any time.

Accessing the Screen-Sets UI Builder

Go to the Screen-Sets section of Gigya's website. Please make sure you are signed in.

The Screen-Sets page may also be reached by clicking the Settings tab in the upper menu and then Screen-Sets in the left menu:

 

The Screen-Sets page displays the Default Screen-Sets and all the screen-sets that have been defined.

Gigya Screen-Sets are responsive and will adjust to the device that is accessing them, there is no need to create separate Collections for web and mobile applications (unless you have specific screens that you want to use only on a specific platform).

 

Screen-Set Collections

Notes: 

  • Sites that were created before October 26th, 2015 use an earlier version of our screen-sets, which include separate sets for both desktop and mobile devices. You now use the same default responsive screen-set for both mobile and desktop applications. If your site is currently using the older versions you may continue using the existing screen-sets or migrate to the new screen-sets.
  • The Screen-Sets version released on November 14th, 2016 include all the features described on this page, including Screen Cloning, Metadata Fields, Custom Data Field Arrays, etc. To have access to these latest features your Screen-Set Collection must have been created on or after that date.

Screen-Set is a set of user interaction screens that are connected logically. For example, a set of login and registration related screens will be defined in a single 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. 

Gigya packages screen-sets in "collections". Each screen-set collection contains four screen-sets (by default) which, between them, comprise a full best-practice implementation. The four screen-sets are named in the following format, where <collection name> is a prefix placed in front of the screen-set name:

  1. <collection name> -LinkAccounts
  2. <collection name> -ProfileUpdate
  3. <collection name> -ReAuthentication
  4. <collection name> -RegistrationLogin
  5. <collection name> -LiteRegistration 

For a full explanation of the default screen-sets and the screens they contain see the Default Screen-Sets page. 

When you enter Screen-sets for the first time, you will find a list of the screen-sets predefined by Gigya:

 

In the right-hand Actions column, you will find the available operations you can perform for the screen-set. These are:

Opens the UI Builder for the screen-set.
Opens the Version Control page of the screen-set
Export the screen-set to another site.
Open the Advanced Customization window for the screen-set.
Duplicate this screen-set using a different name.
Delete this screen-set. Note that you can not delete Default screen-sets.

 

Version Control

Whenever you edit and then save an existing screen-set, it will be saved as a new version in your account. This enables you to revert to a past version if something is configured incorrectly or you want to roll-back to a previous design.

You enter the Version Control menu by selecting the Versions icon from the UI Builder dashboard (see table above). You will then be presented with all the versions for the selected screen-set.

 

On this page you can see all the existing versions, as well as who edited (saved) each version. From here you can select a previous version and then re-save it to roll-back your active screen-set.

Initially, you can edit any version via either UI Builder or through the Advanced Customization window. It is important to note that once you save a screen-set from the Advanced Customization window, you can no longer use the UI Builder on that screen-set, or any later version of that screen-set. To regain UI Builder functionality you will need to open a previous version that is still accessible via the UI Builder and re-save it; this will make the previous version the latest version and the UI Builder will be available once again. It also important to note that rolling back a screen-set will remove any changes made to that screen-set from the time the previous screen-set was active (not including schema changes, so if you roll-back a RegistrationLogin screen-set and you have made new fields required in your schema since it was last active, be sure to update the rolled back screen-set to include any necessary fields on it's Registration Completion screen.

 

Version Control and the showScreenSet API

When using the accounts.showScreenSet API method, the latest version of the defined screen-set will be the version displayed from the API call. So in the following example, assuming we are on the site that the above screenshot is from, the following call will automatically display version 3 of our screen-set:

gigya.accounts.showScreenSet({ "screenSet" : "Default-RegistrationLogin"});

If I edit version 3 of my screen and then save it, it will become version 4, and now version 4 will be the screen displayed.

 

Adding New Screen-Set Collections 

If you press the Add New Collection button:

  • The ID that you enter will be used to create four new screen-sets with the ID used instead of the default. The screen-sets created will contain the same screens as the default screen-sets.
  • The Description option sets a short description of this particular screen-set for reference purposes. 

Note: It is no longer possible to create a single screen-set outside of an existing collection. 

 

It is important to note that only screen-sets within the same collection  can be implemented together. Trying to use screen-sets from multiple collections within a unique instance will break the functionality of the displayed screens. This is especially critical after the October 26th, 2015 major Screen-Set update which integrated our new Responsive Design Technology.

Lite Registration is a premium feature, see here for more information.

 

How to Customize Screen-Sets

Edit screen-sets in the following ways:

  • Edit the screen-sets using the UI Builder. Use this guide to learn how to use the UI Builder. Click the "UI Builder" button    next to a specific screen-set to open the editor cavas, make your changes and save. The editor then saves the edited screen-sets on Gigya's server with a new version number.  
  • It is important to note that although the Default Schema does not have any custom fields, once you open any screen-set in the UI Builder, the following two fields are immediately created:

    • data.terms
    • data.subscribe

    Additionally, the write permissions of all fields that may require user input are changed from 'Server only' to 'Client modify'.

    These changes occur as soon as the screen is opened within the UI Builder for the first time, even if you do not  save  the screen-set after opening, the fields are created. This will result in receiving a warning message that you have made changes to the screen. This warning will also appear any time that a field is mapped to a previously un-mapped schema object.

  • Edit the HTML code: Clicking the Advanced Customization button next to a specific screen-set opens a dialog that presents the HTML and CSS code of the specific screen-set. You can copy the code and paste it into your dev environment enabling you to edit the entire code to fit your specific user experience design. Learn more about this in the Markup Extensions guide. After tweaking the markup code, you can either keep it on your pages and serve it from your servers, or if you wish Gigya to host it, you can paste your code into the Advanced Customization dialog and click the "Save Changes" button.

    Important Notes:

    • After clicking "Save Changes" you will not be able to use the UI Builder on this specific screen-set again.
    • To edit the CSS, use the UI Builder (not the "Advanced Customization" dialog) as changes made using theAdvanced Customization dialog make the screen-set inaccessible to the UI Builder.
    • If you want to return to a previous version of a screen-set that still supports the UI Builder, you can enter the Versions window and choose a previous version. Re-saving the previous version will make this the latest version for the screen-set and you can then use the UI Builder on it again (Any changes made since the previously editable version was saved will be lost - screen-set changes only, schema changes are permanent for your site).

Screen-Sets are called using the call the accounts.showScreenSet API method in your site. See a working example on the Screen-Set Hosted on Gigya demo page that also displays the code used.

Using The UI Builder

This section will explain how to utilize the Gigya UI Builder and manage the screens within a screen-set to enable unlimited customization.

UI Builder Basics

Clicking the UI Builder button next to a specific screen-set in the screen-sets table opens the following canvas:

 

Screen Behavior

Editing a screen's behavior can be used to create custom registration and login flows, e.g., to enable multi-step registration/progressive profiling.

Screen ID

You can change the name of a screen by editing it directly in the Screen ID field. The Screen ID must be unique and may contain any combination of supported characters:

  • Letters (a-z A-Z)
  • Digits (0-9)
  • Underscore (_)
  • Hyphen (-)

You can also edit the Internal Name and the screen's Caption using the corresponding fields. The Internal Name is the name that it is referred to in the left-hand Screens list and has no impact on your production environment. The Caption is the Title of the screen when it's UI is displayed to the end-user.

 

Behavior

You can change the default behavior of a screen within a collection using the following options:

  • Behavior - Useful when cloning existing screens or creating new ones. This allows you to define the behavior of the screen, e.g., when implementing Progressive Profiling.
  • Success Screen - Defines which screen to display (or terminate the flow) when the current screen is successfully completed, e.g., always force a TFA Registration screen after a successful registration. You can use the From other screen-set: option to call a screen that does not exist in the current collection.

 

Only advanced users should ever change the Behavior of any of the Gigya default screens. Editing the behavior of a default screen, if there is no replacement, may result in users being unable to register, login or perform the action the screen is designed to serve. For more detailed information on screen behaviors, please see the Forms section of our Markup Extensions guide.

 

                        

 

From Other Screen-Set

When selecting the From other screen-set option, you will be presented with an additional set of drop-downs allowing you to choose any existing screen-set within your account, and then select the specific screen from within that screen-set.

                

 

Skip If Data Exists

On screens that use the Edit Profile behavior you will have a checkbox labeled Skip if data exists. You can use this checkbox to skip the current screen (not to display it) if data for all of the displayed fields currently exists for the user in the database.

 

Adding And Cloning Screens

You can add new screens from within the UI Builder to any existing Screen-Set . There are two ways to create a new screen; you can press the Add A New Screen button (plus symbol) in the top-left of the Screen-set's UI Builder, or, to create an identical copy of an existing custom screen, use the Clone Screen button from the right-hand menus. You may also delete any screen by pressing the Delete Screen button of the right-hand menu.

Deleting a screen can break your implementation and is recommended only for advanced users that are familiar with the flow of the screens used within their site. You should never delete a default screen prior to creating one to replace it's existing functionality.

 

Add Screen Button

Pressing the Add Screen button will create a new screen within the current screen-set. You will be presented with a popup dialog to define the screens Screen ID, Internal Name, and Screen Template. The Screen Template defines which of the Gigya default screens to use as the basis of the new screen. This is useful if you, for instance, accidentally delete one of the original default screens. The options available to choose from are dependent upon which screen-set is currently open, i.e., you can not add a new Edit Profile screen while inside the RegistrationLogin screen-set.

 

Clone Screen Button

Pressing the Clone Screen button will create a duplicate copy of the current screen. You will be presented with a popup dialog to define the screens Screen ID and Internal Name.

 

Rearranging Screens

When creating new screens, you may find it helpful to change the order that the screens are displayed within the UI Builder. You can reorder the screens list on the left-hand side of the UI Builder by dragging and dropping them as you like. Reordering the screens on the left will also update their order within any of the drop-downs option boxes where they are listed.

        

To download the video, click here. If you are having trouble viewing the video, please see Video Help For Gigya Documentation.

 

Localization

Use the Localization panel in the UI Builder to manage translations of your Screen-Sets. Gigya provides default translations for the default Gigya fields in all Screen-Sets in 15 locales, and supports a total of 44 different locales. For a list of all 44 supported language codes see Advanced Customizations and Localization. The 15 locales built-in to the UI Builder are:

  • Arabic
  • Chinese (Mandarin)
  • Czech
  • Danish
  • Dutch
  • French
  • German
  • Italian
  • Japanese
  • Norwegian
  • Polish
  • Portuguese (pt)
  • Russian
  • Spanish (es)
  • Swedish

Visit our demo site, The Daily Recipe, to see screen-sets that use Gigya's OOTB localization capabilities.

  1. Open the View or Edit Gigya Add-ons menu.
  2. Select Screen-Sets.
  3. Underlang, select the locale you wish to preview. You can see that in the code box, the value of the 'lang' parameter has changed.
  4. Click Initiate Custom Screen-Set.

 

Managing Localization

Manage your screen-set's translations via the UI Builder Localization canvas.

 

Opening the canvas will display the Localization table.

Add a Locale

The Localization table already includes the default (English) locale, which cannot be deleted or edited (imported), and the locales provided out-of-the-box by Gigya.

To add a new supported locale:

  1. Select Add Locale
     
  2. Choose the locale. If you have already added a locale to the table, it will no longer appear as an option and you must edit the existing file (see Editing the Locale CSV File, below).

     

 

As a result, a new row appears in the table with the selected locale.

When using the Localization tool, you must add the new locale(s) to every screen-set within the Screen-Set Collection used on your site, and edit their translations accordingly:

  • RegistrationLogin
  • ProfileUpdate
  • ReAuthentication
  • LinkAccounts
  • LiteRegistration

 

Editing the Locale CSV File

You need to edit the locale files in the following cases: 

  • When adding a locale that is not included in the default translations provided by Gigya (in this case you will need to provide translations for all the fields in the screen-set)
  • If you wish to edit or change those default translations  (in this case, you may use the default translations as the baseline, and change the translation only for individual fields)
  • If you added custom fields to any screen (in this case, when using one of the default languages, only those fields need to be translated)

 

Important

We recommend you export translation files from a development or test environment, have them translated, and import them back for checking the result before uploading translations into a production environment. You should make sure you have a full translation file prepared and ready for upload when adding a new locale to a production environment, then import that file immediately after adding the relevant locale.

 

To edit a locale:

  1. Click the corresponding Export CSV button and save the file to your local environment (do not change the name). You may send this file to a translator.
  2. The person translating the file should open it in a spreadsheet (e.g., Microsoft Excel, Google Sheets). If using OpenOffice Calc, make sure to set the delimiter to 'comma'. 

    Open Office Calc 1
  3. The spreadsheet must contain 6 columns: 
    • Screen - the name of the screen within this screen-set to which the field belongs.
    • Translation Key - a unique ID of the field.
    • Control - see Controls.
    • Property - the field type.
    • Default - the original English default string. This should be the source for the translation. This field is for reference only - changes you make to it will not affect the original screen-set.
    • Localized - this column may be wholly or partially empty, depending on whether translations already exist for all or some of the fields in the screen-set.
  4. Enter the translations in the Localized column. Do not make any changes to any of the other fields. 

    Notes

    • If you add new fields to the screen-set , you should export new locale files for translation. Do not add new rows manually to the locale file.
    • When translating a field that is a button or hyperlink, the translator should copy the entire string into the Localization column, and only change the text included in the value of that string. The translated value should be surrounded by quotation marks, like the original. For example:
  5. Save the file.
  6. In the Localization panel, click the corresponding Import CSV button  and upload the fully translated file.
  7. Check the Missing Translations column to see if any files are still missing translations for any number of fields.
  8. When you have finished uploading translations, Save changes in the Screen-Set.

Export All Localization Files

You can export a single CSV file containing all the localization files you added to the panel.

 

This file will be similar to the individual CSV files for each locale, but instead of a Localization column, will include a separate column for each locale that currently exists in the Localization panel:

Example file snippet:

Screen,Translation Key,Control,Property,Default,Chinese (Mandarin) (zh-cn),German (de),Hebrew (he)
Login,CHECKBOX_46370714680136104_LABEL,Checkbox,Label,Keep me logged-in,,,
Login,HEADER_125151791345112740_LABEL,Header,Label,Quickly log in with your social network:,,,

Setting the Screen-Set Language

Once you have a localized version of your screen-set installed, you can display it on your site by setting the lang parameter of your global Configuration object to the desired language code. 

Example:

<script type="text/javascript" src="https://cdns.gigya.com/js/gigya.js?apiKey=3_fakeApiKey1234567&lang=es"> // For Spanish
</script>

 

To control the localization on a per user basis, do not add it to the global Configuration object and instead include the lang parameter in the showScreenSet call, example:

gigya.accounts.showScreenSet({screenSet: 'YOUR_PREFIX-RegistrationLogin', lang: 'es'})

 

Using Custom Schema Data Arrays

You can create screens that allow users to add multiple items within an array. You can use arrays to store multiple phone numbers, addresses, or custom data for your users.

To create a custom array follow the instructions below. In this example we will explain creating an array for storing multiple children's names for your users.

Step One - Preparing The Screen

Create a new screen to allow the users to add/edit this new data. The easiest way to accomplish this is to access the UI Builder of the Gigya Console. Navigate to the Screen-Sets tab of the Dashboard and open the ProfileUpdate screen-set of your site's active Screen-Set Collection.

 

Clone the Update Profile screen and give it a unique name.

 

Remove all the current fields (except the Save button) and add new fields to handle the data you want collect (you can remap all the existing fields if you prefer, but is can be less confusing in the beginning to simply add new fields and map them).

For our example we are going to add a Header and 3 Textbox Controls.

Our Header is going to say Update Your Children's Names. The Textboxes will be for the First child's name, the Second child's name, and the Third child's name (you can add additional fields to handle any situation required). Define the Labels and Placeholder Text you require for each of the fields.

 

Step 2 - Mapping Fields To An Array

To map the new fields to a single array, select the first available field. In the Mapped Field drop-down, select the +Add... button.

 

In the dialog that appears, enter the Field Name of the new array, terminating in .value (or any unique string, in the example we are using names), and setting the Data Type to String.

Press the Add button and you will see your field now mapped in the drop-down. Checking the Store in array checkbox will display 2 additional fields - Key Field and Key Value.

 

In the Key Field drop-down select +Add... (as above in the Mapped Field section), and define the Key name for this item, in this example it will be data.children.key (where the field is pre-populated with data.children.) and setting the Data Type to String

 

In the Key Value field enter the name as you would like it to appear in the schema, e.g., First Child.

 

Repeat the above for each remaining field of your new screen, selecting the same top-level mapping for each field (i.e., data.children.names) and creating a unique Key Value for each.

 

Responses

Example response of accounts.getSchema after performing the above actions.

 

"children.key": {
  "writeAccess": "clientModify",
  "type": "string",
  "allowNull": true,
  "required": false
},
"children.names": {
  "writeAccess": "clientModify",
  "type": "string",
  "allowNull": true,
  "required": false
},

 

Example response of accounts.getAccountInfo for a unique user after a they filled out the corresponding form.

 

"data": {
  "children": [
    {
      "key": "First Child",
      "names": "Jane"
    },
    {
      "key": "Second Child",
      "names": "John"
    },
    {
      "key": "Third Child",
      "names": "Julie"
    }
  ]
}

 

Demo Video

You can watch this short video that covers the complete process described above.

 

To download the video, click here. If you are having trouble viewing the video, please see Video Help For Gigya Documentation.

 

Custom Previews

Once you design your screen-set you can preview it by selecting the Preview button from the top of the UI Builder canvas.

 

You can preview your screen-set for any device by selecting a Device type from the right-hand menu drop-down while in Preview mode or by setting a custom size in the width/height fields.

You can further choose to view it as the default modal Dialog pop-up or In page and you can choose to display it in any of the currently localized languages.

 

Pre-configured options include:

  • Desktop (default resolution of 1024 x 768).
  • Tablet (default resolution of 768 x 780).
  • Mobile phone (default resolution of 375 x 667).

 

Responsive Design

By default, Screen-Sets are responsive , and seamlessly adjust to the user's device. Design user-friendly, branded screens that look great on both desktop and mobile environments. 

To view how your screen-set will appear across devices, choose the device type in the Preview canvas, or enter custom width and height dimensions.

To specifically preview the screen in a touch-enabled device (e.g., tablet or smart phone), check the Emulate mobile device field.

 

Button Customization

You can set a custom width for buttons and fields in the UI Builder. 

  • Select the field or button you want to adjust.
  • In the Width property box from the right-hand menu enter a new size in pixels and press Enter.
  • Press Save when finished.

 

Social Login Widget

The Properties window for the Social Login widget contains several important fields that you can edit.

  • Supported Providers - A comma delimited list of all providers that will be displayed as options for the Login widget. You can leave this field blank to enable 'All Supported Providers'.
  • Button Style - The type of buttons that will be displayed within the widget.
    • Available options are:
      • Icons - Icons with the provider logo only, and no text.
      • Full Logos : Provider Logos on a grey background.
      • Full Logos - Colored : Provider Logos on a colored background. (The default button type always displayed within the editor canvas).
      • Sign In With : Provider logos on a colored background that includes the term 'Sign in with <provider>; where <provider> is the name of the provider.

             
         
  • Paging Button Style
    • The type of buttons available for scrolling through the available providers.
      Available options are:
      • Arrows
      • New Arrows (arrows slightly farther away from the provider buttons to ease use on touch devices).
      • Floating
      • Auto (default)

                      
  • Button Size
    • Edit the size of the provider buttons within the widget.

      Please see socialize.showLoginUI for Button Sizes supported by your chosen Paging Button Style. Using an unsupported Button Size will result in your Login UI being corrupted and not displaying properly.

  •  Height/Width
    • Edit the size of the Social Login widget container.
  • Mode/Version
    • Mode - the type of login required for the widget (e.g., Standard, Re-Authentication, and Link Accounts).
    • Version - The version of the Login plugin the widget uses. Version 2 is recommended (Note: changing the version may effect the plugins layout).

 

Left Hand Menu

In the left side menu you will find three sections:

  • Screen-set - This section includes the screen-set ID, a "Close editor" button, which closes the UI Builder without saving, and a "Save" button. When you finish editing hit the "Save" button, this will save the changes on Gigya's server.
  • Screens - The Screens section lists the screens within this screen-set. Clicking one of these screens will open it for editing in the center of the editor canvas.  Below the list of screens you may find a "Screens Style" button. Clicking it will open the CSS editor of the screen-set in the center of the Editor Canvas allowing you to customize the Screen-Set's Styles. This style sheet applies to all screens of the screen-set. 
  • Controls - This section includes Standard  controls and special Gigya Widgets. Drag and drop the elements you want included in the screen. Relevant properties will be shown on the right in the Properties menu (explained below). For more details regarding the widgets see the Markup Extensions. If you use the Photo Upload widget, note that user image uploads have a maximum size of 3MB and ensure that an appropriate warning exists on screen.

 

Note: See CAPTCHA Validation for information about using the CAPTCHA widget.

 

For a complete list of Controls and how to implement them, please see Screen-Set Controls.

 

Editor - Center

The center section of the UI Builder canvas presents the screen that is selected in the "Screens" section  Left Hand Menu.

CSS Styles

Selecting "CSS Styles"  in the  "Screens" section opens the screen-set's CSS editor in the center of the UI Builder canvas. This is a simple text editor and is fully customizable.

When editing CSS for your screen-sets, recommended best practice is to use the CSS Styles editor of the UI Builder canvas as described here. Editing CSS via the Advanced Customization  link on the main Screen-Sets page of the console will disable your future ability to use the UI Builder on that screen-set.

 

JavaScript Parameters

Selecting JavaScript Parameters in the Screens section opens a JavaScript editor, usually used for defining the event handlers of this screen-set. Here you can define anonymous custom JavaScript functions within any of the events you need to perform actions for. Anything added to this JSON obj will be appended to the params obj of the accounts.showScreenSet method (so must be a valid parameter for accounts.showScreenSet).

Common Use Cases: 
  • Event handlers for the screen-set.
  • Adding custom validations to the screen-set.

Example of incrementing a counter inside the onFieldChanged event:

{ // JavaScript Parameters JSON Obj
	// Called when a field is changed in a managed form.
	onFieldChanged: function(event) {
    	window.eye = (typeof(window.eye) == 'undefined') ? 0 :  window.eye +1;
    	console.log("field changed: " + window.eye);
	}
}

 

 

Properties

The right side of the UI Builder contains the Properties menu. Highlight and click on an element within the screen (in the UI Builder canvas) to see the element's properties in the right side menu. You may now edit the element's properties:

 

Different types of controls or widgets have different properties. Some properties of form fields are:

  •  Mapped Field: This property maps the form field to a field in the database. You may select one of the predefined Data or Profile fields from the drop-down, or you may specify your own custom field, by clicking the "Add" button under Data or Subscriptions in the drop-down, and typing the field name and the data type, or subscription ID, in the dialog. 
                   
  • Error Display Name This name is used in error messages bound to this field. Error Display Name acts as a placeholder and replaces the name of the field within any error messages when it is defined, otherwise the name of the form field is displayed in the error message. This attribute correlates to the  data-display-name  attribute of the Gigya HTML Markup extensions. 

Schema

In the "Schema" section you can define the data type and choose whether the field is required or not. Whenever a field is set to Required, an asterisk will display whenever the field is visible in the displayed screen.

                    

 

  • Not Required: Select this option to define the field is not required (default). 

  • When Visible: Select this option to define that, if the field has a Visible When attribute and when the field is visible on the screen, it is required.
  • Conditionally: Select this option to set define a JavaScript expression that determines when the field is required (e.g., based upon data contained in another field).
    • Fields available for conditional use within screen-sets are as follows:
      • screenset.width
      • screenset.height
      • viewport.orientation
      • profile - All fields of the profile object, if the user is logged in.
      • data - All fields of the data object, if the user is logged in.
      • accountInfo - All fields of the user's account object, if the user is logged in. This contains loginID/emails.

        "accountInfo.loginIDs.emails"
      • tfaProviders - Any TFA providers that exist for the user, if the user is logged in.

        tfaProviders.gigyaPhone - The user's SMS TFA info.
        tfaProviders.gigyaEmail - The user's email TFA info.



  • Always: Select this option to set the field as required always. This option makes the field required and updates the site's schema.

    When making a field required in the schema it is necessary to ensure that all Registration and Registration Completion screens that are associated with the site contain the required fields or users will be unable to complete registration.

    If you belong to group that does not have the Edit schema permission enabled, you will not be able to select the Always option, as that requires updating the site's schema.

In the "Schema" section you may also decide, for data fields with a type of string, whether to assign regex and whether to encrypt the data:


  • Format (regex): You may assign a regular expression that defines the format of this data field.
  • Encrypt (AES): You may encrypt the string. It is important to note that if you already have existing data for a field and you enable encryption, only new data will be encrypted. Furthermore, once encryption is enabled for a field, it is not possible to disable encryption. The field will remain permanently encrypted.

 

Advanced Customization

Clicking the Advanced Customization button next to a specific screen-set in  the screen-sets t able opens the following dialog:

Warning:  Editing either the HTML or CSS via the  Advanced Customization  dialog will permanently disable future access to the UI Builder for the screen-set!

 

This dialog enables you to both export the screen-set code from the Gigya server, and to import your own screen-set code to the Gigya server as well as make any desired changes to the existing code.

Copying Code

The UI Builder provides a wide range of editing possibilities, however, if you require higher flexibility you may copy the screen-set code and edit it directly. The UI Builder is essentially a code generator, therefore, the simplest way to get started is by using the UI Builder, copying the generated code and pasting it into your dev environment and then tweaking the code to meet your specific design and flow needs.

The generated HTML code is a standard HTML code with embedded Gigya's proprietary HTML classes and attributes. Learn more about it in the Markup Extensions  guide.

Pasting Code

After you have made changes to the markup code, you have a choice where to place the screen-set definition. One option is on the page where the screens are displayed (i.e., hosted on your server). Another option is to host the screen-set definition on Gigya's server. This option is recommended if the screen-set may be shown on many different pages of the site. To do that, paste your manually edited screen-set markup code into this dialog and hit the "Save Changes" button*.

*Important: After pressing the "Save Changes" button you will not be able to use the UI Builder on this specific screen-set again.

CSS Code

This dialog gives you the option to copy and/or paste the screen-set's CSS code (in addition to the HTML code). However, if you wish only to edit the screen-set's CSS, instead do it using the UI Builder. When editing the CSS using the UI Builder, the CSS is saved on Gigya's server, and you can continue using the UI Builder on this screen-set in the future. However, editing or importing new CSS via the Advanced Customization interface    will permanently disable future use of the UI Builder on this Screen-set.

 

Exporting Screen-Sets

To export screen-sets to additional sites within your account (under the same Partner ID), please see our Exporting Screen-Sets documentation.


Screen-Set Controls

This section explains all current screen-set controls available within the UI Builder.

Controls

Access the Controls menu from the Screen-Set UI Builder. Log into the Gigya console and select the site you wish to edit. Then select Screen-Sets from the left-hand menu.

 

Open the screen-set you want to edit by clicking the UI Builder button that pertains to the screen-set.

 

Select the particular screen you wish to add or remove controls from, which will open the screen within the UI Builder canvas.

 

Here you can add or remove the controls you require for that screen.

Explanations

Standard Controls

Header

Adds a custom text line to the top (or elsewhere) of the screen-set dialog window.

Usage

Drag the Header control from the left-hand Controls menu into the screen where you would like it to appear.

In the Properties menu:

  • Give the control a Label which will be the displayed text of the control.
  • Set the Alignment of the control to NoneLeftRight, or Center.
  • Set the Style (font-weight) of the text to Standard or Bold.

 

Label

Adds a custom text line to a screen-set dialog window using a smaller font than in a Header control (above).

Usage

Drag the Label control from the left-hand Controls menu into the screen where you would like it to appear.

In the Properties menu:

  • Give the control a Label which will be the displayed text of the control.
  • Set the Alignment of the control to NoneLeftRight, or Center.

Adds a custom hyperlink to the current screen.

Usage

Drag the Link control from the left-hand Controls menu into the screen where you would like it to appear.

In the Properties menu:

  • Give the control a Label which will be the displayed text of the Link.

  • In the URL field choose whether to send the user to an external page or a different screen within the screen-set.
  • If using an External URL, input the fully qualified URI into the corresponding field.
  • If using a Screen, select the appropriate destination from the drop-down menu.


  • In the Target field, select if you would like the Link to open in a New Window, or Redirect within the parent window.
  • Select to align the text to LeftCenterRight, or None within the widget.

Textbox

Adds a text input field within the screen to collect or display data from the user.

Usage

Drag the Textbox control from the left-hand Controls menu into the screen where you would like it to appear.

                          

In the Properties window:

  • Map the control to a field using the Mapped Fields drop-down.
  • Enter a Label to be displayed for the field (or leave blank).
  • Set a custom Width (in px) if necessary.
  • Set the Tab Index.
  • Enter the Error Display Name.
  • For most cases you want to leave the Read Only checkbox un-checked (Gigya screen-sets utilize the read-only property on certain screens, i.e., Registration Completion, in order to show previously entered data such as the user's email address).

Image

Adds an image placeholder to the screen.
Screen Shot 2016-07-11 at 11.45.43 am.png 

Usage

Drag the Image control from the left-hand Controls menu into the screen where you would like it to appear.

In the Properties window:
 

  • Set the size of the image frame (width and height. Width may be in percentages or pixels. Height may be only in pixels)
  • Enter the publicly-available URL of the image. Note that if the URL is HTTP, if displayed on a secure page, it will automatically be converted to a secure URL (HTTPS).
  • In the Fit to Frame dropdown, select how to position the image:
    • Fit - the image is shown in full within the frame allotted for the picture. The image is resized to fit the frame and proportions are constrained according to the larger of its width/height dimensions.
    • Fit Horizontally - the image's height is cropped to fit the allotted width.
    • Fit Vertically - the image's width is cropped to fit the allotted height.
    • Stretch - the image is stretched to fit the allotted frame.
  • Enter an Alternate Text to be used in case the user cannot view the image (e.g., text that will be read aloud by screen readers).
  • Apply a CSS Class, if necessary.
  • If the image is to be displayed only under certain conditions, under Visible When, enter the JavaScript expression that, if true, will cause the image to be displayed.

Login ID

Adds a Login ID input field within the screen for the user to enter their login id, this can be a username or email. The default label is email.

            

Usage

Drag the Login ID control from the left-hand Controls menu into the screen where you would like it to appear.

In the Properties window:

 

    • Enter a Label to be displayed for the field (or leave blank). If this field is Required, the placeholder text will not contain a default asterisk, so it must be included in the placeholder text.
    • Enter Placeholder Text to be displayed within the actual password field itself.
    • Set a custom Width (in px) if necessary.
    • Set the Tab Index.
    • Enter the Error Display Name.
    • Define whether you want this to be a Read Only field (for instance, if it is on the Profile Update screen and you do not want users to edit their Login Id's).
    • Define whether you want the ID Availability check-mark to display if their selected username is available, by selecting the Show ID availability checkbox.

       

      Show ID availability is only supported on the initial Registration Screen.

       

       

 

This Control is only applicable to the following screens:

  • Login screen within the RegistrationLogin Screen-Set.
  • Registration screen within the RegistrationLogin Screen-Set.
  • Forgot Password screen within the RegistrationLogin Screen-Set.

Password

Adds a password input field within the screen to collect data from the user. Among it's uses is to hide the inputted data as the user enters it in the field.

Usage

Drag the Password control from the left-hand Controls menu into the screen where you would like it to appear.

In the Properties window:

     

 

  • Select the Type parameter.  Here you define whether the field will represent one of the following:
    • Password                              
    • Password Confirmation
    • New Password
    • Old Password
  • Enter a Label to be displayed for the field (or leave blank). Note: If this field is Required, the placeholder text will not contain a default asterisk, so it must be included in the placeholder text.
  • Enter Placeholder text to be displayed within the actual password field itself.
  • Set a custom Width (in px) if necessary.
  • Set the Tab Index.
  • Enter the Error Display Name.
  • Choose the position of the pop-up helper. The choices available for display of the helper field are:
    • Disabled
    • Up
    • Right
    • Left
    • Down

Metadata

Adds a hidden field within the screen to collect, store or write data related to the user's interaction with the screen. You can store a static string, or create a JavaScript expression to dynamically generate the data.

Although it is possible to add a Metadata Control to any screen within a screen-set, it will only have an effect on screens which write data to the user's account, i.e., Registration, Registration Completion, Link Accounts, Edit Profile and Lite Registration.

Usage

Drag the Metadata control from the left-hand Controls menu into an available space of the screen (note that this field is not visible to the end user, so placement is not important, it also has a display property of none, so it will not impact the layout of any other items of the screen).

In the Properties window:

  1. Map the control to a field using the Mapped Fields drop-down.
  2. Set the Value format to either String or JavaScript expression.
    • If using String, set the Value to the string you want to define.
    • If using JavaScript expression, set the Value to the function you want to define the resulting data.

You will then be able to access the data for the registered user via the Identity Access tab of the Gigya Console, or using accounts.getAccountInfo for the user.

An example of viewing the data in Identity Access is below:

Dropdown

Adds a drop-down Select input field control.

Usage

Drag the Drop-down control from the left-hand Controls menu into the screen where you would like it to appear.

In the Properties window:

  • Map the control to a field using the Mapped Fields drop-down.
  • Enter a Label to be displayed for the field (or leave blank).
  • Set a custom Width (in px) if necessary.
  • Set the Tab Index.
  • Enter the Error Display Name.
  • Enter the choices you want to offer the user and their corresponding values, separated by an equal sign (=).

     

    • You can also choose from several predefined lists Gigya provides.
      • Countries
      • Years
      • Months
      • Days
      • Gender
      • U.S. States

 

Option group

Adds a radio button selection control.

Usage

Drag the Option group control from the left-hand menu into the UI Builder canvas of the screen where it will appear.

In the Properties menu:

  •  

    Dragging multiple Option group controls into the UI Builder canvas will create multiple unique selection lists. These will not be linked together.



    • Map the control to a field using the Mapped Fields drop-down.
    • Enter a Label to be displayed for the field (or leave blank).
    • Set the Tab Index.
    • Enter the Error Display Name.
    • Enter the choices you want to offer the user. e.g.,
      • Male
      • Female

      To designate one of the selections as pre-selected, use an asterisk *. If you want to use a literal * without a pre-selected radio button use \*. To use a literal * and designate the field as pre-selected, use **.
      i.e.,

      //Designate the first button as pre-selected
      *Yes = 1   // Result > [x] Yes
      No = 2     // Result > [ ] No
        
      //Designate the first button as pre-selected with a literal asterisk
      **Yes = 1  // Result > [x] *Yes
      No = 2     // Result > [ ] No
        
      // Designate the first button unselected with a literal asterisk
      \*Yes = 1  // Result > [ ] *Yes
      No = 2     // Result > [ ] No

 

Checkbox

Inserts a single checkbox that returns a true or false response whether clicked or not.

Usage

Drag the Checkbox control from the left-hand menu into the UI Builder canvas of the screen where it will appear.

In the Properties menu:

  • Map the control to a field using the Mapped Fields drop-down.
  • Enter a Label to be displayed for the field (or leave blank).
  • Set the default value of the checkbox when the screen is displayed:
    • No - (default) sets the box unchecked by default and returns a false value.
    • Yes - checks the box by default and returns a true value.
    • Conditionally - uses a JavaScript expression to determine whether the box is checked or not when the screen is displayed. If the expression validates to true the checkbox will be checked.

      This only sets the default value for the checkbox, so will only effect Registration screens. Once a user is created and a value is set in the schema for their account, this setting will not have any affect.

  • Set the Tab Index.
  • Enter the Error Display Name.
  • Add any required CSS Classes, if necessary.
  • Set the fields Visibility, if it is not required all the time.

     

 

Form Error

Adds an empty area to display general form error or errors not associated with any particular input field, i.e., Account Locked or Network Error.

Usage

Drag the Form Error control from the left-hand menu into the UI Builder canvas of the screen where it will appear.

In the Properties menu:

  • Enter the Width(px) to define how wide you would like it to appear when it is needed.

 

Spacer

Adds an empty space divider to separate two sections of the screen, vertically.

Usage

Drag the Spacer control from the left-hand menu into the UI Builder canvas of the screen where it will appear.

In the Properties menu:

  • Enter the Height Unit(s) to define how large of a space to use as a separator.
    • A single Height Unit is 1 line-height (10px).

Submit button

Adds a Submit button to the screen.

Usage

Drag the Submit button control from the left-hand menu into the UI Builder canvas of the screen where it will appear.

The Submit button will attempt to process the screen either completing the login process or proceeding to the next screen (or returning errors).

In the Properties menu:

  • Enter the text you want displayed on the button (value).
  • Set the Tab Index.

 

Standard Controls Common Properties

HTML

Most Control and Widget Labels support basic HTML, for styling the text, i.e., you can add a carriage return by including <br />.

 

Adding A Mapped Field

  1. Select the relevant field in the UI Builder.
  2. In the Mapped Field drop-down within the Properties menu, scroll to the bottom of the Data or Subscriptions tree, and select Add.
  3. Enter the details in the Add New... dialog:
  4. When finished, click Add.

If you belong to group that does not have the Edit schema permission enabled in the Groups Privileges, you will not be able to Add new fields to the schema, as this requires updating the site's schema.

Tab Index

When designing your screens within the UI Builder, you can set the Tab Index for all of the controls and widgets. Tab Index defines the order in which a user will arrive at the corresponding field via the tab key of their keyboard or which field will be tabbed to after any other given field within the screen (if a user tabs from any other field).

Error Display Name

This name is used in error messages bound to this field and defines the text that will display when the corresponding field is not filled out correctly. Error Display Name acts as a placeholder and replaces the name of the field within any error messages when it is defined, otherwise the name of the form field is displayed in the error message. This attribute correlates to the  data-display-name  attribute of the Gigya HTML Markup extensions.

 

CSS Classes

You can use the CSS Classes field to attach a custom CSS class to the field. The CSS can be defined either within the Screens Style page of the Screens section or on the page the screen will eventually display from.

 

 

Visible When

The Visible When field allows you to attach a JavaScript expression to a field that determines whether it is displayed to the user. If the javascript expression evaluates to false, the element is not displayed.

If a field has a condition, it will appear in the UI Builder with a dashed yellow border surrounding it, to differentiate it from normal fields.

 

Only insert the actual expression to evaluate, e.g.,

profile.firstName !==''

 

You can use various inherited property variables to test against, such as any of the schema Mapped Fields, as well as the accountInfo object (only available after a user is logged in, e.g., on Profile Update screens), i.e., 

accountInfo.loginProvider == 'facebook'

and the following additional variables:

  • screenset.width
  • screenset.height
  • screenset.translations
  • viewport.height
  • viewport.width
  • viewport.orientation

 

Widgets Controls

LoginID Availability  (Deprecated)

Adds a graphical popup when the user selects a username, letting them know if the name is available or not.

 

Usage

Drag the LoginID Availability control from the left-hand menu into the UI Builder canvas of the screen where it will appear.

The LoginID Availability control will search the database and let the user know if their chosen Username is already being used or not.

In the Properties menu:

  • Select which form field to bind the widget to.
    • Email
    • Username

Deprecation

Though the LoginID Availability widget is still available within the UI Builder, it has been replaced with the Login ID control Show ID Availability check box which can be toggled on/off for any applicable field via the field's Show ID Availability checkbox in the properties settings.

The Show ID Availability control provides the same function.

 

 

 

CAPTCHA

Adds a CAPTCHA ("Completely Automated Public Turing test to tell Computers and Humans Apart") to discourage bots and account harvesting.

This widget requires prior setup in your Accounts Policies.

Usage

Drag the CAPTCHA control from the left-hand menu into the UI Builder canvas of the screen where it will appear.

The CAPTCHA control will challenge the user to verify they are a human by requiring them to input a random code into the widget correctly in order to proceed.

In the Properties menu:

  • Select which theme you would like to use.
    • White (default)
    • Blackglass
    • Clean
    • Red
       

Social Login

Adds the ability to log users into your site via any of the supported social networks they have accounts with.

Usage

Drag the Social Login control from the left-hand menu into the UI Builder canvas of the screen where it will appear.

The Social Login control will display the graphic enabling the user to select which of the social networks they would like to use to login to your site.

In the Properties menu:

  • Choose Supported Providers
    • Input the comma separated list of social networks you would like to support.
      For the complete list of Gigya supported networks, please see the  Social Network Capabilities Table.
  • Choose the Button Style.
    • Full Logos - Colored (default)
      • Fully colored and labeled buttons with the name of the social network
    • Icons
      • Icons only, without the full name of the network.
    • Full Logos
      • Full logos, similar to the default, but without a fully colored background.

 

   


 

  • Set the individual Button Size (in pixels).
  • Set the Height (of the widget container, in pixels).
  • Set the Width (of the widget container, in pixels).
  • Choose the Mode.
    • Standard
    • Re-authentication
    • Link accounts
  • Choose the Version

2-Factor Authentication

Adds a widget that allows enabling of Two Factor Authentication (TFA) for users.

 

Usage

Drag the 2-Factor Authentication control from the left-hand menu into the UI Builder canvas of the screen where it will appear.

The 2-Factor Authentication  control will display the form allowing the user to enable TFA for their account.

This widget requires prior setup in your Accounts Policies.

In the Properties menu:

  • Choose the Mode:
    • Register
    • Verify
    • Edit

 

My Photo

Adds and/or displays the user's profile photo (replaces both the deprecated Photo Upload and Profile Photo widgets).

Usage

Drag the My Photo control from the left-hand menu into the UI Builder canvas of the screen where it will appear.

The My Photo  control can be used to both:

  • Allow the user to upload or change their profile photo (only available if the user is logged in).
  • Display the user's current photo.

In the Properties menu:

  • Set:
    • Allow Upload (default) -deselect  this to make the widget Display only.
    • Height (px)
    • Width (px)

   


The myPhoto widget is only applicable within screens of the RegistrationLogin, LinkAccounts and ProfileUpdate Screen-Sets.

 

New Releases

It is important to note that screen-sets, unlike other Gigya services which are dynamic, do not automatically update when new versions of code are released. Screen-Sets, once created in your Dashboard, are static. This enables the functionality to remain intact regardless of any new code changes implemented in upcoming Gigya releases. To enable new release functionality, you must create a new Screen-Set Collection after any new Gigya release if you want to take advantage of that functionality.

More Information

For a complete list of available Screen-Set parameters and responses please view accounts.showScreenSet JS.

If a User belongs to a group, the group must have the permission to Edit schema enabled or the user will not be able to perform the following actions:

  • Add a new custom field via the Mapped Field drop-down.
  • Change the setting of whether a field is always required.
  • Change a field's data type.
  • Change a field's regex format.
  • Enable encryption for a field.

 

This applies to the UI Builder, as well as any API's that perform the aforementioned functions.