The public SDK for RIPE Core.

1. Initialization

As a starting point, you need to provide the brand and model of your customizable product. You may also pass an options map to override parameters like the base url of the server where the product is configured, as well as currency and country, which are 'EUR' and 'US' respectively by default.

var ripe = new Ripe(brand, model, {
    variant: variant,
    url: url,
    currency: currency,
    country: country
});

2. Events

After initializing the Ripe object you should subscribe to the available events so you can easily respond and update your UI.

Update

Triggered whenever there is a customization change (eg: the color of a part is changed).

ripe.bind("update", function() {
    updateUI();
});

Price

Notifies you when the price of the customization changes.

ripe.bind("price", function(value) {
    var price = document.getElementById("price");
    price.innerHTML = value.total.price_final + " " + value.total.currency;
});

Combinations

Called when the possible customization combinations of the product are loaded. Each combination is a triplet formed by part, material and color. You should use this to populate the customization options on your UI.

ripe.bind("combinations", function(value) {
    for (var index = 0; index < value.length; index++) {
        var triplet = value[index];
        var part = triplet[0];
        var material = triplet[1];
        var color = triplet[2];
        addOption(part, material, color);
    }
});

Parts

Notifies you when all the product's parts have changed.

ripe.bind("parts", function(parts) {
    parts && showPartsPicker(parts);
});

Frames

Triggered whenever there is a frame change.

configurator.bind("changed_frame", function(frame) {
    frame === "top" && disableButton("top-view-button");
});

3. Product visualization

Usually the product has 24 lateral frames, plus a top and bottom view. To display any frame of the product you can use the bindImage function to automatically update an <img> element. This method also contains an options parameter. Subscribe to the event loaded and you will know when your image is loaded. Finally, after the initial binding of the frames you should call the load function for the initial update.

var element = document.getElementById("frame-0")
var image = ripe.bindImage(element, {
    frame: "side-0"
});

image.bind("loaded", function(frame) {
    console.log("frame " + frame + " loaded")
});

ripe.load();

Whenever you want to set a new image frame, you only have to call setFrame function.

image.setFrame("side-3");

4. Product customization

You can change a part of your product by using the setPart function. Alternatively, multiple parts can be changed at once with setParts.

ripe.setPart(part, material, color);
ripe.setParts([
    [part, material, color],
    [part, material, color]
]);

Getters

If you need to explicitly retrieve the product's customization information you can use the following methods:

• getConfig: to get information about the product's model.
• getCombinations: to get all the customization options for products without any restrictions applied.
• getDefaults: to get the product's default customization.
• getFrames: to get all the product's frames.
• getPrice: to get the product's pricing information.

These functions receive a callback function as a parameter as shown below:

ripe.getPrice(function(value) {
    var price = document.getElementById("price");
    price.innerHTML = value.total.price_final + " " + value.total.currency;
});

5. Product personalization

To display a frame with initials you can use the bindImage function by setting the parameter showInitials as true on the options map. The initials are set on the Ripe object with the setInitials function which accepts initials and engraving as parameters. If your initials require a transformation to different profiles you can set a function that receives the initials and engraving parameters and transforms it into a map with initials and an array of profiles using the setInitialsBuilder function.

ripe.setInitials("SW", "metal_gold");

ripe.bindImage(document.getElementById("frame-initials"), {
    showInitials: true
});

6. Product interaction

To provide an interactive product visualization you simply need to pass a <div> element to the method bindConfigurator. Subscribe to the event loaded and you will know when your configurator is loaded.

This element supports the following methods:

Method	Params	Description
changeFrame	frame (string), named frame defined in the "view-position" format. Eg.: "side-0" options (JSON object with optional fields): duration: (number) total duration, in milliseconds, of the animation; type: (string) the animation style you want, wich can be "simple" (fade in), "cross" (crossfade) or null (without any style)*; preventDrag: (boolean) to choose if drag actions during an animated change of frames should be ignored. "True" by default	displays a new frame, with an animation from the starting frame
highlight	part (string), named part options (JSON object with optional fields)	highlights a product's part
lowlight	options (JSON object with optional fields)	removes any highlight from the product
selectPart	part (string), named part options (JSON object with optional fields)	selects a given product's part
deselectPart	part (string), named part options (JSON object with optional fields)	removes selection from a given product's part

var element = document.getElementById("config");
var configurator = ripe.bindConfigurator(element, {});

configurator.bind("loaded", function() {
    this.changeFrame("side-11", {
        duration: 500
    });
});

7. Plugins

Part synchronisation

If your product has synchronisation rules, where a set of parts must always have the same material and color, you can use the sync plugin to have this behaviour automatically. To do this you need to initialize the SyncPlugin wich receives the synchronisation rules and add it to the ripe object using the addPlugin function.

ripe.getConfig(function(result) {
    var syncRules = result.sync;
    var syncPlugin = new Ripe.plugins.SyncPlugin(syncRules);
    ripe.addPlugin(syncPlugin);
});

Appendix

Options

Name	Type	Description
backgroundColor	string	RGB format color value of the background ( no need to pass the "#" signal ). No background by default. Example: "cccccc"
country	string	Two letters standard country codes defined in ISO 3166-1 alpha-2 codes. "US" by default. Example: "PT"
currency	string	Standard currency codes defined in ISO 4217 codes. "USD" by default. Example: "EUR"
frames	array of strings	All the frames to be used in the customization. Example: ["top", "bottom", "1", "2"]
format	string	One of the valid image formats: 'jpeg', 'webp', 'sgi' or 'png'
maskDuration	number	Specifies how many milliseconds the mask animation takes to complete. 150 by default
maskOpacity	number	Specifies the opacity value of the the masks used to highlight/select parts. 0.4 by default
maxSize	number	Maximum value for frame image size. 1000px by default
noCombinations	boolean	Defines if the combinations are loaded or not. False (loading) by default
noDefaults	boolean	Defines if the defaults are loaded or not. False (loading) by default
noMasks	boolean	Used to negate the useMasks option
noPrice	boolean	Used to negate the usePrice option
parts	JSON Object	Defines the product initial parts. Each key is a part's name built with color and material information. Example: var parts = { "sole": { "material": "nappa", "color": "white" }, ... }
sensitivity	string	Defines the degree of sensitivity of the dragging interaction. 40 by default.
size	number	Initial size value of a frame image that is going to be composed. By default it's 1000px.
url	string	The base url of the server where the product is configured
variant	string	Variant of the customizable product
useChain	boolean	Determines if a chain based loading should be used for the pre-loading process of the various image resources to be loaded. False by default.
useMasks	boolean	Enables masks on selection/highlight. True by default
usePrice	boolean	Enables the fetch price feature everytime a new part is set. True by default.
useSync	boolean	Enables the part synchronisation feature. False by default.

Browser Support

Desktop:

• ≥ Chrome v23 (V8)
• ≥ Firefox v21 (SpiderMonkey)
• ≥ Safari v6 (Nitro)
• ≥ Opera v12 (V8)
• ≥ IE v11 (Chakra)

Mobile:

• ≥ Android 4.4
• ≥ iOS's WebKit 9

License

RIPE SDK is currently licensed under the Apache License, Version 2.0.

Build Automation