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.

addClass(el, className) ​

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

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.

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.

// 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.

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.

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

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

getCookie(name) ​

Get the value 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.

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.

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.

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

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.

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.

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.

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.

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.

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

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.

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