chamilo-lms2/public/assets/pwstrength-bootstrap/OPTIONS.md

Options

The plugin expect the options to follow this structure:

options = {
    common: {},
    rules: {},
    ui: {}
};

Let's see the options of each section.

Common

• minChar:

Default: 6 (Integer)

Sets the minimum required of characters for a password to not be considered too weak.

• usernameField:

Default: "#username" (String)

The username field to match a password to, to ensure the user does not use the same value for their password.

• userInputs:

Default: [] (Array)

Array of CSS selectors for input fields with user input. The content of these fields will be retrieved and passed to the zxcvbn library.

This option only takes effect when the zxcvbn library is being used. Check the zxcvbn option.

• onLoad:

Default: undefined (Function)

A callback function, fired on load of the widget. No arguments will be passed.

• onKeyUp:

Default: undefined (Function)

A callback function, fired on key up when the user is typing. The keyup event will be passed as first argument, and an object as second with the score and the verdict text and level.

This handler will also be called when the change or the onpaste events happen.

• onScore:

Default: undefined (Function)

A callback function that will be called when the score is calculted by the rules engine, allowing for a final modification before rendering the result.

The options, the word and the score will be passed as arguments, in that order.

• zxcvbn:

Default: false (Boolean)

Use the zxcvbn to calculate the password entropy and use it as the score. For more information about zxcvbn plase check this post.

If you activate this setting, then all the rules won't be applied, and all the options under the Rules section will be ignored as well. zxcvbn will be used instead of the default rules engine.

To use this option you must load the zxcvbn library file on your site. You'll find it at their repository.

• zxcvbnTerms:

Default: [] (Array)

An array of strings. A list of banned words for the zxcvbn library. This option will be ignored if zxcvbn is not being used.

• events: ["keyup", "change", "paste"] (Array)

An array of strings. A list of the event names the plugin is going to listen to. Customize this option to deal with iOS 9 keyup bug.

• debug:

Default: false (Boolean)

If true, it prints the password strength in the javascript console, so you can test and tune your rules settings.

Rules

• extra:

Default: {} (Object)

Empty object where custom rules functions will be stored.

• scores:

Default: (Object)

  {
    wordNotEmail: -100,
    wordLength: -50,
    wordSimilarToUsername: -100,
    wordSequences: -50,
    wordTwoCharacterClasses: 2,
    wordRepetitions: -25,
    wordLowercase: 1,
    wordUppercase: 3,
    wordOneNumber: 3,
    wordThreeNumbers: 5,
    wordOneSpecialChar: 3,
    wordTwoSpecialChar: 5,
    wordUpperLowerCombo: 2,
    wordLetterNumberCombo: 2,
    wordLetterNumberCharCombo: 2
  }

Scores returned by the rules when they match. Negative values are for penalizations.

• activated:

Default: (Object)

  {
    wordNotEmail: true,
    wordLength: true,
    wordSimilarToUsername: true,
    wordSequences: true,
    wordTwoCharacterClasses: false,
    wordRepetitions: false,
    wordLowercase: true,
    wordUppercase: true,
    wordOneNumber: true,
    wordThreeNumbers: true,
    wordOneSpecialChar: true,
    wordTwoSpecialChar: true,
    wordUpperLowerCombo: true,
    wordLetterNumberCombo: true,
    wordLetterNumberCharCombo: true
  }

An object that sets wich validation rules are activated. By changing this object is possible to deactivate some validations, or to activate them for extra security.

• raisePower:

Default: 1.4 (Double)

The value used to modify the final score, based on the password length, allows you to tailor your results.

User Interface

• bootstrap2:

Default: false (Boolean)

Sets if it supports legacy Bootstrap 2 (true) or the current Bootstrap 3 (false), the progress bar html is different.

• bootstrap4:

Default: false (Boolean)

Sets if it supports unstable Bootstrap 4 (true) or the current Bootstrap 3 (false), the progress bar html is different. Keep in mind that the current Boostrap 4 support is very basic.

• colorClasses:

Default: ["danger", "danger", "danger", "warning", "warning", "success"] (Array)

The css classes applied to the bar in the progress bar and to the verdicts, depending on the strength of the password.

Keep in mind that for Boostrap 2 a bar- prefix will be added, that for Boostrap 3 the prefix will be progress-bar-, and that for Bootstrap 4 it will be progress-. This is the case for the progress bar, not the verdicts. For the verdicts there is no prefix whatsoever.

• showProgressBar:

Default: true (Boolean)

Displays the password strength in a progress bar.

• progressExtraCssClasses: (Bootstrap 3&4 only)

Default: "" (String)

CSS classes to be added to the generated progress wrapper of the progress-bar. It is meant to make use of the extra classes provided by Bootstrap. The classes will be added to the proper DOM element depending of which version of Bootstrap is being used.

E.g.

    div.progress.custom-class {
        height: 4px;
        border-radius: 0px;
        background-color: transparent;
    }
    div.progress.custom-class > .progress-bar {
        line-height: 4px;
        font-size: 2px;
    }

• progressBarEmptyPercentage:

Default: 1 (Integer)

Minimum percentage filled in the progress bar that depicts the strength of the password. An empty password will show the progress bar filled this much.

• progressBarMinPercentage:

Default: 1 (Integer)

Minimum percentage filled in the progress bar that depicts the strength of the password. A terrible but not empty password will show the progress bar filled this much.

• progressBarExtraCssClasses:

Default: "" (String)

CSS classes to be added to the generated progress bar. It is meant to make use of the extra classes provided by Bootstrap. The classes will be added to the proper DOM element depending of which version of Bootstrap is being used.

• showPopover:

Default: false (Boolean)

Displays the error messages and the verdicts in a Bootstrap popover, instead of below the input field. Bootstrap tooltip.js and popover.js must to be included.

If the showVerdictsInsideProgressBar option is active, then the verdicts won't appear on the popover.

• popoverPlacement:

Default: "bottom" (String)

Choose where the popover should be placed in relation with the input field. The possible options are: "top" "bottom" "left" "right" "auto"

• showStatus:

Default: false (Boolean)

Displays the password strength as a validation status in the password field, for this to work, the Bootstrap form structure must be followed.

• spanError:

Default: (Function)

  function (options, key) {
    var text = options.i18n.t(key);
    if (!text) { return ''; }
    return '<span style="color: #d52929">' + text + '</span>';
  };

Function to generate a span with the style property set to red font color, used in the errors messages. Overwrite for custom styling.

• popoverError:

Default: (Function)

  function (errors) {
    var errors = options.instances.errors,
        errorsTitle = options.i18n.t("errorList"),
        message = "<div>" + errorsTitle + "<ul class='error-list' style='margin-bottom: 0;'>";

    jQuery.each(errors, function (idx, err) {
      message += "<li>" + err + "</li>";
    });
    message += "</ul></div>";
    return message;
  };

Function to generate the errors list in the popover if showPopover is true. Overwrite for custom styling.

• showVerdicts:

Default: true (Boolean)

Determines if the verdicts are displayed or not.

• showVerdictsInsideProgressBar:

Default: false (Boolean)

Determines if the verdicts are displayed inside the progress bar or not. When this setting is active, the verdict viewport is ignored and they won't appear on the popover if it is being showed. Also this option overrides the value of the showVerdicts one.

This option is not available when using Bootstrap 4.

• useVerdictCssClass:

Default: false (Boolean)

Determines if it's necessary to add a css class in the verdict element.

• showErrors:

Default: false (Boolean)

Determines if the error list is displayed with the progress bar or not.

• showScore:

Default: false (Boolean)

Determines if the password score is displayed with the progress bar or not.

• container:

Default: undefined (CSS selector, or DOM node)

If defined, it will be used to locate the viewports, if undefined, the parent of the input password will be used instead. The viewports must be children of this node.

• viewports:

Default: (Object)

  {
    progress: undefined,
    verdict: undefined,
    errors: undefined,
    score: undefined
  }

An object containing the viewports to use to show the elements of the strength meter. Each one can be a CSS selector ("#progressbar") or a DOM node reference. They must be contained by the container.

• scores:

Default: [0, 14, 26, 38, 50] (Array)

The scores used to determine what colorClasses and verdicts to display. It has to have 5 elements, which creates 6 categories of strength (the 6 possible verdicts).

Example of an options object

var options = {};
options.common = {
    minChar: 8
};
options.rules = {
    activated: {
        wordTwoCharacterClasses: true,
        wordRepetitions: true
    }
};
options.ui = {
    showErrors: true
};