Return to Common Add-in functions

Creating a Custom View

One of the more common types of add-ins that you create will be a custom view. The following steps and example code will show you how to go about creating a custom view:

  1. Optionally, create an HTML file for the custom view.
  2. Add code to the main.js file to register your custom view.

Create an HTML file

You must create your custom view HTML file in your add-in directory. This code creates an example custom view called view.html. If you do not wish to distribute an HTML file with your add-in, or you have another web page you wish to include as a view, you may skip this step.

<!doctype html>
<html>
<head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
    <title>Add-in View</title>
    <script>
        function apiLoaded() {
            var versionString = "I am running version " + ININ.Addins.version + " of the add-in API.";
            document.getElementById("version").innerText = versionString;
        }
    </script>
</head>
<body>
    <h1>Hello world!</h1>
    <h2 id="version">API not yet loaded</h2>
</body>
<script src="inin.addins.lib.js" data-callback="apiLoaded"></script>
</html>

Note: If you want to use the API, you must add a script tag to reference inin.addins.lib.js. The callback specified by the data-callback attribute is called when the add-in API has loaded. Using the script tag is optional - if you do not wish to call the add-in API, do not use the script tag.

Add code to the main.js file

You must register your custom view by calling ININ.Addins.UI.Views.registerView. This example code illustrates this procedure for the view.html file:

ININ.Addins.UI.Views.registerView({
    viewId: 'addin-view',
    displayName: 'Add-in View',
    description: 'An example add-in view',
    pageUrl: 'view.html'
});

If you do not wish to distribute an HTML file with your add-in, or you have another web page you wish to include as a view, you may specify an absolute URL to the page as the pageUrl property. For example:

ININ.Addins.UI.Views.registerView({
    viewId: 'addin-view-web-age',
    displayName: 'Add-in Web Page',
    description: 'An example add-in view that loads a web page',
    pageUrl: 'http://www.example.com/your-view'
});

If you do not wish to allow multiple instances of your view to be added by the user, you may specify the optional singleInstance property. For example:

ININ.Addins.UI.Views.registerView({
    viewId: 'addin-view',
    displayName: 'Add-in View',
    description: 'An example add-in view',
    pageUrl: 'view.html',
    singleInstance: true
});

Note:

  • Add-in views are loaded into a sandboxed iframe element, as such certain features are disabled.
  • Web browsers that support the X-Frame-Options HTTP response header may refuse to load an externally referenced view depending on the value of X-Frame-Options. Ensure the web server is properly configured to send the appropriate values.