Rivet API
This is a technical summary of what is offered by our Rivet API and how to create your own custom JS based elements within Cornerstone.
Rivet is our internal JS library that facilitates in building custom elements with JS. You can access this through window.csGlobal.rivet in Global or Post JS, or through a script you load externally of the Cornerstone App.
rivet.attach
rivet.attach will run code on an element based on a selector. It will run whenever Rivet has loaded and whenever another element with the same selector has been added to the page. When your selector is a data attribute, the second argument passed to your function will be the value of the data attribute for ease of use. The return of your function will be your teardown function or an array of teardown functions. When your element has been removed from the page these teardown functions are then run. This can help reduce and free memory in Cornerstone when the element is no longer on the page.
This function is useful because the Cornerstone App can dynamically add elements to the page and keeping up with changes can then be handled by Cornerstone internally. Letting you worry about functionality first.
// Simpler alias
const attach = window.csGlobal.rivet.attach;
// Attach to an element with the attribute `data-attribute-test`
attach('[data-attribute-test]', function(element, props) {
console.log('This is the element', element);
console.log('This is value of data-attribute-test', props);
// Teardown function
return function() {
console.log('This element has been removed from the page', element);
};
});
// Attach to any element that has the class `hide-on-click`
attach('.hide-on-click', function(element) {
// On click event
// Set the elements style display to 'none'
function onClick() {
element.style.display = 'none';
}
// Add event
element.addEventListener('click', onClick);
// Teardown remove the click event
// Since this element could be potentially removed this isn't necessarily needed
// However you could be adding events to the window or document.body
// and in that case you wouldn't want to keep the events attached
return function() {
element.removeEventListener('click', onClick);
};
});rivet.util
There are a number of different utils supplied by rivet. They offer helpers to make creating a new Cornerstone JS element easier. Let's go through them.
listener and listenerPassive
These are similar to add events or addEventListener. The difference is that these functions return a teardown function you can use when an element is removed from Cornerstone. It also allows for more simpler code.
In this example we attach to any element with a class name of scroll-listener and that element will listen to the window's scroll value and set the pixel value of the scroll to the elements inner text.
// Simpler alias
const attach = window.csGlobal.rivet.attach;
// Util alias
const util = window.csGlobal.rivet.util;
// Attach to any element that has the class `scroll-listener`
attach('.scroll-listener', function(element) {
// We return what listener returns because that will be a valid teardown
// of the event on the window object we are listening to
return util.listenerPassive(window, 'scroll', function(e) {
// Set the scroll value to display on this element
element.innerHTML = window.scrollY + "px";
});
});onScroll
Similar to our listener function we looked at. This exclusively handles listening to onScroll. Let's see how this can help slim down our code from before.
This event handler will throttle the scroll event and mark as a passive event. Meaning you can't prevent the page from scrolling using this. See onScrollRaw if you wish to do that.
const attach = window.csGlobal.rivet.attach;
const util = window.csGlobal.rivet.util;
// Attach to any element that has the class `scroll-listener`
attach('.scroll-listener', function(element) {
// We return what listener returns because that will be a valid teardown
// of the event on the window object we are listening to
return util.onScroll(function(e) {
// Set the scroll value to display on this element
element.innerHTML = window.scrollY + "px";
});
});onScrollRaw
This scroll handler will not mark itself as passive. In this example we will simply prevent the scroll from happening at all with preventDefault.
const attach = window.csGlobal.rivet.attach;
const util = window.csGlobal.rivet.util;
// Attach to any element that has the class `scroll-preventer`
attach('.scroll-preventer', function(element) {
// We return what listener returns because that will be a valid teardown
// of the event on the window object we are listening to
return util.onScrollRaw(function(e) {
e.preventDefault();
});
});onScrollOrResize
This event will trigger on a scroll or a onResizeOrScan event. It can be useful for resizing the element itself when it uses a 3rd party library.
onResize
This will trigger when the page is resized. It will also throttle itself and mark the event as passive, meaning it will not take up as much PC resources and work faster in general.
onResizeOrScan
This handler will watch for resize events and a rivet scan event (rvt-scan). This event is sent by elements such as the Tab element which can alter the page size depending on the content between tabs. It is useful to use this event when the page size matters for the JS you are using.
onViewportChange
Very similar to onResizeOrScan, this handler will trigger also on page load and when the browser tab has been switch and then back to the same tab your JS is on.
onLoad
This works similar to the onload event from the window object. However it will run your callback even if the window has already loaded. This will make sure you code runs even if it's being loaded in dynamically after the page has already loaded.
const util = window.csGlobal.rivet.util;
util.onLoad(function(e) {
console.log("This code has run");
});onScan
This handler will trigger when the special rvt-scan event has triggered.
onScanLazy
This is identical to onScan, however it will throttle itself to prevent using too many resources. rvt-scan can trigger a number of times in a row depending on what a user is doing in Cornerstone.
triggerScan
This function can be called to trigger the rvt-scan event so other elements know the page could have changed in size or state. If you are having a hard time getting an element like Accordions to function properly after an action in your JS, you can trigger this to tell the Accordion to resize or fix itself.
isMobile
A very simple check that will return true if the page is smaller then 979 pixels and the device has touch events.
once
This will add an event listener to a specific element and remove the event listener when the event has happened once.
In this example we will listener to see if the page has been clicked once.
const attach = window.csGlobal.rivet.attach;
const util = window.csGlobal.rivet.util;
// Attach to any element that has the class `body-has-been-clicked`
attach('.body-has-been-clicked', function(element) {
// We return what listener returns because that will be a valid teardown
// of the event on the window object we are listening to
return once(document.body, 'click', function(e) {
console.log("Body has been clicked once");
});
});oncePassive
This is identical to once, but it will mark the event as passive resulting in better performance.
doOnce
This will return a function that you can only call once, and subsequent calls will not do anything. It can be useful if you are sending a function to a large number of other elements, but you only want to the function to run once.
scrollingDisable
This function will disable scrolling on your page. It works by placing a special class on your page that will prevent scrolling and limit the page to only 100% of the viewport.
scrollingEnable
This function will enable scrolling on your page. It is only useful if you have called scrollingDisable first, as all pages automically will have scrolling.
teardown
This will take an array of teardown functions and return them as a singular teardown. It is useful if you have a number of event listeners.
const attach = window.csGlobal.rivet.attach;
const util = window.csGlobal.rivet.util;
attach('.teardown-example', function(element) {
// Teardown any number of teardowns
return util.teardown([
util.onScroll( /* ... */ ),
util.onLoad( /* ... */ ),
]);
});See Also
See something inaccurate? Let us know