npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

mod-build

v3.7.8

Published

Share components for S3 sites.

Downloads

3,251

Readme

About

This package is created to be used on microsites that contain forms. It helps streamline development by providing flexible reusable components for forms such as:

  • data for form fields (e.g. list of states, hvacSystemTypes, etc.);
  • form error texts for each field;
  • configurable Javascript object modSite (mod-site.js) for handling form validation, switching steps, processing and submitting data to the backend, and handling backend responses;
  • Javascript object for thank you page ads;
  • helper Javascript object modUtils for variuos related methods used in modSite or thank you page;
  • templates for about, terms, and privacy pages (with variables for company name, website name, emails, etc.)

Structure

  • src/
    • data/common.js - form fields options, form errors, TCPA copy, list of state names and abbreviations
    • scripts/
      • components/
        • custom-selects.js - object for custom selects
        • modal-pages.js - object for opening links in modal windows
        • radio-panels.js - object for radio panels
      • vendor/ - shared third party scripts
        • heap-addeventproperties-identify.js
        • heap-tracking.js
        • heap-vwo.js
        • maxmind-geoip2.js
      • apt-block.js - used for rendering the set appointments widget (see appointments widget repo)
      • mod-form-pro.js - object for handling pros forms
      • mod-form.js - object for handling forms
      • mod-utils.js - helper object
      • thankyou.js - object for thankyou page
    • styles/
      • partials/ - contains useful SASS partials & mixins; should be imported into project's SASS files
      • apt-block.scss - styles for appointment block
    • templates/
      • _partials/scripts/ - GTM, VWO, and Google Maps script tags
      • modals/ - templates for about, terms, and privacy pages
  • .babelrc - config file for Babeljs
  • .editorconfig - rules for code editors based on company's code guidelines
  • .eslintrc.yml - configuration for Javascript linter
  • .sass-lint.yml - configuration for SASS/SCSS linter
  • gulpfile.babel.js - Gulp file for automations
  • package-lock.json - lock file for package.json; makes sure that the same versions of Node modules are installed across env
  • package.json - Node modules used in mod-site

Installation

mod-site is added as a dependant package (in package.json) to all S3 sites by default.

modForm object

Init modForm for windows trade example:

modForm.init({
  vertical: 'windows'
});

modForm.init() method options

| Option | Required | Default value | Description | |---|---|---|---| | vertical | Yes | null | Form's vertical. Possible options are: solar, windows, roof, hvac | | form | Yes | $('#form') | jQuery form object | | formLoadingCls | Yes | form--loading | CSS class for a loading state of the form | | stepsSelector | Yes | [data-bind="step"] | CSS selector for form's steps | | stepActiveCls | Yes | step--active | active step CSS class | | tcpaCopy | Yes | $('#tcpa-copy') | jQuery object of a TCPA copy block | | maskedPhoneFields | No | $('#form').find(':input[name="homePhone"]') | jQuery object of inputs to add phone mask to | | numericsOnlyFields | No | $('#form').find(':input[name="zip"], :input[name="zip1"]') | jQuery object of digits only inputs (e.g. phone and zip) | | addressField | No | $('#form').find(':input[name="address"]') | jQuery object of an address field | | stateField | No | $('#form').find(':input[name="state"]') | jQuery object of a state field | | cityField | No | $('#form').find(':input[name="city"]') | jQuery object of a city field | | zip1Field | No | $('#form').find(':input[name="zip1"]') | jQuery object of secondary zip field | | zipField | Yes | $('#form').find(':input[name="zip"]') | jQuery object of primary zip field | | repairField | No | $('#form').find(':input[name="repair"]') | jQuery object of repair field | | hvacWouldReplaceBlock | No | $('#hvac-would-replace-block') | HVAC only. Block that contains wouldReplace control. | | hvacSystemTypeField | No | $('#form').find(':input[name="hvacSystemType"]') | HVAC only. System type field. | | hvacFuelTypeBlock | No | $('#hvac-fuel-type-block') | HVAC only. Block that contains hvacFuelType control. | | hvacSystemTypesWithFuel | No | 'Central Heating', 'Boiler' | HVAC only. Array of hvac system types (lowercase) that require fuel type selection. | | fieldErrorCls | Yes | has-error | CSS error class. | | errorParentCls | No | parent-error | CSS class of a field parent which will get fieldErrorCls on error. | | gaTracker | No | main | GA tracker to use | | thankyouPage | Yes | /thankyou/ | Thankyou page URL. | | landingPage | No | window.location.href | Landing page URL. |

modForm.init() method Callbacks

| Callback | Options | Return | Description | |---|---|---|---| | formSubmittingCallback | formData | formData | Fires right before form is submitted. Allows to change data that will be sent to the API. If you return false inside the callback, the submission will stop. | | formSubmitSuccessCallback | | response | Fires when submitting form data to server was successful. Returns server response. Return false inside this callback to stop form from redirecting to TY page. | | formSubmitErrorCallback | | response | Fires when submitting form data to server returned an error. Returns server response. | | stepChangingCallback | oldStepId, stepId | stepId | Fires right before the step switches. Return stepId to switch to that step or false to stop | | stepChangedCallback | oldStepId, stepId | | Fires right after the step was switched. | | zipCodeValidated | | geoData | Fires right after the zip code has been validated on the server. Returns geo data: city and state for this zip code. |

modForm methods

Below are most useful methods of the modForm object.

| Method | Options | Return | Description | |---|---|---|---| | showStep | stepId | | Shows form's step by id. | | showNextStep | | | Shows form's next step. | | showPrevStep | | | Shows form's prev step. | | getCurrentStep | | $step | Returns form's current step as a jQuery object. | | isCurrentStepLast | | true or false | Returns true/false if current step is the last one in the form. | | getFormData | | Object | Returns form's data as a key/value object. |

Templates

We use Handlebars.js as a template engine. It allows us to use includes, loops, variables, etc. in our templates.

Available variables

| Variable | Type | Example | Description | |---|---|---|---| | year | Integer | {{year}} | Current year. | | tcpa | Function | {{#x 'this.tcpa("Get matches", "Modernize")'}}{{/x}} | Shows TCPA copy. You can pass in button name and company name as properties. | | formErrors | Object | {{formErrors.firstName}} | Form errors. Support properties: firstName, lastName, streetAddress, city, state, zip, email, homePhone, tradeQuestion | | states | Array | {{#each states}} ... {{/each}} | | | solar.shade | Array | {{#each solar.shade}} ... {{/each}} | | | solar.electricBill | Array | {{#each solar.electricBill}} ... {{/each}} | | | windows.repair | Array | {{#each windows.repair}} ... {{/each}} | | | windows.repair | Array | {{#each windows.repair}} ... {{/each}} | | | windows.hear | Array | {{#each windows.hear}} ... {{/each}} | | | windows.style | Array | {{#each windows.style}} ... {{/each}} | | | hvac.project | Array | {{#each hvac.project}} ... {{/each}} | | | hvac.repair | Array | {{#each hvac.repair}} ... {{/each}} | | | hvac.hvacSystemFuelTypes | Array | {{#each hvac.hvacSystemFuelTypes}} ... {{/each}} | | | hvac.hvacSystemTypes | Array | {{#each hvac.hvacSystemTypes}} ... {{/each}} | | | hvac.hvacFuelTypes | Array | {{#each hvac.hvacFuelTypes}} ... {{/each}} | | | roofing.repair | Array | {{#each roofing.repair}} ... {{/each}} | | | roofing.material | Array | {{#each roofing.material}} ... {{/each}} | |

Using partials

Example: including VWO & GTM snippets into a project:

<!DOCTYPE html>
<head lang="en">
  {{ fileInclude 'node_modules/mod-site/src/templates/_partials/scripts/visual-website-optimizer.html' }}
  {{ fileInclude 'node_modules/mod-site/src/templates/_partials/scripts/google-tag-manager-head.html' }}
  ...
</head>
<body>
  {{ fileInclude 'node_modules/mod-site/src/templates/_partials/scripts/google-tag-manager-body.html' }}
  ...

You can use variables from mod-site package and project itself inside any template.

Example: displaying hvacSystemType select using data from mod-site:

<select class="form-control" name="hvacSystemType" data-required="nonempty">
  <option value="">- Select system -</option>
  {{#each hvac.hvacSystemTypes}}
  <option value="{{this.value}}">{{this.name}}</option>
  {{/each}}
</select>

More on using variables and conditions can be found on Handlebars.js website.

Form and steps markup

modForm object is flexible, and you can pass you own jQuery selector for steps, but the following markup is default:

<!-- Form -->
<form class="form" id="form" method="" action="" novalidate="">
  <!-- Step 1 -->
  <div class="step step--active" data-bind="step" id="step-1">
    ...
  </div>
  <!--/Step 1 -->

  <!-- Step 2 -->
  <div class="step" data-bind="step" id="step-2">
    ...
  </div>
  <!--/Step 2 -->

  <!-- Step 3 -->
  <div class="step" data-bind="step" id="step-3">
    ...
    <div class="form-group">
      <button class="btn btn-primary" type="submit">
        Get matches &rarr;
      </button>
    </div>

    <div class="tcpa-copy">
      <input name="originLeadId" id="originLeadId" type="hidden" />
      <input name="leadToken" id="leadid_token" type="hidden" />
      <input id="leadid_tcpa_disclosure" type="hidden" />
      <label for="leadid_tcpa_disclosure" id="tcpa-copy">
        {{#x 'this.tcpa("Get matches")'}}{{/x}}
      </label>
    </div>
  </div>
  <!--/Step 3 -->
</form>
<!--/Form -->

Validation and steps logic

When user clickes on submit button inside step 1 (or submits it using Enter from a text field), modForm will loop through all required fields inside step 1 and validate them. If there's an invalid field, it will be highlighted and the form won't be switched to the next step.

If step is valid, modForm will:

  • check if step is not last (in DOM):
    • If step contains input with name zip or zip1, it will freeze the form and validate its value with the backend:
      • if it is valid, it will proceed;
      • if not, error will be shown;
    • If the step is valid, it will switch to the next step in the DOM;
  • if step is last (in DOM), modForm will send data to the backend:
    • if backend responds with errors, it will highlight all fields with errors and switch the form to the first step that has invalid fields;
    • if backend responds with success, it will redirect to the thankyou page.

You can use modSite callbacks and methods to alter the logic (e.g. to switch to specific step when user selected homeowner = No).

Fields validation and errors

modForms supports the following validation methods:

  • nonempty - value of a control should be non-empty
  • email - expects valid email address
  • phone - expects valid US phone number
  • zip - expects valid US zip code
  • regex - custom Regex
  • int - expects integer value (min and max are optional)

Validation method for a control is set in html attribute data-required.

Example: required email control with error message

<div class="parent-error">
  <input type="email" name="email" placeholder="Email" class="form-control" data-required="email" />
  <div class="form-error">
    {{formErrors.email}}
  </div>
</div>

More details about the markup:

  • data-required="email" on input defines validation method
  • wrapper <div class="parent-error"> will get class has-error if this field is not valid
  • {{formErrors.email}} is a default error message for invalid email field

Setting up modForm

modForm requires the following files to work:

  • /node_modules/jquery/dist/jquery.js
  • /node_modules/jquery-mask-plugin/dist/jquery.mask.min.js
  • /node_modules/mod-site/src/scripts/mod-utils.js
  • /node_modules/mod-site/src/scripts/mod-form.js

Default options for modForm can be found in mod-form.js file (with comments). The only required setting is vertical.

Example: setting up modForm for a windows form

modForm.init({
  vertical: 'windows'
});

License

This project is licensed under the MIT license.

Copyright (c) 2017 Modernize.