@thesymphonyagency/symphonyjs
v1.1.5
Published
Collection of Symphony Agency helper functions
Downloads
1
Keywords
Readme
#[name] [name] is a JavaScript library that enables developers to run, rerun, and undo functions across window breakpoints.
##Installation Add to project using NPM
npm install [packagename]
Import into project
import SymJs from '@thesymphonyagency/symphonyjs'
Basic usage
[name] comes with some built in actions, but the basic usage is as follows:
//for each use case, register actions before ready is called
const actionSettings = {
windowEvents: ['ready', 'load','resize'],
breakpoints:['xs', 'sm', 'md', 'lg'],
dependency: 'body.home-page',
target: '.custom-class' //example action specific property
}
symJs.actionName(actionSettings)
/**
* In this case, the action will be run on ready, load and every resize event.
* The action will also be running on every breakpoint.
* The action will only run if body.home-page is found.
* The action receives the custom property "target"
*/
action settings
Enqueued action settings control how and when action functions are run.
windowEvents
Controls which events the action function will run on.
Accepts an array of the following options:
- 'ready'
- 'load'
- 'resize'
breakpoints
When the resize is included in windowEvents, this setting controls which breakpoints the action will run on. Some actions may include undo functionality which will remove their effects on non-activated breakpoints.
Accepts an array of the following options:
- 'xs'
- 'sm'
- 'md'
- 'lg'
dependency
This setting is determines whether or not the action is enqueued based on whether or not the query returns any elements.
Accepts a string that can be passed to querySelectorAll
onlyOnBreakpointChanged
Enqueuing on resize will trigger a action to run a lot. This setting will only allow the action to run when a breakpoint has changed.
runOnce
Some actions may need to be run only once, yet still have a reset function for
inactive breakpoints. Setting this to true
will run the action only one time
upon entering an active breakpoint. If the reset function is called, then it
will reactivate after reentering the active breakpoint range.
Extending
TODO: Rewrite everything below that doesn't fit new model.
- Creates a new js file in
src/extensions
. - Write your function as a key/value pair, or as a named function.
module.exports =
your object or function.
Option 1: Named function
The class generator will use the function's name as the prototype name
//src/extensions/yourFile.js
module.exports = function myNewFunction(){
//your code here
}
//client code
const symphony = new SymphonyJs()
symphony.myNewFunction()
Option 2: Object
The class generator will add all keys that are functions to the class prototypes.
//src/extensions/yourFile.js
module.exports = {
myNewFunction: function(){
//your code here
}
}
//Or a little cleaner, and with another function
module.exports = {
myNewFunction(){
//your code here
},
myNewFunction2(){
//more code
}
}
//client code
const symphony = new SymphonyJs()
symphony.myNewFunction()
symphony.myNewFunction2()
##Run functions on jQuery events (ready, load, resize)
In order to enqueue actions to run on events your function will need to make use
of some of the class methods - at the very least: this.addToQueues()
. Every
action that can be enqueued or triggered must submit a common structure to
this.addToQueues()
as either an object, for a single event, or array of objects.
object template:
let action = {
func: yourFunction,
options: {
windowEvents: ['ready', 'resize', 'load'],
breakpoints: ['xs', 'sm', 'md', 'lg'],
onlyOnBreakpointChange: true
}
}
func
: can be an anonymous function, or a reference to one. This will be run by the queuing serviceoptions
: The options object can contain triggers (found below), and custom values. The entire object will be passed intofunc
when the queuing service runs it, so feel free to add custom stuff. Note: class level variables can be passed into the initializing options of SymphonyJs, asthis.options
will be available to custom extension functions.windowEvents
: accepts String or Array of Strings. Defaults to 'ready'.breakpoints
: accepts String or Array of Strings. Defaults to all breakpoints.onlyOnBreakpointChange
: Boolean only runs initially, and when breakpoint changes.
##Utility functions SymphonyJs exposes several utility functions to be used in custom functions.
processArrayOrType
: Params('type', input, callback)
This function allows you to run a function once, or many times based on whether the
input is a single item, or an array of them.
*type
: is the typeof
of whatever parameter you're checking for.
*input
: is the variable or array
*callback
: is the function that will be run based on the number of inputs.
Usage:
module.exports = function sayThings(things){
this.processArrayOrType('string', things, (thing)=>{
console.log(`Saying: ${thing}`)
})
}
SymphoniJs.sayThings('Hello!') //output: Saying: Hello!
SymphoniJs.sayTHings(['yes', 'maybe', 'no'])
/** output:
* Saying: yes
* Saying: maybe
* Saying: no
*/
domElementExists
: Params(string target || Array of string targets)
*targets
: 1 jQuery search per parameter as a string.
- returns: boolean The purpose of the is to check if dependencies on the page exist before running a function. This can be used in combination with custom action options to determine what pages the action should be run on.
usage
module.exports = function sayThings(things){
if(this.domElementExists('body.sayThingPage')){
this.processArrayOrType('string', things, (thing)=>{
console.log(`Saying: ${thing}`)
})
}
}
##Using these functions in combination Here is an example of creating a custom function extension of SymphonyJs
//src/saythings.js
module.exports = function sayThings(optionsInput){
//allow for multiple action queue registrations in a single call.
this.processArrayOrType('object', optionsInput, (options)=>{
//Only add to queue if dependencies exist as defined by custom options var dependencies
if(this.domElementExists(optionsInput.dependencies)){
//add to the queue
this.addToQueues({
func: function(options){
//allow for single or multi-input for options.things
this.processArrayOrType('string', options.things, (thing)=>{
console.log(`Saying: ${thing}`)
})
},
options: options
})
})
}
}
//client js
const symphony = SymphonyJs()
symphony.sayThings([{
things: 'Hello', //defaults to on ready. null/undefined dependenices will run.
},{
things: ['its', 'meeee'], //func determines that both are logged
dependencies: '.its-me-page', //only enqueued if .its-me-page exists
windowEvents: ['ready', 'resize'], //runs on ready, and resize
onlyOnBreakpointChange: true, //but only if resize triggers a new breakpoint
breakPoints: ['xs', 'md', 'lg'] //and only if that breakpoint is xs, md, or lg
}])
##extensions
###Custom() The custom function is a useful utility to run custom JS on breakpoints.
const symphony = SymphonyJs()
symphony.custom({
windowEvents: ['ready', 'resize'], //runs on ready, and resize
onlyOnBreakpointChange: true, //but only if resize triggers a new breakpoint
breakPoints: ['xs', 'md', 'lg']
},
function(){
//Function to be run
},
function(){
//Reset function to undo on off breakpoints.
})