htmlguyllc-jpack v0.1.8

Build Status

jPack

jPack is a vanilla javascript library of components, classes, plugin wrappers, and utilities designed to make building custom websites and web applications simpler.

But why?

Many plugins and libraries are too generic, verbose, bulky, lacking, or have a lot of dependencies. Much of what is included here is stuff that I've written several times, in several different ways, using jQuery in the past (or wrapping other jQuery plugins). The goal of this library is to allow me (and you, now that it's open source) to integrate slim, mostly dependency-free, components as-needed with more specific use-cases than what is currently offered elsewhere.

...where else can you get a component to grab a form from another page and stick it on the current one with XHR and XHR submission in 4 lines of custom JS?

Installation

Standard Global

Download the latest release, unzip and move it into your website's public folder, then include it in your HTML.

Use either jpack.min.js or jpack.bundled.min.js, BUT NOT BOTH. The bundled file includes the dependencies and you don't need them if you already have them in your project.

<script href="/@htmlguyllc/jpack/dist/jpack.bundled.min.js">
<!-- <script href="/@htmlguyllc/jpack/dist/jpack.min.js"> -->

<script>
//wait for the page to finish loading so we know jpack is ready
window.addEventListener('load', function() {
    
    //now you can take advantage of the jpack library
    jpack.strings.ucfirst('bob'); //Bob
    
    //if you want to change the namespace
    jpack.setGlobal("$");
    
    $.strings.ucfirst('bob');
    
    //if you want to make all global without a namespace - do so at your own risk! Things may conflict!
    jpack.setGlobal();
    
    strings.ucfirst('bob');
};
</script>

With NPM or Yarn:

npm i @htmlguyllc/jpack;
//or
yarn add @htmlguyllc/jpack;

ES6 (Babel)

//a single component from it's own file
import {strings} from '@htmlguyllc/jpack/es/strings';
strings.ucfirst('bob');

//or multiple components from jpack
import {strings, dom} from '@htmlguyllc/jpack';
strings.ucfirst('bob');
dom.exists('a.my-link');

//or a namespaced object containing all components
import * as j from '@htmlguyllc/jpack';
j.strings.ucfirst('bob');

CommonJS (Browserify)

var jpack = require('@htmlguyllc/jpack');

//now use it
jpack.strings.ucfirst('bob');

Dependencies

Documentation

To use:

import {navigation} from '@htmlguyllc/jpack/es/navigation';

/**
* Shown with defaults, you don't need to provide all of these, just what you want to modify
* If the defaults are fine, you don't need to call setConfig()
*/
navigation.setConfig({
     trackHistory:false, //keep track of URLs loaded in an array (see setters/getters above for how to retrieve records)
     pushState:true, //push new URLs to the browser's history
     loaderEnabled:true, //show a loader during the request process
     loaderDelay:300, //how long the request needs to take before the loader is shown
     incomingElementSelector:'body', //what element in the content from the URL should be grabbed
     replaceElementSelector:'body', //what element on the page should be replaced with the incoming one
     loaderClasses:'progress page-navigation-loader', //the loader consists of two divs (outer/inner) and uses Bootstrap 4's progress-bar classes (no styling is included so you should either add Bootstrap, change these classes and add your own styling, or just disable the loader)
     loaderInnerDivClasses:'progress-bar progress-bar-striped progress-bar-animated',
});

//attaches event handlers to automatically use XHR to reload pages when the user pushes the back and forward buttons in their browser (will not work if pushState is false)
navigation.initHistoryHandlers();

/**
* Add as many onBeforeRequest callbacks as you'd like to run every time a page is loaded
* 
* el is the element about to be replaced
* data the data object you set when you called .load() or using setData/setDataItem (see above method details) - the two objects are merged and passed
* config is an object {selector, replacedSelector, route}
*    selector is the "replaceSelector" used to grab the current element (to be replaced)
*    incomingSelector is the selector that will be used to grab the new element
*    route is the current page's route
*/
navigation.onBeforeRequest(function(el, data, config){ 
   //...do something...like...show a custom loader? validate data?
   return true; //if you return false from ANY of your onBeforeRequest callbacks, the request will be prevented!
});

/**
* Add as many onload callbacks as you'd like to run every time a page is loaded
* 
* el is the new element on the page
* data the data object you set when you call .load() or using setData/setDataItem (see above method details)
* config is an object {selector, replacedSelector, route}
*    selector is the "incomingSelector" used to grab the new element
*    replacedSelector is the selector used to find the element that was replaced
*    route is the new page's route (if set in JSON or HTML response)
*/
navigation.onload(function(el, data, config){
    
    //some things you might want to run every time a page loads:
   
   //if gtag is set (google analytics), push a page view
   if( typeof gtag !== 'undefined' ) {
       gtag('config', 'GA_MEASUREMENT_ID', {
           page_path: request.getURIWithQueryString()
       });
   }
   
   //if trackHistory is true, you can grab the last history record (or all - see getters/setters above)
   var last_history = navigation.getLastHistoryRecord();
   if( last_history ){
       const last_url = last_history.url;
       const last_route = last_history.route;
   }
   
   //scroll to the top of the page
   window.scrollTo(0, 0);
   
   //.. do more...like init tooltip plugins
});

/**
* Add as many unload callbacks as you'd like to run every time a page is loaded (just before the new HTML is replaced with the old)
* 
* Params are the same as onload except config doesn't have replacedSelector
* 
* Keep in mind this is the element that will be removed shortly (and config.selector is the selector used to retrieve that element) 
* 
*/
navigation.onUnload(function(el, data, config){
   //.. do something...like remove event handlers or destroy plugins 
});

/**
* Adds as many failure callbacks you'd like to run every time a page fails to load
* 
* error is the string message
* url is the requested URL that failed
* data is the data you provided to be passed onto that page
* axios_error is an error object set by axios that will be available if that's where the error occurred
*/
navigation.onFail(function(error, url, data, axios_error){
    //.. do something...like show an error popup for the user or log the issue
});

/**
* Now load pages!
* 
* It might look strange to you that you're passing values that are already in-scope for your callback. 
*    This is done for 2 reasons. 
*       1) It protects the data you passed from modification (your object is cloned inside .load())
*       2) It passes that object to all the global onload() callbacks as well
*/
let data = {pass_this:'hi!'};
navigation.load('/my-url', data, function(el, data, config){ 
    const passed = data.pass_this; //passed = 'hi!'
});

/**
* One of the easiest ways to use this plugin is to tie an event handler to onClick of any link containing a class or attribute
* In this example, all you have to do is add data-href in your link (like this: <a href="my-url" data-href>Link</a>)
*/
import {events} from '@htmlguyllc/jpack/es/events';

events.onClick('[data-href]', function(){
   navigation.load(this.href);
});

/**
* Want to pass a value to all onload callbacks? It's easy!
*/
navigation.setData({
    scrollToTop: true
});
//or
navigation.setDataItem('scrollToTop', true);

/**
* Now load a page and use it!
*/
navigation.load('/my-url', {}, function(el, data){
    if( data.scrollToTop ){
        window.scrollTo(0,0);
    }
});

/**
* You can override global data per-request when you provide it to the .load() method
*/
navigation.load('/my-url', {
    scrollToTop: false
}, function(el, data){
    if( data.scrollToTop ){
        //won't be called
        window.scrollTo(0,0);
    }
});

To use:

import {XHRForm} from '@htmlguyllc/jpack/es/forms'; 

//shown with defaults
var remote_form = new XHRForm('form[name="my_form"]', {
        xhrSubmit: true, //wouldn't make a whole lotta sent to use this if this were false lol, but it's here for extending classes and incase you want to toggle it for whatever reason
        submitURL:null, //when null, the form's action will be used (if explicitly defined), otherwise it falls back to the URL the form was retrieved from
        submitMethod:null, //when null, the form's method will be used (if explicitly defined), otherwise it falls back to POST
        onPreSubmit: function(form, form_values, url, method){ //called right before the request to the server
            //return false; //you can return false to stop submission
            return {form_values:form_values, url:url, method:method}; //you can return these if you want to override them (optional)
        },
        onError: function(error, response, form){ alert(error); }, //although you can add more, you can only pass 1 to start with in the constructor
        onSuccess: function(response, form){ //although you can add more, you can only pass 1 to start with in the constructor 
            if(typeof response.success === "string"){ alert(response.success); }
            else{ alert("Your submission has been received"); }
        },
        //validate the form, display any errors and return false to block submission
        validateForm: function(form){
            //add .was-validated for bootstrap to show errors
            form.classList.add('was-validated');
    
            //if there are any :invalid elements, the form is not valid
            const is_valid = !form.querySelector(':invalid');
    
            //if it's valid, clear the validation indicators
            if( is_valid ) form.classList.remove('was-validated');
    
            return is_valid;
        }
});

//attach the submission handler
remote_form.attachSubmitHandler();

Grabs a form from a URL and places it on the current page (examples/FormModalFromURL shows how to put the form in a modal) and then uses an XHR request to submit the form

There are several methods and properties inherited from XHRForm that are not listed here. See XHRForm above for those details

To use:

import {FormFromURL} from '@htmlguyllc/jpack/es/forms'; 

//shown with defaults
var remote_form = new FormFromURL('/my-form', {
        incomingElementSelector: null, //when null, it assumes the entire response is the form's HTML
        insertIntoElement: null, //error on null, must provide this
        onload: function(form){ return this; }, //although you can add more, you can only pass 1 to start with in the constructor
        xhrSubmit: true, 
        submitURL:null, //when null, the form's action will be used (if explicitly defined), otherwise it falls back to the URL the form was retrieved from
        submitMethod:null, //when null, the form's method will be used (if explicitly defined), otherwise it falls back to POST        
        onPreSubmit: function(form, form_values, url, method){ //called right before the request to the server
            //return false; //you can return false to stop submission
            return {form_values:form_values, url:url, method:method}; //you can return these if you want to override them (optional)
        },
        onError: function(error, response, form){ alert(error); }, //although you can add more, you can only pass 1 to start with in the constructor
        onSuccess: function(response, form){ //although you can add more, you can only pass 1 to start with in the constructor 
            if(typeof response.success === "string"){ alert(response.success); }
            else{ alert("Your submission has been received"); }
        }, 
        //validate the form, display any errors and return false to block submission
        validateForm: function(form){
            //add .was-validated for bootstrap to show errors
            form.classList.add('was-validated');
    
            //if there are any :invalid elements, the form is not valid
            const is_valid = !form.querySelector(':invalid');
    
            //if it's valid, clear the validation indicators
            if( is_valid ) form.classList.remove('was-validated');
    
            return is_valid;
        }
});

//grab the form and insert in into the "insertIntoElement"
remote_form.getForm();

Your javascript

import {FormFromURL} from '@htmlguyllc/jpack/es/forms'; 
new FormFromURL('/email-form', {
    insertIntoElement: '.form-container',
}).getForm();

Your HTML

<div class="form-container"></div>

Server response when retrieving /email-form (or, just the HTML without the JSON wrapper)

{
 "html": "<form><input name='email' required='required'><input type='submit' value='Submit'></form>"
}

Server response when submitting to /email-form (success)

{ "success": "Thank you for submitting, your email has been provided to spammers everywhere" }

Server response when submitting to /email-form (error)

{ "error": "Your email is required/Your email is invalid" }

Extending:

FormFromURL extends XHRForm and either can be extended as you need.

See examples/FormModalFromURL for an example

To use:

import {request} from '@htmlguyllc/jpack/es/request'; 

//get product_id from the querystring
var product_id = request.query.get('product_id');

var current_full_url = request.getFullURL();

var full_blog_url = request.appendSlash(request.getDomainWithProtocol())+'blog'; //https://my-domain.com/blog

Instantiation with current site data:

The easy way:

Create an object named $site with values from your server (prior to including jpack)

<?php
    $user = []; //get user from database/API
?>
<script>
const $user = {
    id: <?php echo $user['id']; ?>,
    fname: "<?php echo $user['fname']; ?>",
    //..
    permissions: JSON.parse("<?php echo json_encode($user['permissions']); ?>"),
    additionalData: JSON.parse("<?php echo json_encode([
        'user_type'=>$user['user_type'],
        //whatever else you might want to pass
    ]); ?>"),
    //..
};
</script>

Then instantiate the Site class in your JS file somewhere

const cur_site = new Site($site);
cur_site.getId();

@see: /examples/CurrentSiteSingleton for a method of instantiating the current site once and using everywhere Note: Even though that creates a singleton which is available anywhere, it's still highly recommended that you pass that object to functions and methods where it is used (dependency injection)

The harder way:

Perform an XHR request to grab site details via a JSON API, then run the populate method on the site object.

import {Site} from '@htmlguyllc/jpack/es/site';
 
//this example uses jQuery's shorthand AJAX call, you can use axios or any request you want
$.get('/my-site-info-endpoint.php', function(data){
    //don't forget error handling!
    const cur_site = new Site(JSON.parse(data));
});

Of course you can use this class for any site, not just the current one, but this is the intended usage.

Instantiation with current user data:

The easy way:

Create an object named $user with values from your server

<script>
const $user = {
    id: <?php echo $user['id']; ?>,
    fname: "<?php echo $user['fname']; ?>",
    //..
    permissions: JSON.parse("<?php echo json_encode($user['permissions']); ?>"),
    additionalData: JSON.parse("<?php echo json_encode([
        'user_type'=>$user['user_type'],
        //whatever else you might want to pass
    ]); ?>"),
    //..
};
</script>

Then instantiate the User class in your JS file somewhere

const cur_user = new User($user);
cur_user.getId();

@see: /examples/CurrentUserSingleton for a method of instantiating the current user once and using everywhere Note: Even though that creates a singleton which is available anywhere, it's still highly recommended that you pass that object to functions and methods where it is used (dependency injection)

The harder way:

Perform an XHR request to grab site details via a JSON API, then run the populate method on the site object.

import {User} from '@htmlguyllc/jpack/es/user';
 
$.get('/my-user-info-endpoint.php', function(data){
    //don't forget error handling!
    const cur_user = new User(JSON.parse(data));
});

Of course you can use this class for any User not just the current one, but that's the intended usage.

To Use:

import {strings} from '@htmlguyllc/jpack/es/strings';

strings.ucfirst('bob'); //returns 'Bob'
strings.getter('name'); //returns 'getName';
strings.setter('name'); //returns 'setName';

To Use:

import {dom} from '@htmlguyllc/jpack/es/dom';

//Dont do this. Most of these are dumb examples.
dom.getElement('.my-fav-button', true, true); //will throw an error if it doesn't find it, or if it finds more than 1
dom.getElements('.links', true); //will throw an error if none are found
dom.getElement('.my-button'); //returns the button, or null (if multiple, it returns the first)
dom.getElements('.links'); //returns an array of any matches for .links
dom.getElement($('a')); //returns the native DOM element for the link and removes the jQuery wrapper
dom.getElement(document.querySelectorAll('a')); //returns the first anchor

dom.exists('a'); //returns true if there is an anchor on the page
dom.multipleExist('a'); //returns true if more than 1 anchor on the page

To Use:

import {type_checks} from '@htmlguyllc/jpack/es/type_checks';

var my_obj = {id:null, name:'John Doe', email:'john@doe.com'};

//make sure my_obj contains the keys: 'id', 'name', 'email'
//force all keys to exist
//block any keys that aren't in that list
//throw an error if the object fails any checks
type_checks.isDataObject(my_obj, ['id', 'name', 'email'], true, true, true);

To Use:

import {events} from '@htmlguyllc/jpack/es/events';

var preventedHandler = events.onClick('a.my-link', function(){
   //do something without the page redirecting to the href 
});
//now remove that handler
events.off('a.my-link', 'click', preventedHandler);

var handler = events.onSubmit('form.my-form', function(){
   //do something and submit the form using XHR 
});

//trigger submit on a form and pass an object as additional data in the event
events.trigger('.my-form', 'submit', {id:1});

Setting with a custom namespace (or no namespace):

import {events} from '@htmlguyllc/jpack/es/events';

events.setGlobal();

onClick('a', function(){
   //do something - href is prevented! 
});

To Use:

import {ToggleOnMobile} from '@htmlguyllc/jpack/es/toggle';

const toggle = new ToggleOnMobile('.toggle-sidebar-btn', '.sidebar', 'visible', true);

toggle.init();

//and later if you want to, toggle.destroy();