Long Story Library

Raw javaScript utility library. Useful tools for javaScript developers. This is currently in pre-release. Better documentation will come soon.

Installation

yarn

$ yarn add long-story-library

npm

$ npm install long-story-library

The UMD build is also available on unpkg:

<script src="https://unpkg.com/long-story-library/umd/long-story-library.min.js"></script>

If you use the UMD build you can find the library on window._$.

Constructor

_$(arg)

Properties

arg

Argument to initialize certain methods

bool

coerce to boolean and return value. returns true ONLY for "true", true, and "yes". _$(this.arg).bool

slash

returns string with slash appended to the end. _$(this.arg).slash

element

creates new element. _$(this.arg).elememt

Methods

vw(ref)

description

If ref is not supplied, calculates the pixel equivalent of the viewport width. If ref is supplied, treats ref as the viewport. Useful for using viewport units in js code. Returns a Number.

example

// for window viewport
someImage.style.width = _$(50).vw()
// for container element as viewport
someImage.style.width = _$(50).vw(_$("container").id())

arguments

• ref
  type: HTMLElement

vh(ref)

description
Same as vw for viewport height.

vmax(ref)

description
Same as vw and vh, but determines which is greater and uses the greater option.

vmin(ref)

description
Same as vw and vh, but determines which is smaller and uses the smaller option.

addListener(els, evt, cb, iterate, options, useCapture)

description

Provides granular control over event listeners. Tests browser for support of an options object and passive support, and uses them by default.

Accepts an array, or array-like object (e.g. - NodeList) or a single element as the first argument and applies the listener(s) to each.

Accepts an array of strings or a single string as the second argument (e.g. - ["scroll", "resize", "load"]), and executes the callback on each event.

arguments

• els
  required
  type: string, array or _$.arrayLike
  description: target element or elements.

• evt
  required
  type: string or array
  description: event.type

• cb
  required
  type: function
  description: The object which receives a notification (an object that implements the Event interface) when an event of the specified type occurs.

• options
  type: boolean
  default: { passive: true, capture: true, once: true }
  description: An object with the following options:

• capture: A Boolean indicating that events of this type will be dispatched to the registered listener before being dispatched to any EventTarget beneath it in the DOM tree.

• once: A Boolean indicating that the listener should be invoked at most once after being added. If true, the listener would be automatically removed when invoked.

• passive: A Boolean which, if true, indicates that the function specified by listener will never call preventDefault().

read more on mdn

• useCapture
  type: boolean
  default: true
  description: A Boolean indicating whether events of this type will be dispatched to the registered listener before being dispatched to any EventTarget beneath it in the DOM tree.

OBJ(nestedObj, pathArr, defaultValue)

description

A more elegant solution to returning calues from nested objects with possible properties. nestedObj may be supplied as this.arg, as in _$(nestedObj).OBJ(pathArr, def). supply an array of the optional properties down the chain, and optionally a default value.

i.e. - instead of doing this:

var mediumImage =  img
                  && img._embedded
                  && img._embedded["wp:featuredmedia"]
                  && img._embedded["wp:featuredmedia"][0]
                  && img._embedded["wp:featuredmedia"][0].media_details
                  && img._embedded["wp:featuredmedia"][0].media_details.sizes
                  && img._embedded["wp:featuredmedia"][0].media_details.sizes.medium_large
                  && img._embedded["wp:featuredmedia"][0].media_details.sizes.medium_large.source_url

do this:

var mediumImage = _$(img).OBJ([
  "img",
  "_embedded",
  "wp:featuredmedia",
  0,
  "media_details",
  "sizes",
  "medium_large",
  "source_url"
], placeHolderImg)

arguments

• nestedObj
  type: object
  description: the parent object

• pathArr
  type: array
  description: array of string representing the properties down the chain.

• defaultValue
  type: any
  default: undefined
  description: Default value when nestedObj property/sub-property is undefined.

example

var obj = {
    lvl1: { isFalse: false, isUndefined: void 0 }
}
console.log(
  _$(obj).OBJ(["lvl1", "isFalse"], 1),
  _$(obj).OBJ(["lvl1", "isUndefined"], 1),
  _$(obj).OBJ(["lvl1", "notDeclared"], 1)
)
// output: false 1 1

glideTo(latitude, speed)

description

Scrolls to a specified document latitude (scrollY) at the specified speed.

arguments

• latitude
  type: number
  default: 0

• scrollDuration
  type: number
  default: 0.5

arrayLike(obj)

description

Determines if obj is similar to an array (like NodeList). Returns a Boolean.

arguments

• obj: The Object to test.

id(selector, parent)

description

Shorthand for <parent>.getElementById(selector). selector may be supplied as this.arg, as in _$(selector).id(parent). parent defaults to document if not supplied.

arguments

• selector: the element id.
• parent: A parent element. defaults to document

cl(selector, parent)

description

Shorthand for <parent>.getElementsByClassName(selector). selector may be supplied as this.arg, as in _$(selector).cl(parent). parent defaults to document if not supplied.

arguments

• selector: the element className.
• parent: A parent element. defaults to document

tags(selector, parent)

description

Shorthand for <parent>.getElementsByTagName(selector). selector may be supplied as this.arg, as in _$(selector).tags(parent). parent defaults to document if not supplied.

arguments

• selector: the element tagName.
• parent: A parent element. defaults to document

qs(selector, parent)

description

Shorthand for <parent>.querySelector(selector). selector may be supplied as this.arg, as in _$(selector).qs(parent). parent defaults to document if not supplied.

arguments

• selector: the element selector.
• parent: A parent element. defaults to document

qsa(selector, parent)

description

Shorthand for <parent>.querySelectorAll(selector). selector may be supplied as this.arg, as in _$(selector).qsa(parent). parent defaults to document if not supplied.

arguments

• selector: the element selector.
• parent: A parent element. defaults to document

el(tagname)

description

Creates a new element. Shorthand for document.createElement(tagname). Alternative syntax would be to use the element property, as in _$(tagname).element.

arguments

• tagname: Element tagName, e.g. - (new _$()).el("span") or _$().el("span").

toggleActive(el)

description

toggles "active" on an elements className. Does not remove existing classnames.

arguments

• el: Target element.

frag(els, _parent)

description

Creates a DocumentFragment, and accepts as the first argument an array of objects that describe elements to append to the fragment. Properties for these objects are as follows:

• type (this is required and represents the HTMLElement tagName. e.g. - "span")
• className
• id
• style (rather than a string, this is an object with javaScript properties for HTMLElement attributes - e.g. { width: "100%", zIndex: 999 })
• href
• onclick (function supplied here will use _$().addlistener to attach it to the target element)
• text
• children (this is an array objects to append to the current element. The same rules apply to this array as with the top-level array supplied as the first argument.)

The array and it's children up the Virtual DOM tree will append themselves to their parent elements until they have reached the top level DocumentFragment, at which point the DocumentFragment is complete and may be attached to the actual DOM structure.

arguments

• els: array containing objects describing elements in Virtual DOM
• _parent: interal. Used within the frag function to recursively append children to parent elements in the Virtual DOM

example

(function(_$){
  var frag = _$.frag([
    {
      type: "div",
      id: "__popUp",
      style: {
        backgroundColor: "rgba(130, 130, 130, 0.5)",
        position: "fixed",
        width: "100vw",
        height: "100vh",
        left: 0,
        right: 0,
        top: 0,
        bottom: 0,
        zIndex: 5555
      },
      children: [
        {
          type: "div",
          className: "popUp",
          style: boxStyle,
          children: [
            type: "span",
            className: "btn",
            text: confirmText,
            style: closeBtnStyle,
            onclick: function() {
              return _$.remove(_$.id("__popUp"));
            }
          ]
        }
      ]
    }
  ]);
  document.body.appendChild(frag);
})(new _$)

remove(el)

description

Shorthand to remove an element from DOM.

arguments

• el: element to remove

before(el, newEl)

description

insert newEl before el on the DOM.

arguments

• el: existing element.
• newEl new element to insert

kids(el, findParentBy)

description

Find all of a specified element's children.

arguments

• el: selector to be supplied as argument for _$().<method>(selector) (one of: id, cl, tags, qs, qsa) specified in findParentBy.
• findParentBy: Method by which to find the parent of the children targeted. if this method returns a NodeList, only the first element in the list will be used as the parentElement.

vpu(num, type)

description

Emulates viewport units in JavaScript. Returns a Number which represents the viewport unit value converted to pixels. num may be supplied as this.arg, as in _$(num).vpu(type)

arguments

• num: number of the type of viewport unit.
• type: the type of viewport unit ("vw", "vh", "vmax", "vmin"). these are detailed in the individual methods above.

changeOnScroll(breakpoint, target, cbTrue, cbFalse, windowObj)

description

Passively listens to the "scroll" event on the windowObj, and executes cbTrue on the target while scrollY is past the breakpoint, and executes cbFalse if scrollY crosses back below the breakpoint. Use case would be changing the size, color, position, etc. of the header on "scroll".

arguments

• breakpoint
  type: number
  description: number that represents the scrollY at which the callbacks are executed.

• target
  type: HTMLElement
  description: The target on which to execute the callbacks.

• cbTrue
  type: function
  description: Callback for when scrollY passes the breakpoint.

• cbFalse
  type: function
  description: Callback for when scrollY passes back from beyond the breakpoint to below.

• windowObj
  type: window, HTMLElement, array, or array-like object (e.g. NodeList) of HTMLElements.
  description: The primary scrolling container. This is almost always Window, but some frameworks use different container elements as their primary scrolling object, and still others use multiple, or different containers for different states.

example

(function(_$) {
  _$.changeOnScroll(
    // breakpoint
    _$.vpu(50, "vmin"),
    // target
    _$.qs(".Header"),
    // cbTrue
    function(header) {
      return _$.toggleActive("solid");
    },
    // cbFalse
    function(header) {
      return _$.toggleActive("solid");
    },
    // windowObj
    [ window, _$.id("s4-workspace") ]
  )
})(new _$)

popUp(children, confirmText, btnClick, boxStyle, closeBtnStyle)

description

Internally uses _$.frag to create a simple popup.

arguments

• children: This argument is passed to _$.frag. see above for details.

• confirmText: text to appear on the button in the popup

• btnClick: callback to execute on the "click" event on the button

• boxStyle: style object for the popUp container, e.g. { width: "90%", zIndex: 999, color: "#fff" }.

• closeBtnStyle: style object for the button to close the popUp.

_count(arr, value)

description

Internal.

Count the number of times value occurs in arr.

arguments

• arr: array to iterate.

• value: the value to count.

_relativeUrl(url)

description

Internal.

Given a URL, will return the path from the root as String arguments

• url: url string to convert

_extractBase(url)

description

Internal.

Given a URL, returns the origin. Useful when browsers don't support window.location.origin

arguments

• url

_absoluteUrl(url, file)

description

Internal.

arguments

• url
• file

_rewriteDotPath(url)

description

Internal.

arguments\

• url

_leadAndTrailSlash(path)

description

Internal.

arguments

• path

frame(path, file, ext, rootnode)

description

Used in conjunction with frameLink and initFrame below, initializes a small framework for rendering html/txt documents that are held in a common directory. These methods may expand and become a separate, more focused library, but will still be available from this library in that event.

There is an example below all three demonstrating how they all tie together

arguments

• path
  type: string
  description: Path to directory. Can accept a full URL if the origin differs

• file
  type: string
  description: Name of the file without the extension.

initFrame(path)

description

Initializes frame with the default file (if supplied), and adds appropriate event listeners for state changes.

arguments

• path: Path to directory where text documents are stored. Supplied to frame method.

frameLink(path, name, def)

description

Used to create a globally namespaced method that "links" from one document to another. This method could probably be used for that purpose itself, but it's semantically easier for the use (as you'll see below) to create something more intuitive (ex - Link(name)) that is available on the global (window) object.

arguments

• path: Path to directory where text documents are stored. Supplied to frame method.

• name: Name of the file to request (without the extension).

• def: The default file to fall back on in the event of a failed request.

frame example

This is designed to be set into an existing webpage. So the assumption is that there will be html around frame that will not change from request to request. Part of that html is assumed to be a menu of sorts wherein each menu item has an id that corresponds to the name of the file that will be requested when it is clicked. The other important part of that html is the rootnode. This is the Node into which the response from the network request to the file will populate. As of now, it must be an element with the id "root" (e.g. - _$("root").id()). It should also be empty as anything inside rootnode before the network request will be permanently replaced upon initialization.

// /samplingplan.js
(function(_$) {
  // set up arguments
  var path = "/lab/samplingplan/Documents/";
  var hash = _$.OBJ(location, ["hash"]);
  var file = hash ? hash.slice(1) : "Malt";

  // menu items that correspond to our text files
  var menuItems = [
    "Mill",
    "HeatEX",
    "ADD-Water",
    "Ferment",
    "ADD-O2-Yeast",
    "Whirl",
    "ADD-Hops",
    "REMOVE-Trub",
    "Bottle-CanorKeg",
    "Lauter",
    "Clarify",
    "REMOVE-Grain",
    "Condition",
    "Kettle",
    "Brite",
    "Mash",
    "ADD-CO2",
    "Malt"
  ];
  // globally available method for "linking" our files
  // this can be used within the files to link to other files
  // used as <div onclick="Link('Ferment')">Ferment</div>
  window.Link = function(name) {
    _$.frameLink(path, name, "Malt");
  };
  // this example comes from a particularly unique case
  // where there were multiples of some menuItems
  // something to do with wanting to have a layout that
  // reflects a specific process in which certain steps
  // are repeated. so I had to get a little creative with
  // adding the event listeners
  menuItems.forEach(function(btn) {

    if (_$.qsa("#" + btn).length > 1) {
      // if more than one, add to each
      // addListener method handles NodeList
      _$.addListener(
        _$.qsa("#" + btn),
        "click",
        function(e) {
          Link(e.target.id);
        },
        { once: false, passive: false }
      );
    }

    if (_$.qsa("#" + btn).length === 1) {
      // else just apply to the one and use id method
      _$.addListener(
        _$.id(btn),
        "click",
        function(e) {
          Link(e.target.id);
        },
        { once: false, passive: false }
      );
    }
  });

  // finally, attach frame initialization to DOMContentLoaded
  _$.addListener(document, "DOMContentLoaded", _$.initFrame(path));

})(new $$());

<!-- index.html -->

<div class="menu" style="width: 200px; float: left">

  <div id="Mill">Mill</div>
  <div id="HeatEX">HeatEX</div>
  <div id="ADD-Water">ADD-Water</div>
  <div id="Ferment">Ferment</div>
  <div id="ADD-O2-Yeast">ADD-O2-Yeast</div>
  <div id="Whirl">Whirl</div>
  <div id="ADD-Hops">ADD-Hops</div>
  <div id="REMOVE-Trub">REMOVE-Trub</div>
  <div id="Bottle-CanorKeg">Bottle-CanorKeg</div>
  <div id="Lauter">Lauter</div>
  <div id="Clarify">Clarify</div>
  <div id="REMOVE-Grain">REMOVE-Grain</div>
  <div id="Condition">Condition</div>
  <div id="Kettle">Kettle</div>
  <div id="Brite">Brite</div>
  <div id="Mash">Mash</div>
  <div id="ADD-CO2">ADD-CO2</div>
  <div id="Malt">Malt</div>
</div>
<div id="root"></div>
<script type="text/javascript" src="/samplingplan.js"></script>

getXML(url, cb)

description

Written alongside parseXML, but really isn't specific to XML. Pretty much just a wrapper around an XMLHttpRequest, but greatly simplified, and cuts out the boilerplate request code. only makes GET requests. provides a callback for the reponse. url may be supplied as this.arg as in _$(url).getXML(cb)

arguments

• url: request url.
• cb: function to execute on the response returned from the request.

parseXML(text, cb)

description

Parses XML (and html) string into a DOM, providing native browser functions for traversing the DOM tree. provides a callback to be executed on the resulting DOM. test may be supplied as this.arg as in _$(url).parseXML(cb)

arguments

• text: string to parse.
• cb: callback to execute on DOM

example for XML methods above

this incorporates react-gallery-designer's somewhat unique umd build, which wraps a React component in a custom function making it quite portable

(function(_$) {
  // get rss XML
  _$.getXML(
    "https://twitrss.me/twitter_user_to_rss/?user=plantdisease",
    function(rss) {
      // parse it
      _$.parseXML(rss, function(doc) {
        // construct our feed segments
        var images = Array.from($$.tags("item", doc), function(item, i) {
          return {
            caption: _$.qs("title", item).innerHTML.slice(0, 100) + " ...",
            link: _$.qs("link", item).innerHTML,
            style: {
              // gives every other item a grey background
              backgroundColor: Math.ceil(i % 2) ? "#dcdbdb" : "#fff"
            },
            target: true
          };
        });

        var settings = {
          inview: 2,
          auto: true,
          playpause: false,
          pauseonhover: false,
          direction: "left",
          animation: "slide",
          orientation: "vertical",
          speed: 5000,
          transitionspeed: 1,
          arrows: false,
          advance: 1,
          showcaptions: true,
          linkslides: true,
          thumbnails: false,
          contain: false,
          noImages: true
        };
        // return custom rotating feed
        return __RGD({
          images: images,
          settings: settings,
          captionStyle: { color: "#595956", fontWeight: "bold", lineHeight: 2, fontSize: "1.05rem" },
          imgStyle: { padding: "0 1rem" },
          style: { height: "9rem" },
          domId: "twitterFeed"
        });
      });
    }
  );
})(new _$;