API

Spis treści

Introduction

netDecor app (called App/application, netDecor or Program) is embedded in HTML web page and has publicly facing API which lets send and receive data to/from web page app is embedded in. In particular, the following features are available in basic, unmodified version of netDecor:

  • Force program to open project send by webpage
  • Send project data to webpage
  • Send to app user login/logout state and username and show it in Program
  • Send to Program implementation of user-clicked fullscreen button in Program
  • Send references of items used in project to webpage
  • Get data about items from webpage (e.g. price)
  • Get data about physical location of running Program from webpage (Client’s shop/facility ID)


All this features require using netDecor’s API, most of the time call has an argument in which desired behaviour’s implementation should be sent. netDecor Team will add new features and modify exisitng ones, only on explicit Client’s demand, and only after evaluating price/time of feature.

Running application

Starting netDecor is easy: you need to include two .js files (NetPlusAPI.js, UnityLoader.js) and call RunNetPlusApp:

  1. function RunNetPlusApp(containerId,
    buildPath, params, onAPIInitialised);

containerId : String – ID of element where netDecor will be embedded.

buildPath : String – URL to app data (comes in package delivered by CADProjekt).

params : String – JSON containing startup info.

How exaclty JSON looks like is client-dependant, but one of parameters will be dbaddr : string – URL for database directory.

onAPIInitialised : Function – no-argument-method that will be called right after API initialisation is complete, parametr opcjonalny.

RunNetPlusAPP returns integer (errorCode):

0 – no error

1 – app is running already

If this call is executed properly there will be new object available: window.NetDecor, which contains API (also window.NetPlusAPI, API calls in that object are DEPRECATED and will be removed in a future.)

IMPORTANT netDecor API is not asynchronous and is available only after app is initially loaded. In order to be sure it is callable you need to implement onAPIInitialised parameter from runNetPlusAPP

Many of publicly facing API calls are overrides of events fired up by an app, in order to register override for event you need to call window.NetDecor.Events.RegisterEventHandler

  1. window.NetDecor.Events.RegisterEventHandler("eventName",methodToCall);

„eventName” : string – name of an event you want to override (names are included in this document)

methodToCall : function – method that will be called instead of default implementation when firing event.

Example:

  1. src="Build/UnityLoader.js">

  2. src="NetPlusAPI.js">

  3.  

Method can throw exceptions, most often because of bad call parameters. ALL API calls can throw exceptions!

Load Project

In order to force netDecor to open project send by webpage, call window.NetDecor.Project.Open:

  1. function
    window.NetDecor.Project.Open(buffer, params);

buffer : Uint8Array – typed array with project data

params : String – JSON string with additional project data, e.g. ID or project’s name.

Example:

  1. function
    whenReady(){

  2. var req =
    new XMLHttpRequest();

  3. req.open("GET","http://localhost:8001/project2.npf",
    true);

  4. req.responseType
    = "arraybuffer";

  5. req.onload =
    function (oEvent) {

  6. var blob =
    new Uint8Array(req.response);

  7. NetDecor.Project.Open(blob,
    JSON.stringify({id: "546536"}));};

  8. req.send();}

  9. RunNetPlusApp("appcontainer",
    "Build/","{
    \"dbaddr\":\"http://dev.netdecor.cadprojekt.com.pl/Example-Database/\"}",function(){

  10. console.log("APIREADY");

  11. whenReady();

  12. console.log("after ready")});

All parameters send by params are optional. Currently supported parameters include:

id : String – Project ID. If this exist, netDecor will send it while saving project.

name : String – Project name. If this exists, netDecor will send it while saving project and will show it in top-level bar in app UI, where it is modifiable by user.

readOnly : Bool – flag that marks project as read only. Program will block all tabs besides 'File’, 'Help’ and 'Basket’. Additionally, entering changes into scene is also blocked. Save action is not blocked.

Project is loaded after full app initialization and after basic database data is downloaded. Projects are not queued, only overwritten. That is why after app startup last send project will be loaded.

If both buffer and params are null new project window will be shown instead. Example:

  1. RunNetPlusApp("appconatiner",
    "Build/", runParams, function(){

  2. NetDecor.Project.Open(null, null)});

Method will throw exceptions in case of bad project buffer or when not valid param will be sent.

Save Project

To register event handler on save action, you need to call: NetDecor.Events.RegisterEventHandler(„SaveProject”,onSaveProject)

  1. function window.NetDecor.Events.RegisterEventHandler("SaveProject",onSaveProject);

„SaveProject” : string – event name.

onSaveProject(buffer, pngBuffer, params, items) : function – Implementation that will be called on fired save event.

buffer : Uint8Array – byte array with project data

pngBuffer : Uint8Array – byte array with preview (PNG)

params : String – JSON project parameters, e.g ID

items : String – JSON of items used in project, with indexes, quantity and prices

Parameters available in params:

id : String – Project ID. Will be send only if it was created.

name : String – Project name.

Parameter 'items’ contains array of objects that have properties:

refID : String – ID of product.

quantity : Decimal – how many items of this kind is in scene.

unitPrice : Decimal – price per item.

price : Decimal – total price (quantity*unitPrice)

Example:

  1. function onReady(){

  2. NetDecor.Events.RegisterEventHandler(

  3. "SaveProject",function(buffer, png, jsondata, items) {

  4. console.log("project size: "+ buffer.length);

  5. console.log("png size: " + png.length);

  6. console.log("json params: " + jsondata);

  7. console.log("items: " + items);});}

  8. RunNetPlusApp("appconatiner", "Build/", runParams, onReady);

Shop settings

NetDecor.Shop.SetShopInfo(shopInfo) : function – method that set info of physical location of running app (Client’s shop/facility). It takes JSON string as parameter. Content of JSON is client-dependant and will be customized for each NetDecor customization. Example:

  1. NetDecor.Shop.SetShopInfo(JSON.stringify({ id: 12, code: '035', name: 'Wrocław' }));

Method can thorw an exception when not valid params/ params names in JSON.

Fullscreen event

To register to Fullscreen event, you need to call: NetDecor.Events.RegisterEventHandler(„Fullscreen”,onFullScreen)

„Fullscreen” : string event name.

onFullScreen : function – method that will be called on fired fullscreen event.

  1. function NetDecor.Events.RegisterEventHandler("Fullscreen",onFullScreen);

User login/logout

This feature is established individually for every new customization of netDecor.

App DOES NOT HAVE any kind of user accounts nor login/logout feature.

App DOES HAVE possibility to show login/logout state of user of web page program is embedded in.

For this feature, netDecor makes available following API calls:

NetDecor.Events.RegisterEventHandler(„Login”,onLogin); – Register to onLogin event

„Login” : string – event name.

onLogin : function – method that will be called on event fired.

  1. loginState =
    {"state":true,"name":"userName"};

  2. NetDecor.Events.RegisterEventHandler("Login",function(){NetDecor.Login.SetLoginState(JSON.stringify(loginState))});

NetDecor.Events.RegisterEventHandler(„Logout”,onLogout); – Register to logout event. onLogout does not take any parameters.

Example: „Logout” : string – event name.

onLogout : function – method that will be called on fired event. Example:

  1. NetDecor.Events.RegisterEventHandler("Logout",function(){

  2. alert("Your are logged out
    now.")});

NetDecor.Events.RegisterEventHandler(„ShowProjects”,onShowProjects) – Register to event fired when user clicks 'My Projects’ button in user panel OR 'Open” from 'File’ tab. onShowProjects does not take any parameters.

„ShowProjects” : string event name.

onShowProjects : function – method tha will be called on event fired.

NetDecor.Login.SetLoginState(loginState) : string – Set login state inside of app. Takes JSON as a parameter. Example:

  1. {

  2. "state":true,

  3. "name":"userName"

  4. }

Parameter state specifies whether user should be logged in or out. true – user is logged in, false – logged out. Parameter name set the visible user name in app. It is not required when state is false.

Add to shop basket

To register to event fired whenever user adds item to shopping cart you need to call: NetDecor.Events.RegisterEventHandler(„AddToBasket”,onAddToBasket)

„AddToBasket” : string – event name.

onAddToBasket : function – method tha will be called on event fired.

  1. function
    NetDecor.Events.RegisterEventHandler("AddToBasket",onAddToBasket)

onAddToBasket(basket) : function – method that handles event, it takes one parameter: basket : string – JSON with content of shopping cart in netDecor, Exact format of JSON is client-dependant and established individually per each netDecor customization.

Przykład:

  1. NetDecor.Events.RegisterEventHandler("AddToBasket",
    function(basket){console.log("Shopping cart content:
    "+basket)});

Set Prices (static price-list)

In order to set prices for sellable products netDecor exposes two methods:

NetDecor.Shop.SetPrices(PricesJsonFile)

and

NetDecor.Shop.SetPricesFileUrl(PricesFileUrl)

Both methods take string as argument -> SetPrices takes stringified Json file with prices while SetPricesFileUrl takes Url to such json file. Both methods can throw exceptions when data is corrupted or null.

Json file should be array of ShopItem objects, base implementation of ShopItem is:

  1. class
    ShopItem

  2. {

  3. public ID :
    string; // Item reference ID

  4. public Price
    : number; // Price

  5. public
    Available : number; // Item availabilty. 1 - available, 0 - not
    available

  6. public
    Description : string; // Item name. Displayed in documentation.

  7. public
    UnitType : PriceUnitType;

  8. }

where PriceUnitType should be typed as string, which can be of values: „Unknown”,”Pieces”, „Area”, „Length” or „Packages”.

Note: Descriptions of cupboards from kitchen database are generated dynamically using price data. For correct generation of descriptions either static or dynamic prices loading must be implemented.

Set Prices (dynamic API)

We do not recommend static price-list for large data sets. For these cases, netDecor exposes event and method, to load prices asynchronously:

NetDecor.Events.RegisterEventHandler(„OnShopItemDataRequest”,onShopItemDataRequest)

NetDecor.Shop.SetShopItemData(itemID : string, itemDataJson : string)

OnShopItemDataRequest event is called when application needs a price of a specific item. To send price back to the application, call SetShopItemData. Example:

  1. window.NetDecor.Events.RegisterEventHandler("OnShopItemDataRequest",
    function (item) {

  2. window.NetDecor.Shop.SetShopItemData(item,
    JSON.stringify({

  3. ID: item,

  4. Price: 200,

  5. Available:
    1,

  6. UnitType:
    "Pieces",

  7. Description:
    "Item name"

  8. }));

  9. });

SetShopItemData method can be called synchronously or asynchronously. Application match request with result by itemID.

All prices are cached in application memory. To clear this cache, call ClearPrices method:

NetDecor.Shop.ClearPrices()

This method can also clear prices served through static API.

Note: Descriptions of cupboards from kitchen database are generated dynamically using price data. For correct generation of descriptions either static or dynamic prices loading must be implemented.

Language change

In order to force language change you need to call:

NetDecor.Lang.SetLang(’langCode’)

„langCode” : string – ISO 639-1 language code (two letters). Available languages depends on specific netDecor customization.

Example:

  1. NetDecor.Lang.SetLang("DE");

Adding videos to 'Help' tab

netDecor can play videos (located in 'help’ tab). List of videos can be different per language chosen. To add videos to netDecor instance, you need to call:

NetDecor.Help.AddVideoList(videoFilesJson);

THIS METHOD IS OBSOLETE ~~NetDecor.Help.AddVideos(„langCode”,(videoFilesJson));~~

„langCode” : string – ISO 639-1 language code (two letters). Available languages depends on specific netDecor customization. Program will switch help tab to use that language video list.

videoFilesJSON : string – JSON with videos names, in specified format:

  1. videoJson =

  2. {"LangCode
    1":[

  3. {"Name":"Shown
    name","FilePath":"video URL"},

  4. {"Name":"Shown
    name","FilePath":"video URL"}],

  5. "LangCode
    2":[

  6. {"Name":"Shown
    name","FilePath":"video URL"},

  7. {"Name":"Shown
    name","FilePath":"video URL"}],

  8. "LangCode
    3":[

  9. {"Name":"Shown
    name","FilePath":"video URL"},

  10. {"Name":"Shown
    name","FilePath":"video URL"}]};

Example:

  1. function
    onReady()

  2. {

  3. videoJson =

  4. {"PL":[

  5. {"Name":"Dodatkowe
    Wyposażenie","FilePath":"PL//dodatkowewyposazenie.mp4"},

  6. {"Name":"Kolor
    Ścian I Podłogi","FilePath":"PL//kolorscianipodlogi.mp4"}],

  7. "EN":[

  8. {"Name":"Additional
    Equipment","FilePath":"PL//dodatkowewyposazenie.mp4"},

  9. {"Name":"Floor
    and Walls Color","FilePath":"PL//kolorscianipodlogi.mp4"}],

  10. "DE":[

  11. {"Name":"Zusatzausstattung","FilePath":"PL//dodatkowewyposazenie.mp4"},

  12. {"Name":"Wand-
    und Bodenfarbe","FilePath":"PL//kolorscianipodlogi.mp4"}]};

  13. NetDecor.Help.AddVideos("PL",(JSON.stringify(videoJson)));

  14. }

  15. RunNetPlusApp("appcontainer",
    "Build/","{ \"dbaddr\":\"database/\"}",onReady);