Front end helper methods

Apostrophe provides a small library of front-end utility methods to support implementing client-side JavaScript. These can be useful in widget players, for example. General utility methods area available on apos.util and HTTP request methods are available on apos.http.

General utility methods

These are all available in the browser on apos.util, e.g., apos.util.addClass(el, 'is-active'). They include wrappers for common browser APIs, classic DOM traversal methods, and Apostrophe-specific utilities. They are also compatible with all modern browsers as well as Internet Explorer 11.

Method	What is it?
addClass	Add a class to a DOM element, if missing.
assign	Assigns properties from one or more source objects to a target object.
attachmentUrl	Get the file URL for an Apostrophe attachment object.
closest	Returns the closest ancestor element that matches the selector.
emit	Emit a custom browser event on a DOM element.
getCookie	Get the value of a browser cookie.
onReady	Runs the function passed in when Apostrophe refreshes page content during editing.
removeClass	Remove a class from a DOM element, if present.
sameSite	Returns true if a URI argument matches the same website as the current page.

addClass(el, className)

Add a class to a DOM element, if missing. Often used with removeClass. Supports browsers without the matching native method.

Argument	What is it?
el	a DOM element
className	a string to be added to the class attribute

const myElement = document.querySelector('[data-my-element]');

apos.util.addClass(myElement, 'is-active');

assign(target, src1, src2, ...)

Assigns properties from one or more source objects to a target object. Uses Object.assign when available. Supports browsers without the matching native method.

Argument	What is it?
target	an object on which to add source object properties
src1, src2, etc.	one or more source objects whose properties should copy to the target object

const options = {
  name: 'balloon',
  color: 'blue'
};

apos.util.assign(options, {
  color: 'red',
  language: 'French'
});

console.log(options)
// {
//   name: 'balloon',
//   color: 'red',
//   language: 'French'
// }

attachmentUrl(fileObj, options)

Get the file URL for an Apostrophe attachment object. Optionally pass an options object to get a specific version of the file. File (non-image) attachment objects include a single _url property already, so this is primarily used for retrieving specific versions of an image.

Argument	What is it?
fileObj	an attachment object, such as from an attachment field value or using a template helper method to parse an image widget value
options	image options to apply for the resulting URL

Options	What is it?
size	an image size name to retrieve, such as one of the standard image file variations

// Getting an image attachment object after stashing the stringified object
// on a `data-image` attribute in the template
const imageObj = document.querySelector('[data-thumbnail]').dataset.image;

const smallImage = apos.util.attachmentUrl(imageObj, {
  size: 'one-third'
});

closest(el, selector)

Returns the closest ancestor element that matches the selector. The element itself is considered the closest possible match. Supports browsers without the matching native method.

Argument	What is it?
el	a DOM element
selector	a string to use as a CSS selector to match

const menuToggle = document.querySelector('[data-toggle]');

const menu = apos.util.closest(myElement, '[data-menu]');

emit(el, name, data)

Emit a custom browser event on a DOM element. Optionally include a data object to include on the event. For event listeners, use the standard browser addEventListener method.

Argument	What is it?
el	a DOM element
name	a string to use as the event name
data	(optional) an object containing data to include on the event object

const myElement = document.querySelector('[data-my-element]');

apos.util.emit(myElement, 'openChat', {
  url: window.location
});

getCookie(name)

Get the value of a browser cookie.

Argument	What is it?
name	The name of a browser cookie

apos.util.getCookie('cookiename');

onReady(fn)

Runs the function passed in when the page loads as well as when Apostrophe refreshes page content during editing. When logged out it will run the function on initial page load. This is not necessary in widget players.

INFO

This method was previously named onReadyAndRefresh. The name was changed, though the previous name will still work through the 3.x major version.

Argument	What is it?
fn	a function that should run when page content is ready

const loadNewsletterForm = function () {
  // Code that loads a sign-up form...
}

apos.util.onReady(loadNewsletterForm);

removeClass(el, className)

Remove a class from a DOM element, if present. Often used with addClass. Supports browsers without the matching native method.

Argument	What is it?
el	a DOM element
className	a string to be added to the class attribute

const myElement = document.querySelector('[data-my-element]');

apos.util.removeClass(myElement, 'is-hidden');

sameSite(uri)

Returns true if the URI pass in matches the same website (same host and port) as the current page. This is used in some HTTP utility methods.

Argument	What is it?
uri	a valid URI

const targetUrl = 'https://some-website.rocks/api/gems'
const siteMatches = apos.util.sameSite(targetUrl);

INFO

There is also a runPlayers method on apos.util. That is run for us using apos.util.onReady and runs all registered widget players. It is unlikely that it will need to be run in project-level code.

HTTP request methods

These are all available in the browser on apos.http, e.g., apos.http.get('/api/v1/article'). They include utility methods to make requests with each HTTP method (GET, POST, PATCH, PUT, and DELETE) as well as other helpers for making HTTP requests.

Method	What is it?
get	Send a GET request.
post	Send a POST request.
patch	Send a PATCH request.
put	Send a PUT request.
delete	Send a DELETE request.
remote	The HTTP request method that powers other request methods.
parseQuery	Parses a URL query string, returning an object of parameters.
addQueryToUrl	Returns a URL with data object properties added as a query string.

get(url, options, callback)

Send a GET request. The response will be returned via a Promise unless a callback is included. Query string data may be in options.qs. You do NOT have to pass a callback unless you must support IE11 and do not otherwise have Promise support.

Argument	What is it?
url	The path to a resource or service
options	Request options. See apos.http.remote for details. Required.
callback	An optional callback function, required when not using Promises. Receives error and result arguments.

async function logArticles() {
  let articles;

  try {
    articles = await apos.http.get('/api/v1/article', {});
    console.info(articles);
  } catch (err) {
    console.error(err);
  }
}

logArticles();

post(url, options, callback)

Send a POST request. The response will be returned via a Promise unless a callback is included. options.body should be an object containing properties to be passed as POST body data. You do NOT have to pass a callback unless you must support IE11 and do not otherwise have Promise support.

See the get method for argument details and a related example.

patch(url, options, callback)

Send a PATCH request. The response will be returned via a Promise unless a callback is included. PATCH body data should be in options.body. You do NOT have to pass a callback unless you must support IE11 and do not otherwise have Promise support.

See the get method for argument details and a related example.

put(url, options, callback)

Send a PUT request. The response will be returned via a Promise unless a callback is included. PUT body data should be in options.body. You do NOT have to pass a callback unless you must support IE11 and do not otherwise have Promise support.

See the get method for argument details and a related example.

delete(url, options, callback)

Send a DELETE request. The response will be returned via a Promise unless a callback is included. You do NOT have to pass a callback unless you must support IE11 and do not otherwise have Promise support.

See the get method for argument details and a related example.

remote(method, url, options, callback)

Send an HTTP request with a specific method to the given URL, returning the response body. The response will be returned via a Promise unless a callback is included. You do NOT have to pass a callback unless you must support IE11 and do not otherwise have Promise support.

INFO

This method is used to power the individual HTTP request methods. We recommend using those instead. They will produce the same result as using remote and including the proper HTTP method name.

Argument	What is it?
method	An HTTP method name: GET, POST, PUT, PATCH, or DELETE
url	The path to a resource or service
options	Request options. See below.
callback	An optional callback function receiving when not using Promises. Receives error and result arguments.

Options	What is it?
qs	An object of query string parameters set to values.
body	The request body. If an object or array it is sent as JSON. Otherwise sent as-is, unless the send option is set to 'json'.
send	Set to 'json' to always send the request body as JSON, even if a FormData object or non-object. This is not necessary when the body is a normal object.
parse	Set to 'json' to always parse the response as JSON. Otherwise the response body is parsed as JSON only if the Content-Type is application/json.
headers	An object containing HTTP header names and values.
draft	If true, always add aposMode=draft to the query string, creating one if needed.
csrf	Set to false to prevent sending the X-XSRF-TOKEN header when talking to the same site.
fullResponse	If true, return an object with status, headers and body properties, rather than returning the body directly. The individual headers are canonicalized to lowercase names. If there are duplicate headers after canonicalizing only the last value is returned. If a header appears multiple times an array is returned for it.
downloadProgress	Optional. A function accepting received and total arguments. It may never be called. If called, received will be the bytes sent so far and total will be the total bytes to be received. If the total is unknown, it will be null
uploadProgress	Optional. A function accepting sent and total arguments. It may never be called. If it is called, sent will be the bytes sent so far and total will be the total bytes to be sent. If the total is unknown, it will be null.

If the status code is greater than 400 an error is thrown. The error object will be similar to a fullResponse object, with a status property.

If the URL is site-relative (starts with /) it will be requested from the Apostrophe site itself.

TIP

Just before the XMLHttpRequest is sent, this method emits an event matching the HTTP method. For example, apos-before-post for POST requests, apos-before-get for GET requests, etc. The event object has uri, data and request properties. request is the XMLHttpRequest object.

You can use this to set custom headers on all requests, for example.

parseQuery(query)

Returns a data object from parsing a URL query string (e.g., ?theme=light&aposRefresh=1). The argument should only include the query string part of a URL. The leading question mark (?) is allowed but not required. A parameter with no value will be set to null.

Argument	What is it?
query	A url query string

const simpleParams = apos.http.parseQuery('?refresh=true&number=7');
const nestedParams = apos.http.parseQuery('?product%5Bprice%5D=50&product%5Bname%5D=Cheese')

INFO

apos.http.parseQuery() supports query parameter objects and arrays (when escaped), as well as bracket nesting.

addQueryToUrl(url, data)

Returns a URL with data object properties added as a query string. This supports data object values as objects and arrays. If data is an empty object no query string is added. If the URL already includes a query string it is discarded and replaced.

Argument	What is it?
url	A url
data	An object with data to convert to a query string

const updatedUrl = apos.http.addQueryToUrl(location.href, {
  theme: 'dark',
  'search-complete': 1
});