kameleoon-react

Activation API - React Module

Introduction

The Kameleoon React Module is a standard npm module that adds new functionality to our base Activation API. The module first needs to be installed into your React application and deployed. Once integrated, specific new methods will be added to the Activation API. These methods will allow you to modify the UI and behaviour of React based components without modifying the source code of your application. For instance, you will be able to query (select) React components and change their states and props.

This module is designed to work on websites that are using the React JavaScript framework. For websites developed without React, please use the standard Kameleoon Activation API. Our module works with React version 16 (and up). However, it won't work with minified JS code, which is usually the case in production. This is because the names (types) of the components are minified in. To use this module, please disable minification of your React application (or better, disable minification only for the components you wish to change during experiments).

## Installation

npm i kameleoon-react

The Kameleoon React Module can be installed via npm in a standard way: npm i kameleoon-react.

import KameleoonReact from 'kameleoon-react';
import React from 'react';
import ReactDOM from 'react-dom';

The module then needs to be initialized at the top of the React application.

## General Usage

The Kameleoon React module adds a new module (namespace) to the usual Kameleoon Activation API: Kameleoon.API.React. Although several methods are available within this module, the most important one is runWhenComponentPresent().

To use an API method provided by the React module, just call it in the usual way, for instance Kameleoon.API.React.runWhenComponentPresent().

## Kameleoon.API.React Reference

runWhenComponentPresent

Kameleoon.API.React.runWhenComponentPresent("MyComponentName", function(components) {
    // components contains all components that match the type and filters
}, {"className": "MyClassName", "layout": "push"});

The runWhenComponentPresent() method will execute a JavaScript function (callback) as soon as a specific React component appears in the DOM.

Arguments

Name	Type	Description
type	String	Name of the component to find. This field is mandatory.
callback	Function	JavaScript function that will be called when a component will be found. This field is mandatory.
filter	Object	Filters to obtain specific components among all components with the same type. This field is optional.
pollingInterval	Number	Polling interval, in milliseconds. The engine will periodically check if the component is present on the DOM or not. This field is optional, if not provided, the method will use the default value of 200 milliseconds.

createReactElement

Kameleoon.API.React.createReactElement("div", {
    "className": "MyCustomClassName",
    "onClick": function () {
        // do something
    }
}, "My inner text");

Kameleoon.API.React.runWhenComponentPresent("Link", function (components) {
	var title = Kameleoon.API.React.createReactElement("h3", {}, "My new title");
	var children = [title];
	components[0].setProps("children", children);
}, {});

The createReactElement() method will allow you to create React elements directly.

Arguments

Name	Type	Description
type	String	Name of the component to create ("div", "a", etc...). This field is mandatory.
props	Object	Props to add to your element. This field is optional.
children	Any	Inner content of the element. This can be a text string, an Array or an Object. This field is optional.

## Component methods

The API returns custom objects that are wrappers around the React components. You can use some standard React methods to edit and change those components, such as the ones listed below.

setState

Kameleoon.API.React.runWhenComponentPresent("MyComponentName", function(components) {
    // components contains all components that match the type and the filters
    components[0].setState("myKeyState", "myNewValue");
}, {});

The setState() method enqueues changes to the component state and tells React that this component and its children need to be re-rendered with the updated state.

Arguments

Name	Type	Description
key	String	Key (name) of the data to set. This field is mandatory.
value	Any	Value of the data. This field is mandatory.

setProps

Kameleoon.API.React.runWhenComponentPresent("MyComponentName", function(components) {
    // components contains all components that match the type and the filters
    components[0].setProps("myKeyProps", "myNewValue");
}, {});

The setProps() method enqueues changes to the component props and tells React that this component and its children need to be re-rendered with the updated props.

Arguments

Name	Type	Description
key	String	Key (name) of the data to set. This field is mandatory.
value	Any	Value of the data. This field is mandatory.