Home Reference Source

MagiCAD Widget SDK Version 4.1.0.376

MagiCAD Widget SDK offers simple access to MagiCAD Cloud Resources.

Getting Started

Just include MagiCAD Widget SDK to your web site. Initialize MagiCAD Widget SDK based to your needs and MagiCAD Cloud Resources are available for your web site.

If you have been already done implementation with earlier version then you should look migration guide to update your implementation.

Prerequisites

  1. Contact to MagiCAD Cloud Team and get your own client_id. Some of MagiCAD Cloud resources e.g. RFA/DXF downloads need authentication. Using restricted resources you need to host provided html page(s) which will be set as trusted at our authentication server and bound to your client_id:
    1. popup_redirect_uri - the URI that the popup window will be redirected to after successful sign-in OR
    2. redirect_uri - the URI that the main browser window will be redirected to after successful sign-in. NOTE: if this is given, popup_redirect_uri will be ignored and redirection is used instead of popup
    3. post_logout_redirect_uri - the URI that the browser window (or popup) will be redirected to (after user interaction) on successful sign-out

You need to decide which sign-in/sign-out mechanism you will use; either popup or redirect.

  1. Your web site must use HTTPS protocol because of restricted resources and sensitive login information.

Installing

Include script to bottom of body

<script src="https://sdk.magicloud.com/v4/magicad-widget-sdk.min.js"></script>

Initialize

You need to call init function to initialize MagiCAD Widget SDK library.

MagiCAD.init({
    client_id: 'YOUR_CLIENT_ID',           
    popup_redirect_uri: 'URI_TO_REDIRECT_TO_AFTER_POPUP_SIGNIN', // Will be ignored if redirect_uri is given
    redirect_uri: 'URI_TO_REDIRECT_TO_AFTER_REDIRECT_SIGNIN',
    post_logout_redirect_uri: 'URI_TO_REDIRECT_TO_AFTER_SIGNOUT',

    // Authenticated user status events
    onLoadUser: function (user) {
        // Event handler to get signed in user if any exists
        // e.g. case when page refreshed
    },
    onSignin: function (user) {
        // Event handler to perform some action on user signin
    },
    onSignout: function () {
        // Event handler to perform some action on user signout
    },

    // Product data load events
    onLoad: function(data) {
        // Event handler to perform some action on product data load
    },
    onLoadError: function(err) {
        // Event handler to perform some action on error when product data loaded
    },

    // X3D rendering
    onRenderX3D: function() {
        // Event handler to perform some action after succesful x3d rendering
    }
});

Implement business logic

MagiCAD.init({
    ...
    onLoad: onLoad,
    onLoadError: onLoadError
    ...
});

MagiCAD.load({
    productId: 'YOUR_PRODUCT_ID'    
});

// Set to onLoad property on init method
function onLoad(data) {
    var productCode = data.ProductCode;
    var dxfDownloadUrl = data.DxfUrl;
    var attachments = data.Attachments; // contains e.g. RFA files
    var image2D = data.ImageUrl;
    var dimensionImage = data.DimensionsUrl;

    var options = {
        containerId: 'YOUR_3D_CONTAINER_ID',
        x3dUri: data.X3DUrl,
        imageUri: data.ImageUrl
    };
    MagiCAD.renderX3D(options);

    var variantInfo = data.VariantDetails; // If any variants
    var variantCount = data.VariantDetails.VariantCount;
    // NOTE: Remember add pagingSize query to get amount of needed variants otherwise top 10 will be listed
    var moreVariantInfoUrl = data.VariantDetails.VariantDetailsUrl + "?pagingSize=" + data.VariantDetails.VariantCount;

    // Get response from moreVariantInfoUrl and use is similar than above e.g. response.ImageUrl
    // Example:
    $.get(moreVariantInfoUrl).then(function (response) {
        $.each(response, function (index, item) {
            $.get(item.DetailsUrl).then(function (itemResponse) {
                var variantImageUrl = itemResponse.ImageUrl;
            });
        });
    });

    // update UI
    ...
}

// Set to onLoadError property on init method
function onLoadError(err) {
    // Handle error situation....
}

Authentication

MagiCAD Cloud Authentication requires client_id specified by MagiCAD Cloud team. The client_id is provided against to the popup_redirect_uri where you need to host login callback html file for finalization of performed authentication action. We will provide minimum content of the callback html file. You can customize that html page to indicate for user that some authentication action is going on e.g. progress bar or spinner but it is not required. After successful authentication all restricted resource urls will contain needed information to download resouce e.g. token, applicationId and sessionId.

Callback HTML file, sign-in popup method

It is required to host callback html file in same domain where MagiCAD Widget SDK is used to complete authentication action e.g. login action.

NOTE: This html file will be seen awhile when authentication action is performed. You can create some custom styles for this page if wanted. Following example contains simple spinner.

Example content of callback html file. This file is required to be available on popup_redirect_uri:

<!DOCTYPE html>
<html>

<head>
    <link rel="stylesheet" type="text/css" href="https://sdk.magicloud.com/v4/callbacks/loader.css">
</head>

<body>
    <div class="loader"></div>
    <script src="https://sdk.magicloud.com/v4/callbacks/oidc-client.min.js"></script>
    <script src="https://sdk.magicloud.com/v4/callbacks/signin-popup-callback.js"></script>
</body>

</html>
Callback HTML file, sign-in redirect method

If using browser redirect instead of popup (redirect_uri configured), same principle applies: you have to host the callback html file on the same domain where MagiCAD Widget SDK is used. Additionally, you need to finish the sign-in process yourself. You can, for example, set a custom redirect back to whatever page your user was on.

Note that Oidc.UserManager.signinRedirectCallback() must be called to add the signed-in user's information to the client application. Other things you are free to customize on this html file.

Example:

<!DOCTYPE html>
<html>

    <head>
        <link rel="stylesheet" type="text/css" href="https://sdk.magicloud.com/v4/callbacks/loader.css">
    </head>

    <body>
        <div class="loader"></div>
        <script src="https://sdk.magicloud.com/v4/callbacks/oidc-client.min.js"></script>
        <script type="text/javascript">
            new Oidc.UserManager({
                userStore: new Oidc.WebStorageStateStore({ store: window['localStorage'] || window.sessionStorage })})
            .signinRedirectCallback()
            .then(function (user) {
                window.history.replaceState({},
                window.document.title,
                window.location.origin);
            }).catch(e => {
                console.log("Error or canceled signin.");
            }).finally(() => {
                window.location = 'your-desired-redirection-url'
        });
        </script>
    </body>

</html>
Callback HTML file, sign-out

You may do any custom logic on the post_logout_redirect_uri HTML file to which the user can be redirected to after sign-out, or you can show a thank you page or similar.

Signin
// Use signin when user signin needed
MagiCAD.signin();
Signout
// Use signout when user signout needed
MagiCAD.signout();
Get authenticated user status

You can set event handlers during initialization of the MagiCAD Widget SDK library:

MagiCAD.init({
    client_id: 'YOUR_CLIENT_ID',           
    popup_redirect_uri: 'TRUSTED_REDIRECT_URI',
    post_logout_redirect_uri: 'TRUSTED_LOGOUT_REDIRECT_URI',

    onLoadUser: function (user) {
        console.log($`user {user.username} is signed in.`);
    },
    onSignin: function (user) {
        console.log($`user {user.username} signed in.`);
    },
    onSignout: function () {
        console.log('user is signed out!');
    },
    ...
});
How to access restricted resources?

DXF and RFA downloads are restricted resources. Before showing download links in UI you need to check is user logged in. If user is logged in then product data contain needed information to get restricted resources. Otherwise resources cannot be downloaded.

// Set to onLoad property on init method
function onLoad(data) {        
    // If user is authenticated these links will contain needed parameters to download content
    // Otherwise links can be only used to determine available downloads
    var dxf = data.DxfUrl; // DXF link
    var attachments = data.Attachments; // RFA links
}
How to maintain authentication status in UI?

You can handle authenticated user status on UI by using onLoadUser, onSignin and onSignout event setters.

Disclaimer: This is just example and you might need to implement your own business logic for authentication

MagiCAD.init({
    client_id: 'YOUR_CLIENT_ID',           
    popup_redirect_uri: 'TRUSTED_REDIRECT_URI',
    post_logout_redirect_uri: 'TRUSTED_LOGOUT_REDIRECT_URI',

    onLoadUser: function (user) {
        console.log($`user {user.username} is signed in.`);
    },
    onSignin: function (user) {
        console.log($`user {user.username} signed in.`);
    },
    onSignout: function () {
        console.log('user is signed out!');
    },
    ...
});

updateUI();
updateDimensionsX3D();

function updateUserInfo(user) {
    if (user) {
        $("#login").hide();
        $("#logout").show();
        $("#username").text(user.username);
    } else {
        $("#logout").hide();
        $("#login").show();
        $("#username").empty();
    }
    updateUI();
}

$("#login").click(function () {
    MagiCAD.signin();
});
$("#logout").click(function () {
    MagiCAD.signout();
});

Features

Features introduced below require load method call to get product data.

How to use diagrams?

You need to specify diagram image and data image containers with wanted diagram type Currently supported diagrams:

{ Ventilation, Heating, Cooling, SupplyAir, ExtractAir, Radiator, Pump }

Diagrams available for current product can be read from Diagrams property Example of Diagrams property:

{ "Ventilation": { "BaseUrl": "https://.../api/diagram/abc/Ventilation", "HasData": true } }

Usage:

$.each(data.Diagrams, function (diagramType, item) {
    if (item.HasData) {
        // When user clicks element with id `diagramImageContainer-${diagramType}` 
        // then diagram data will appear to element with id `diagramDataImageContainer-${diagramType}`
        MagiCAD.setDiagram(data, { 
            type: diagramType, 
            elementId: `diagramImageContainer-${diagramType}`, 
            dataElementId: `diagramDataImageContainer-${diagramType}` 
        });

        // You can also operate with operation point values (valueXAxis/valueYAxis) if you have those already:
        // MagiCAD.setDiagram(data, 
        // { type: diagramType, 
        //   elementId: `diagramImageContainer-${diagramType}`, 
        //   dataElementId: `diagramDataImageContainer-${diagramType}`, 
        //   operationPoint: { x: valueXAxis, y: valueYAxis}
        // });
    }
    else {
        // Render diagram to element with id `diagramImageContainer-${diagramType}`
        MagiCAD.setDiagram(data, { type: diagramType, elementId: `diagramImageContainer-${diagramType}` });
    }
});

Advanced operations

2D, 3D and dimension images by QModelId and QModelParameters

QModel values can be used to create 2D, 3D and dimension images and this method doesn't require load method at all i.e. you can instantly call below methods to get needed resources without load method call.

var options = {
    containerId: 'x3dContainer',
    QModelId: qmodelId,                  // QModelId to customize X3D image
    QModelParameters: qmodelParameter,   // QModelParameters used to customize X3D image        
    ViewMode: 1,                         // ViewMode: [0=Rendered, 1=DimensionLabels, 2=DimensionValues]
    ViewPosition: 1                      // ViewPosition: [0=Default, 1=Front, 2=Right, 3=Left, 4=Top, 5=Bottom, 6=IsometricLeft, 7=IsometricRight]
}
// Note: Second parameter. First time rendering x3d image pass false and always on update pass true
MagiCAD.renderX3D(options, update);

var alternativeImageUrl = MagiCAD.getImageQueryUrl(options);
var alternativeDimensionImageUrl = MagiCAD.getDimensionImageQueryUrl(options);
Level of detail (LOD) for 3D models

If the model supports it, you can specify the wanted level of detail (LOD). The LOD value is a number between 0 and 3, where 3 is the highest level of detail (MC LOD 350) and 1 is the lowest (MC LOD 200). Level 0 (default) is a preview model for illustration and product selection purposes.

var options = {
    containerId: 'x3dContainer',
    QModelId: qmodelId,                  // QModelId to customize X3D image
    QModelParameters: qmodelParameter,   // QModelParameters used to customize X3D image        
    LodLevel: 3                          // LodLevel: [0=Preview, 1=MC LOD 200, 2=MC LOD 300, 3=MC LOD 350]
}
// Note: Second parameter. First time rendering x3d image pass false and always on update pass true
MagiCAD.renderX3D(options, update);

Migration Guide from 2.x to 4.x

Introduction

Prerequisites

Include script to bottom of body

Replace

<script src="https://sdk.magicloud.com/magicloud.min.js"></script>

With

<script src="https://sdk.magicloud.com/v4/magicad-widget-sdk.min.js"></script>

Initialize

You need to call init function to initialize MagiCAD Widget SDK library. Without init function call MagiCAD Widget SDK cannot be used.

MagiCAD.init({
    client_id: 'YOUR_CLIENT_ID',           
    popup_redirect_uri: 'TRUSTED_REDIRECT_URI',

    // Authenticated user status events
    onLoadUser: function (user) {
        // Event handler to get signed in user if any exists
        // e.g. case when page refreshed
    },
    onSignin: function (user) {
        // Event handler to perform some action on user signin
    },
    onSignout: function () {
        // Event handler to perform some action on user signout
    },

    // Product data load events
    onLoad: function(data) {
        // Event handler to perform some action on product data load
    },
    onLoadError: function(err) {
        // Event handler to perform some action on error when product data loaded
    },

    // X3D rendering
    onRenderX3D: function() {
        // Event handler to perform some action after succesful x3d rendering
    }
});

Authentication

Properties applicationId and returnUri are deprecated and will be automatically mapped to new properties:

It is recommended to use client_id and popup_redirect_uri properties instead of obsolete properties.

MagiCAD.init({
    // applicationId: 'YOUR_APPID', // Use client_id instead. Property applicationId is deprecated and will be mapped to client_id.
    // returnUri: 'YOUR_RETURNURI', // Use popup_redirect_uri instead. Property returnUri is deprecated and will be mapped to popup_redirect_uri.
    client_id: 'YOUR_CLIENTID',
    popup_redirect_uri: 'YOUR_REDIRECT_URI' // callback html file
})

It is now required to host callback html file in same domain where MagiCAD Widget SDK is used to complete authentication action e.g. login action.

Minimum content of callback html file is required to be available on popup_redirect_uri. You can create your custom styles for this page:

<!DOCTYPE html>
<html>

<body>
    <script src="https://sdk.magicloud.com/v4/callbacks/oidc-client.min.js"></script>
    <script src="https://sdk.magicloud.com/v4/callbacks/signin-popup-callback.js"></script>
</body>

</html>

MagiCAD Cloud team will set your popup_redirect_uri as trusted url and after that authentication will work.

Now signin and signout functions are simplified to take no parameters:

MagiCAD.signin();
MagiCAD.signout();

Load method

You can now introduce onLoad, onLoadError and onRenderX3D functions on MagiCAD.init(options) function call by giving those in options object.

MagiCAD.init({
   ...
   onLoad: function(data) { ... },
   onLoadError: function(err) { ... },
   onRenderX3D: function() { ... },
   ...
});

MagiCAD.load({
    // applicationId: 'YOUR_APPID', // applicationId is not used anymore in load method so it can be removed
    productId: 'SOMETHING',
    logoContainerId: 'SOMETHINGELSEHERE',
});

Obsolete methods and properties

Authenticated user can be checked now with event handlers:

MagiCAD.init({
    ...
    onLoadUser: function (user) {
        console.log($`user {user.username} is signed in.`);
    },
    onSignin: function (user) {
        console.log($`user {user.username} signed in.`);
    },
    onSignout: function () {
        console.log('user is signed out!');
    },
    ...
});

© MagiCAD Group Ltd. All rights reserved