Form UI Component

Overview

The form component provides the capability to validate and submit multiple passwords in a single operation. This is commonly employed in situations where the application prompts the user to change their password.

Embed the Form UI component

The Form UI component is intricately linked with the Password UI Component. It necessitates the initialisation of one or more Password UI Component which are initialised via the form component.

tip

To use Weavr UI components, you must first set up the Weavr UI library in your application.

const form = weavrComponents.form();

Mounting

To display the components on the screen, it's necessary to mount it to the DOM. This involves creating a wrapping element that will serve as the container for injecting the secure frames. Be sure to assign an id to the HTML element.

Each Password UI Component needs to be mounted individually to the wrapping elements.

<!--login.html-->
<form onSubmit="onSubmit(); return false;">
  Password:
  <div id="password-example"></div>

  Confirm Password:
  <div id="confirmPassword-example"></div>

  Extra Confirm Password:
  <div id="extraConfirmPassword-example"></div>

  <input type="submit" value="Submit" />
</form>

// secure-form.js
const password = form.password(name, options);
password.mount("#password-example");

const confirmPassword = form.password(name, options);
confirmPassword.mount("#confirmPassword-example");

const extraConfirmPassword = form.password(name, options);
extraConfirmPassword.mount("#extraConfirmPassword-example");

Look and feel

The Form UI Component does not have a universal form styling. Styling should be applied individually to the Password UI Components within the form. Each Password UI Component can be styled differently. Refer to the documentation of the Password UI Component options properties for more details.

// secure-form.js
const password = form.password(name, {
  placeholder: "Password",
  style: {
    // Properties as per Password UI Component documentation
  },
});
password.mount("#password-example");

const confirmPassword = form.password(name, {
  placeholder: "Confirm Password",
  style: {
    // Properties as per Password UI Component documentation
  },
});
confirmPassword.mount("#confirmPassword-example");

---

API functions

You can interact with the library's components by utilizing the exposed functions. The below is a list of functions exposed for the Form component.

password

Provides the ability to initialise a Password UI Component within the form.

form
  .password
  // Password UI Component Parameters
  ();

match

The match function can be used to verify that all values entered in each Password UI Component within the form are consistent.

form.match(
  inputNames //String Array - The names of each Password UI Component that requires to be matched.
);

createToken

This function provides the capability to tokenise all Password UI Component values found in the form. A promise is returned and the resolved value is the tokenised value.

form.createToken();

destroy

The destroy function can be used to remove the element and its references from the DOM.

note

Once a component is destroyed it cannot be remounted. The component will be removed from Document Object Model (DOM) alongside any references and will need to be re-initialised.

form.destroy();

---

Examples

1. Form matching

Verifying the match between two password inputs is straightforward. Simply create multiple password components within the same form and invoke the match function, which returns a promise. If the passwords match, the promise is resolved; otherwise, it is rejected. Additionally, you can specify which input components to match by providing the respective component names.

<!-- Define a form in which you will ask your customer to input their new password -->
<form onSubmit="onSubmit(); return false;">
  Password:
  <div id="password"></div>

  Confirm Password:
  <div id="confirmPassword"></div>

  Extra Confirm Password:
  <div id="extraConfirmPassword"></div>

  <input type="submit" value="Submit" />
</form>

<script lang="js">
  const form = weavrComponents.form();
  const passwordComponent = form.password(
    "primaryPassword", // component name
    {
      placeholder: "Password",
    }
  );
  const confirmPasswordComponent = form.password("confirmPassword", {
    placeholder: "Confirm password",
  });
  const extraConfirmPasswordComponent = form.password("extraConfirmPassword", {
    placeholder: "Extra Confirm password",
  });

  passwordComponent.mount("#password");
  confirmPasswordComponent.mount("#confirmPassword");
  extraConfirmPasswordComponent.mount("#extraConfirmPassword");

  function onSubmit() {
    // Match all password inputs
    form
      .match()
      .then(() => {
        // All three password inputs have matched
      })
      .catch((e) => {
        // Mismatched password, confirmation password and extra confirmation password
        // or other error while creating the tokens
        console.log(e.message);
      });

    // Only match the first two password inputs
    form
      .match(["primaryPassword", "confirmPassword"])
      .then(() => {
        // The primary and confirm passwords have matched, the extra confirm password input is ignored
      })
      .catch((e) => {
        // Mismatched password and confirmation password
        // or other error while creating the tokens
        console.log(e.message);
      });
  }
</script>

2. Change password

If you want to change a password, you will need to tokenise the old and new password. This can be easily done using 2 password components in the same secure form.

warning

Due to requirements related to strong customer authentication, your authentication token is required to be stepped-up when updating your password.

<!-- Define a form in which you will ask your customer to input their new password -->
<form onSubmit="onSubmit(); return false;">
  Old Password:
  <div id="oldPassword"></div>

  New Password:
  <div id="newPassword"></div>

  <input type="submit" value="Submit" />
</form>

<script>
  const form = weavrComponents.form();
  const oldPasswordComponent = form.password("secure-oldPassword", {
    placeholder: "Old Password",
  });
  const newPasswordComponent = form.password("secure-newPassword", {
    placeholder: "New password",
  });

  oldPasswordComponent.mount("#oldPassword");
  newPasswordComponent.mount("#newPassword");

  function onSubmit() {
    form
      .createToken()
      .then((res) => {
        // Successfully created token
        console.log(res);

        // Outputs:
        // {
        //   "tokens": {
        //     "secure-oldPassword": "{{ token1 }}",
        //     "secure-newPassword": "{{ token2 }}"
        //   }
        // }
      })
      .catch((e) => {
        // Error while creating the tokens
      });
  }
</script>