simplePass

simplePass Function Parameters

• passwordModifier
• strengthCheck
• cFig

Usage Inside Of JavaScript

First we will just import the simplePass program and use it to console.log() various random strings.

                    
// Import simplePass
import simplePass from "YOUR_DIRECTORY_PATH/simplePass.bundle.js"

/**
* Generate a password with the default modifiers.
* Outputs similar to: 5UyO"Ir/nyB?Z65o0/3)Rm
*/
console.log(simplePass());
                    
                

As you can see integrating simplePass into your application can be as simple as two lines of code.

As we progress through this documentation we will create more complex examples of integration.

                    
// Generate a more complex random password.
const complexPass  = simplePass({
    length: 26,
    lowercase: true,
    uppercase: true,
    numbers: true,
    punctuation: true,
    lowercase_supplement:true
    excludeCharacters: 'abc'
});

console.log(complexPass)
// outputs similar to: tsøû}BpWe:o]M6õ1þJ4D$þ/84ù
                    
                

* Note: This documentation can not go through every possible form of integration into every type of application scenario. While it does go through many of the most common use cases, it is highly advised you use this documentation as a starting point for more complex integration scenarios. If you need further help please open a question on the GitHub Issues Board (you should also please read our Creating An Issue section of our Contributing documentation.)

Next let's add an element to our page to inject a random string into.

JavaScript

                    
// Get an element to display our password
const displayPassword = document.body.querySelector(".simplePass_passwordTarget");
// Get an element to display our entropy score.
const passwordEntropy = document.body.querySelector('.simplePass_passwordEntropy');

// Create our password
const initialPassword = simplePass(
            {
                length: 22,
                lowercase: true,
                uppercase: true,
                numbers: true,
                punctuation: true
            },
            {
                strengthCheck: {
                    entropyTarget: true
                }
            }
        );

// Set our 'display element' text to the password.
displayPassword.innerText = initialPassword.password;
// Set the 'password entropy' elements inner text to our passwords entropy.
passwordEntropy.innerText = Math.round(initialPassword.entropy);
                    
                

HTML

                    

    

        Password:
        
    
    

        Bits Of Entropy ~:
        
    

                    
                

Should produce something similar to:

Targeting An Inline Element

For this example we will:

1. import simplePass into our script;

2. Add the a class identifier to the element that is our desired password target;

3. Call the simplePass.init() function.

The simplePass.init() function can also determine if the element you are trying to target is an input and insert the password into the inputs value attribute instead of the innerText.

JavaScript

                    
// Import simplePass
import simplePass from "YOUR_DIRECTORY_PATH/simplePass.bundle.js";

// Call the initializer function
simplePass.init();
                    
                

HTML

                    


    Password:
    

                    
                

Given the above JavaScript and HTML the results should look something like the following:

Password:

Integrating With A Registration Form

A more practical use case for simplePass is the integration with a websites registration form.

For this example we will:

1. import simplePass into our script;

2. Add the following class identifier simplePass_passwordTarget to the element that is our desired password target;

3. Optionally: Add action buttons so your clients may Regenerate and Copy their generated password. Ensure these elements have their respective class identifiers set based on their configuration attributes.

4. Call the simplePass.init() function.

JavaScript

                    
// Import simplePass
import simplePass from "YOUR_DIRECTORY_PATH/simplePass.bundle.js";

// Call the initializer function
simplePass.init();
                    
                

HTML

                    

    Registration
    Username:
        
    
    Password:
        
    
    Regenerate Password
    Copy Password
    Register

                    
                

The result should look like something below:

Registration Username: Password: Regenerate Password Copy Password Register

Integrating A Modifier Form

If you would like your clients to have some customization over their password you must add an extra form with the necessary inputs.

simplePass will also set the default attributes for each input based on the default password modifiers configured.

The name attributes of these input elements must match the keys of the passwordModifier object.

For the following example we will take the the JavaScript and HTML from the previous example and modify the following:

1. Add a new form with the a unique id attribute.

2. Set the Regenerate buttons type attribute to "submit". Also set this buttons form attribute to the id of the new form we added.

3. Call the simplePass.init() function.

JavaScript

                    
// Import simplePass
import simplePass from "YOUR_DIRECTORY_PATH/simplePass.bundle.js";

// Call the initializer function
simplePass.init();
                    
                

HTML

                    


    Registration
    Username:
        
    
    
    Regenerate Password
    
    Copy Password
    Register



    Password:
        
    
    Lowercase Alpha:
        
    
    Uppercase Alpha:
        
    
    Numbers:
        
    
    Signs, Symbols, and Punctuation:
        
    

                    
                

Should produce the following:

From here you should be able to add any password modifier to your forms.

Batch Password Generation

simplePass also has the ability to generate batches of passwords if this is desired.

* Note: This is currently not a native feature of simplePass as it requires the use of the simplePass.init() function and can only be used in conjunction with a form. We understand this is inconstant and unitive to how the program should function and are working on a way to implement some form of batch option inside of the simplePass() function itself.

For this example we continue to use the same JavaScript example as the previous but we will only use the Password Modifier form from the previous example (as generating batches of passwords in not generally a registration use case).

We will als need to preform the following modifications:

1. Add a new input following the same naming convention as other form inputs.

2. Instead of setting our password target to an input element we will instead use an Inline Element such as a paragraph or span.

3. Our password target element must be nested inside of a separate element. We must give this element the class identifier of "simplePass_passwordContainer"

When you click the Regenerate button this time, if you have a set a batch amount of passwords simplePass will inject a list

JavaScript

                    
// Import simplePass
import simplePass from "YOUR_DIRECTORY_PATH/simplePass.bundle.js";

// Call the initializer function
simplePass.init();
                    
                

HTML

                    


    
        Password:
        
    


    
    Batch Amount:
        
    
    Lowercase Alpha:
        
    
    Uppercase Alpha:
        
    
    Numbers:
        
    
    Signs, Symbols, and Punctuation:
        
    
    Regenerate Password
    Copy Password

                    
                

Should produce the following:

Password Modifiers

Batch Amount: Lowercase Alpha: Uppercase Alpha: Numbers: Signs, Symbols, and Punctuation: Regenerate Password Copy Password

Password Stats

simplePass has the ability to display various stats about the generated password such as:

• Bits of Entropy
• Possible Combinations
• Binary Information
• Percentage of Unique Characters

Building upon our previous examples we will add a Passwords Stats section and display some stats.

* Note: When using Batch Password Generation simplePass will initially only display the stats for the last generated password. Clicking on generated passwords will update the stats.

* Note: If you are using Batch Password Generation ensure you are not putting your Entropy Target inside of your Password Container or else it will be removed when generating passwords.

JavaScript

                    
// Import simplePass
import simplePass from "YOUR_DIRECTORY_PATH/simplePass.bundle.js";

// Call the initializer function
simplePass.init();
                    
                

HTML

                    

    
    

        
            Password:
            
        
    
    
    

        

            Password Stats
        
        

            Bits of Entropy:
            
            
        
        

            Possible Combinations
            
            
        
        Binary String For Password:
            
        
        

            Average Character Bit Length:
            
            
        
        

            Binary String Length:
            
            
        
        

            Percentage Of Unique Characters:
            
            
        
    


    
    Batch Amount:
        
    
    
    Lowercase Alpha:
        
    
    Uppercase Alpha:
        
    
    Numbers:
        
    
    Signs, Symbols, and Punctuation:
        
    
    Regenerate Password
    Copy Password

                    
                

Should produce something similar to:

Batch Amount: Lowercase Alpha: Uppercase Alpha: Numbers: Signs, Symbols, and Punctuation: Regenerate Password Copy Password

Error Messages

Due to simplePass being part standalone application it needs the ability to handle and display various messages to the user, such as an Error Message or Invalid Input Message. If this might not be entirely suitable for your needs thus you can disable this feature as well and have simplePass resort to throwing exceptions that can be caught by your application.

To enable simplePass messaging you can add a messages.messageBoard attribute to your simplePass.config file with a DOM Query String that references an element that simplePass can attach messages to (default value: ".simplePass_messageBoard").

Using the following code.

JavaScript

                    
// Import simplePass
import simplePass from "YOUR_DIRECTORY_PATH/simplePass.bundle.js";

// Call the initializer function
simplePass.init();
                    
                

HTML

                    

    
    

        

            Password:
            
        
    
    
    

        Bits Of Entropy ~: 
    


    
    

    
    
    Batch Amount:
        
    
    
    Lowercase Alpha:
        
    
    Uppercase Alpha:
        
    
    Numbers:
        
    
    Signs, Symbols, and Punctuation:
        
    
    Regenerate Password
    Copy Password

                    
                

Should produce something to the similar

Batch Amount: Lowercase Alpha: Uppercase Alpha: Numbers: Signs, Symbols, and Punctuation: Regenerate Password Copy Password

Attempting to create a password without any modifiers should trigger an Error and result in a message being added to the board.