[DEPRECATED] M.JS API v3

🚧

Using this feature requires knowledge of JavaScript, HTML and CSS

Misuse of the M.JS API might cause unexpected issues on your site.
If you need any support, we're here to help!

📘

Previous version of MJS

The documentation for the previous deprecated version of our MJS can be found here: https://developers.findify.io/docs/customization-mjs-api

M.JS v3 introduces the new API for manipulating behavior, that we call 'hooks'.

M.JS starts listening to the hooks inside window.findifyApiRegistry array immediately upon loading.

By using the M.JS API you can access all parts of the app lifecycle and adjust them to your needs.

👍

window.findifyApiRegistry array must be defined before M.JS script is referenced

Custom styles and scripts

Although you can add custom scripts through the Merchant Dashboard, you can also do this directly with the M.JS API

Adding Custom CSS

You can specify the custom CSS directly or include a link

window.findifyApiRegistry = [{
  style: 'body{ background: black; }'
}];

window.findifyApiRegistry = [{
  style: 'https://example.com/custom.css'
}];

Adding Custom JS

window.findifyApiRegistry = [{
  script: 'console.log(1);'
}];

window.findifyApiRegistry = [{
  script: 'https://example.com/script.js'
}];

Working with hooks

M.JS uses a powerful hook system that allows you to modify the data and the nodes directly inside different lifecycle functions. The hook is an object, that contains of the hook name and function handlers:

window.findifyApiRegistry = [{
	hook: 'search.results',
  didMount: function(data, config) {...}
}];

Hook object contains three fields:

1. hook - name of hook, is [context].[component] composition, which specifies component where hook will be injected.
2. mapProps - function which allows you to change data which will be passed to component.
3. didMount - function triggers on component view was rendered in window.
4. didUpdate - similar to previews one, but triggers every time when view was changed.

Available hooks

Generic hooks

• *.item - Generic single item hook, can be used to apply customizations across all widgets. It is fired for every rendered item
  -- search.item - is usable only for the search item
  -- autocomplete.item - is usable only for autocomplete item
  -- recommendations.item - is usable only for recommendation item
  -- collection.item - is usable only for collection item

• *.grid - Generic items hook, can be used to apply customizations to all widgets. It is fired when all items for particular widget are rendered
  -- search.grid - is usable only for search items
  -- autocomplete.grid - is usable only for autocomplete items
  -- recommendations.grid - is usable only for items in the recommendation with grid type
  -- collection.grid - is usable only for collection items

• recommendations.carousel - Items hook similar to *.grid but modifies only the recommendation with carousel type.

• *.facet - Generic facet hook, which is fired for each facet that is rendered
  -- search.facet - is usable only for search facet
  -- collection.facet - is usable only for collection facet
  -- mobile.facet - is fired only for mobile facet

• *.facets - Generic facets hook, which is fired when the facet container is rendered
  -- search.facets - is usable only for search facets
  -- collection.facets - is usable only for collection facets
  -- mobile.facets - is fired only for mobile facets

• *.results - Generic results hook, which is fired when search or collection results are completely rendered
  -- search.results - is fired when search results are rendered
  -- collection.results - is fired when collection results are rendered

Specific hooks

• search.noResults - is fired when search returned 0 results
• autocomplete.suggestions - is fired the list of autocomplete suggestions
• recommendations.carousel - is fired only for carousel type widget
• recommendations.grid - is fired only for grid type widget
• collection.fallback - is fired only for smart collection, when the collection was not set up
• location - is fired when the url in the browser is updated, which happens when user selects filters or navigates to the next page in the results

Functions available for every hook

• mapProps({ config, ...rest }) - Allows you to change properties that will be passed to the component. It contains config and other component specific properties. Do not execute slow code as it will affect component rendering

• didMount({ node: DOMNode, data: componentProps }, config) - Is called when the component is rendered (mounted). You have access to the DOM and item properties here. We recommend doing all DOM manipulation in this function

• didUpdate({ node: DOMNode, data: componentProps }) - Is called when the component is rendered. It's really similar to didMount, but if the component is re-rendered multiple times, this function will be called on each render.

• onChange({ state }) - is called when the state object is updated (e.g. a filter is selected, user goes to the next page in the search\collection results. Is only available for location hook.

Example

window.findifyApiRegistry = [{
  //the code will be applied only for search results
	hook: 'search.items',

  didMount: function(data) {
    //appending custom code for each node
    $(data.node).appendChild('<div>CUSTOM HTML</div>');
  },

  //depending on the width of the screen we can 
  //show either 3 or 4 columns of products
  mapProps: function(props) {
    var width = props.size.width;
    if (width > 1000) {
      return { columns: 4 };
    } else {
      return { columns: 3 };
    }
  }
}];