Long-story-library NPM

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().

`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 _$;

javascript utilities raw small

@infinitebrahmanuniverse/nolb-lon @everything-registry/sub-chunk-2100

6 years ago

6 years ago

6 years ago

6 years ago

6 years ago