WebFigures

Using the WebFigures feature in MATLAB Builder NE you can display MATLAB figures on a Web site for graphical manipulation by end users. This enables them to use their graphical applications from anywhere on the Web without the need to download MATLAB or other tools that can consume costly resources.

This chapter includes Quick Start Implementation of WebFigures, which guides you through implementing the basic features of WebFigures, and an advanced section to let you customize your configuration depending on differing server architectures.

Supported Renderers for WebFigures

The MATLAB Builder NE WebFigures feature uses the same renderer used when the figure was originally created by default.

In MATLAB, the renderer is either explicitly specified for a figure or determined by the data being plotted. For more information about supported renderers in MATLAB, see http://www.mathworks.com/support/tech-notes/1200/1201.html.

Note   The WebFigures feature does not support the Painter renderer due to technical limitations. If this renderer is requested, the renderer Zbuffer will be invoked before the data is displayed on the Web page.

Back to Top

WebFigures Prerequisites

• Your Role in the .NET WebFigure Deployment Process

• What You Need to Know to Implement WebFigures

• Required Products

• Assumptions About the Examples

Your Role in the .NET WebFigure Deployment Process

Depending on your role in your organization, as well as a number of other criteria, you may need to implement either the beginning or the advanced configuration of WebFigures.

The table WebFigures for .NET Deployment Roles, Responsibilities, and Tasks describes some of the different roles, or jobs, that MATLAB Builder NE users typically perform and which method of configuration they would most likely use when running Quick Start Implementation of WebFigures and Advanced Configuration of a WebFigure.

WebFigures for .NET Deployment Roles, Responsibilities, and Tasks

What You Need to Know to Implement WebFigures

The following knowledge is assumed when you implement WebFigures for .NET:

• If you are a MATLAB programmer:

  • A basic knowledge of MATLAB

• If you are a .NET programmer:

  • Knowledge of how to build a Web site using Microsoft Visual Studio.

  • Experience deploying MATLAB applications

Required Products

Install the following products to implement WebFigures for .NET, depending on your role.

Assumptions About the Examples

To work with the examples in this chapter:

• Assume the following MATLAB function has been created:

  function df = getKnot()
          f = figure('Visible','off');  %Create a figure.
                             %Make sure it isn't visible.
          knot;              %Put something into the figure.
          df = webfigure(f); %Give the figure to your function
                             % and return the result.
          close(f);          %Close the figure.
  end

• Assume that the function getKnot has been deployed in a .NET component (using Getting Started for example) with a namespace of MyComponent.MyComponentclass.

• Assume the MATLAB Compiler Runtime (MCR) has been installed. If not, refer to Installing the MATLAB Compiler Runtime (MCR) in the MATLAB Compiler documentation.

• If you are running on a system with 64-bit architecture, use the information in Advanced Configuration of a WebFigure to work with WebFigures unless you are deploying a Web site which is 32-bit only and you have a 32-bit MCR installed.

Back to Top

Quick Start Implementation of WebFigures

• Overview

• Procedure

Overview

Using Quick Start, both the WebFigure service and the page that has the WebFigure embedded on it reside on a single server. This configuration enables you to quickly drag and drop the WebFigureControl on a Web page.

Procedure

To implement WebFigures for MATLAB Builder NE using the Quick Start approach, do the following. For more information about the Quick Start option, see WebFigures.

1. Start Microsoft Visual Studio.

2. Select File > New > Web Site to open.

3. Select one of the template options and click OK.

   Caution   Do not select Empty Web Site as it is not possible to create a WebFigure using this option.

4. Add WebFigureControl to the Microsoft Visual Studio toolbar by dragging the file InstallRoot\toolbox\dotnetbuilder\bin\arch\v2.0\
   WebFiguresService.dll, (where InstallRoot is the location of the installed MCR for machines with an installed MCR and matlabroot on a MATLAB Builder NE development machine without the MCR installed), on to the Microsoft Visual Studio Toolbox toolbar as follows:

   Note   If you are running on a system with 64-bit architecture, use the information in Advanced Configuration of a WebFigure to work with WebFigures unless you are deploying a Web site which is 32-bit only and you have a 32-bit MCR installed.

   1. Expand the General section of the Toolbox toolbar.

   2. Using your mouse, drag the DLL file to the expanded section, as shown by the arrow:

      

   If you added the control correctly, you will see the following WebFigureControl in the General section of the Microsoft Visual Studio toolbar:

   

5. Drag the WebFigureControl from the toolbar to your Web page. After dragging, the Web page displays the following default figure.

   

   You can resize the control as you would any other .NET Web control.

6. Switch to the Design view in Microsoft Visual Studio by selecting View > Designer.

7. Test the Web page by "playing" it in Microsoft Visual Studio. Select Debug > Start Debugging. The page should appear as follows.

   

8. Interact with the default figure on the page using your mouse. Click one of the three control icons at the top of the figure to activate the desired control, select the desired region of the figure you want to manipulate, then click and drag as appropriate. For example, to zoom in on the figure, click the magnifying glass icon, then hover over the figure.

9. Close the page as you would any other window, automatically exiting debug or "play" mode.

10. The WebFigureService you created has been verified as functioning properly and you can attach a custom WebFigure to the Web page:

    1. To enable return of the webfigure and to bind it to the webfigure control, add a reference to MWArray to your project and a reference to the deployed component you created earlier (in Assumptions About the Examples). See Component Integration for more information.

    2. In Microsoft Visual Studio, access the code for the Web page by selecting View > Code.

    3. In Microsoft Visual Studio, go to the Page_Load method, and add this code, depending on if you are using the C# or Visual Basic language. Adding code to the Page_Load method ensures it executes every time the Web page loads.

       Note   The following code snippets belong to the partial classes generated by your .NET Web page.

       • C#:

         using MyComponent;
         using MathWorks.MATLAB.NET.WebFigures;
         
         protected void Page_Load(object sender, EventArgs e)
         {
                 MyComponentclass myDeployedComponent =
                         new MyComponentclass();
                 WebFigureControl1.WebFigure =
                         new WebFigure(myDeployedComponent.getKnot());
         }
         

       • Visual Basic:

         Imports MyComponent
         Imports MathWorks.MATLAB.NET.WebFigures
         
         Protected Sub Page_Load(ByVal sender As Object,
                                 ByVal e As System.EventArgs)
                                 Handles Me.Load
             Dim myDeployedComponent As _
                  New MyComponentclass()
             WebFigureControl1.WebFigure = _
                  New WebFigure(myDeployedComponent.getKnot())
         End Sub
         

       Tip   This code causes the deployed component to be reinitialized upon each refresh of the page. A better implementation would involve initializing the myDeployedComponent variable when the server starts up using a Global.asax file, and then using that variable to get the WebFigure object. For more information on Global.asax, see Using Global Assembly Cache (Global.asax) to Create WebFigures at Server Start-Up.

       Note   WebFigureControl stores the WebFigure object in the IIS session cache for each individual user. If this is not the desired configuration, see Advanced Configuration of a WebFigure for information on creating a custom configuration.

11. Replay the Web page in Microsoft Visual Studio to confirm your WebFigure appears as desired. It should look like this.

    

Back to Top

Advanced Configuration of a WebFigure

• Overview

• Manually Installing WebFigureService

• Retrieving Multiple WebFigures From a Component

• Attaching a WebFigure

• Setting Up WebFigureControl for Remote Invocation

• Getting an Embeddable String That References a WebFigure Attached to a WebFigureService

• Improving Processing Times for JavaScript Using Minification

• Using Global Assembly Cache (Global.asax) to Create WebFigures at Server Start-Up

Overview

The advanced configuration gives the experienced .NET programmer (possibly a business service developer or front-end developer) flexibility and control in configuring system architecture based on differing needs. For example, with the WebFigureService and the Web page on different servers, the administrator can optimally position the MCR (for performance reasons) or place customer-sensitive customer data behind a security firewall, if needed.

In summary, the advanced configuration offers more choices and adaptability for the user more familiar with Web environments and related technology, as illustrated by the following graphics.

This section describes various ways to customize the basic WebFigures implementation described in Quick Start Implementation of WebFigures.

Manually Installing WebFigureService

WebFigureService is essentially a set of HTTP handlers that can service requests sent to an instance of Internet Information Service (IIS). There are occasions when you may want to manually install WebFigureService. For example:

• You want to implement the WebFigure controls programmatically and provide more detailed customization.

• Your Web environment was reconfigured from when you initially ran the Quick Start Implementation of WebFigures.

• You want to implement WebFigures in a multiple server environment, as depicted in the previous graphic.

• You want to understand more about how WebFigures for .NET works.

When you dragged the GUI control for WebFigures onto the Web page in Quick Start Implementation of WebFigures, you automatically installed WebFigureService in the Web application file web.config.

To install this manually:

1. Add a reference to WebFiguresService.dll from the folder InstallRoot\toolbox\dotnetbuilder\bin\arch\v2.0 to the project, (where InstallRoot is the location of the installed MCR for machines with an installed MCR and matlabroot on a MATLAB Builder NE development machine without the MCR installed).

2. Add these lines to the <httpHandlers> section of web.config. This tells IIS to send any requests that come to the __WebFigures.ashx file to the WebFigureHttpHandlerFactory in the WebFiguresService.dll.

   <httpHandlers>
           <add 	path="__WebFigures.ashx"
                   verb="GET"
                   type="MathWorks.MATLAB.NET.WebFigures.
                           Service.Handlers.Factories.
                           Http.WebFigureHttpHandlerFactory"
                   validate="false" />
   </httpHandlers>
   

Retrieving Multiple WebFigures From a Component

If your deployed component returns several WebFigures, then you have to make additional modifications to your code.

MATLAB sees a WebFigure the same way it see a MWStructArray. WebFigure constructors accept a WebFigure, an MWArray, or an MWStructArray as inputs.

Use the following examples as guides, depending on what type of functions you are working with.

Working with Functions that Return a Single WebFigure as the Function's Only Output.  

 C#

using MyComponent;
using MathWorks.MATLAB.NET.WebFigures;

public class
{
        protected void Page_Load(object sender, EventArgs e)
        {
                MyComponentclass myDeployedComponent =
                   new MyComponentclass();

                WebFigureControl1.WebFigure =
                   new WebFigure(myDeployedComponent.getKnot());
        }
}

 Visual Basic

Imports MyComponent
Imports MathWorks.MATLAB.NET.WebFigures

Class
        Protected Sub Page_Load(ByVal sender As Object,
                                ByVal e As System.EventArgs)
                                Handles Me.Load
                Dim myDeployedComponent As _
                    New MyComponentclass()

                WebFigureControl1.WebFigure = _
                    New WebFigure(myDeployedComponent.getKnot())
        End Sub
End Class

Working With Functions That Return Multiple WebFigures In an Array as the Output.  

 C#

using MyComponent;
using MathWorks.MATLAB.NET.WebFigures;

public class
{
        protected void Page_Load(object sender, EventArgs e)
        {
                MyComponentclass myDeployedComponent =
                        new MyComponentclass();

		 //If the function returns an array with 4 WebFigures 
		 //  in it and takes in no inputs.
		 MWArray[] outputs = myDeployedComponent.getKnot(4);	
		
                WebFigureControl1.WebFigure =
                        new WebFigure(outputs[0]);

		 WebFigureControl2.WebFigure =
                        new WebFigure(outputs[1]);

		 WebFigureControl3.WebFigure =
                        new WebFigure(outputs[2]);

  		 WebFigureControl4.WebFigure =
                        new WebFigure(outputs[3]);
        }
}

 Visual Basic

Imports MyComponent
Imports MathWorks.MATLAB.NET.WebFigures

Class
        Protected Sub Page_Load(ByVal sender As Object,
                                ByVal e As System.EventArgs)
                                Handles Me.Load
                Dim myDeployedComponent As _
                        New MyComponentclass()

		 Dim outputs as MWArray() = _
			myDeployedComponent.getKnot(4)
 		
                WebFigureControl1.WebFigure = _
                        New WebFigure(outputs(0))

                WebFigureControl2.WebFigure = _
                        New WebFigure(outputs(1))

                WebFigureControl3.WebFigure = _
                        New WebFigure(outputs(2))

                WebFigureControl4.WebFigure = _
                        New WebFigure(outputs(3))
        End Sub
End Class

Attaching a WebFigure

After you have manually installed WebFigureService, the server where it is installed is ready to receive requests for any WebFigure information. In the Quick Start, WebFigureService uses the session cache built into IIS to retrieve a WebFigure, per user, and display it. Since a WebFigureControl isn't being used in this case, you need to manually set up the WebFigureService and attach the WebFigure. Add the code supplied in this section to attach a WebFigure of your choosing.

This method of setting up WebFigureService and attaching the figure manually is very useful in the following situations:

• You do not want front-end servers to have WebFigureService running on them for performance reasons.

• You are displaying a WebFigure that does not change based on the current user or session. When multiple users are sharing the same WebFigure, which is very common, it is much more efficient to store a single WebFigure in the Application or Cache state, rather than issuing all users their own figure.

There are a number of ways to attach a WebFigure to a scope, depending on state (note that these terms follow standard industry definitions and usage):

Note   In this type of configuration, it is typical to have the following code executed once in the Global.asax server startup block. For more information on Global.asax, see Using Global Assembly Cache (Global.asax) to Create WebFigures at Server Start-Up.

Add the following code to manually attach the WebFigure, based on whether you are using C# or Visual Basic:

• C#:

  MyComponentclass myDeployedComponent =
          new MyComponentclass();
  
  Session["SessionStateWebFigure"] =
          new WebFigure(myDeployedComponent.getKnot());
  

  Or

  Application["ApplicationStateWebFigure"] =
          new WebFigure(myDeployedComponent.getKnot());
  

  Or

  Cache["CacheStateWebFigure"] =
          new WebFigure(myDeployedComponent.getKnot());

• Visual Basic:

  Dim myDeployedComponent As _
          New MyComponentclass()
  
  Session("SessionStateWebFigure") = _
          New WebFigure(myDeployedComponent.getKnot())
  

  Or

  Application("ApplicationStateWebFigure") = _
          New WebFigure(myDeployedComponent.getKnot())
  

  Or

  Cache("CacheStateWebFigure") = _
          New WebFigure(myDeployedComponent.getKnot())
  

Setting Up WebFigureControl for Remote Invocation

After you drag a WebFigureControl onto a page, as in Quick Start Implementation of WebFigures, you either assign the WebFigure property or set the Remote Invocation properties, depending on how the figure will be used.

The procedure in this section allows you to tell WebFigureControl to reference a WebFigure that has been manually attached to a WebFigureService on a remote server or cluster of remote servers. This allows you to use the custom control, yet the resources of WebFigureService are running on a remote server to maximize performance.

1. Drag a WebFigureControl from the toolbox onto the page, if you haven't done so already in Quick Start Implementation of WebFigures.

   Note   If you are running on a system with 64-bit architecture, use the information in Advanced Configuration of a WebFigure to work with WebFigures unless you are deploying a Web site which is 32-bit only and you have a 32-bit MCR installed.

2. In the Properties pane for this control, set the Name and Scope attributes as follows:

   • Name ApplicationStateWebFigure

   • Scope application

     Caution   Always attempt to define the scope. If you leave Scope blank, the Session state, the Application state, and then the Cache state (in this order) will be checked. If there are WebFigures in any of these states with the same name, there can be potential for conflict and confusion. The first figure with the same name will be used by default.

   The pane should now look like this:

   

   Note   If you don't provide a root (usually the location of the load balancer), it is assumed to be the server where the page is executing.

Getting an Embeddable String That References a WebFigure Attached to a WebFigureService

From any server, you can use the GetHTMLEmbedString API to get a string that can be embedded onto a page, if you followed the procedures Manually Installing WebFigureService in Attaching a WebFigure.

To do so, use the following optional parameters and code snippets (or something similar, depending on your implementation). For information on the differences between session, application, and cache scopes, see Attaching a WebFigure.

GetHTMLEmbedString API Parameters

Referencing a WebFigure Attached to the Local Server.  

• C#:

  using MathWorks.MATLAB.NET.WebFigures.Service;
  
  String localEmbedString =
          WebFigureServiceUtility.GetHTMLEmbedString(
                  "SessionStateWebFigure",
                  WebFigureAttachType.session,
                  300,
                  300);
  
  Response.Write(localEmbedString);

• Visual Basic:

  Imports MathWorks.MATLAB.NET.WebFigures.Service
  
  Dim localEmbedString As String = _
          WebFigureServiceUtility.GetHTMLEmbedString( _
                  "SessionStateWebFigure", _
                  WebFigureAttachType.session, _
                  300, _
                  300)
  	
  Response.Write(localEmbedString)		

Referencing a WebFigure Attached to a Remote Server.  

• C#:

  using MathWorks.MATLAB.NET.WebFigures.Service;
  
  String remoteEmbedString =
          WebFigureServiceUtility.GetHTMLEmbedString(
                  "SessionStateWebFigure",
                  "http://localhost:20309/WebSite7/",
                  WebFigureAttachType.session,
                  300,
                  300);
  
  Response.Write(remoteEmbedString);

• Visual Basic:

  Imports MathWorks.MATLAB.NET.WebFigures.Service
  
  Dim localEmbedString As String = _
          WebFigureServiceUtility.GetHTMLEmbedString( _
                  "SessionStateWebFigure", _
                  "http://localhost:20309/WebSite7/", _
                  WebFigureAttachType.session, _
                  300, _
                  300)
  
  Response.Write(localEmbedString)	

Improving Processing Times for JavaScript Using Minification

This application uses JavaScript to perform most of its AJAX functionality. Because JavaScript runs in the client browser, it must all be streamed to the client computer before it can execute. To improve this process, you use a standard JavaScript minification algorithm to remove comments and white space in the code. This feature is enabled by default. To disable it, create an environment variable called mathworks.webfigures.disableJSMin and set its value to true.

Using Global Assembly Cache (Global.asax) to Create WebFigures at Server Start-Up

In ASP.NET there is a special type of object you can add called a Global Assembly Cache, also known by the name Global.asax.

Global.asax classes have methods that are called at various times in the IIS life cycle, such as Application_Start and Application_End. These methods get called respectively when the server is first started and when the server is being shut down.

As seen in Quick Start Implementation of WebFigures, the default behavior for a WebFigureControl is to store data in the Session cache on the server. In other words, each user that accesses a page using a WebFigureControl has an individual instance of that WebFigure in the cache. This is useful if each user gets specific data, but resources can be wasted in situations where all users are accessing the same WebFigures.

Therefore, in order to maximize available resources, it makes sense to move WebFigure code for commonly used figures into the Application_Start method of the Global.asax. In the following example, code written in the Web page initialization section of Attaching a WebFigure is moved into a Global.asax method as follows:

 C#

void Application_Start(object sender, EventArgs e) 
{ 
    // Code that runs on application startup 
    MyComponentclass myDeployedComponent = 
        new MyComponentclass(); 

    Application["ApplicationStateWebFigure"] = 
        new WebFigure(myDeployedComponent.getKnot()); 

    //Or 

    Cache["CacheStateWebFigure"] = 
        new WebFigure(myDeployedComponent.getKnot()); 
} 

 Visual Basic

Sub Application_Start
           (ByVal sender As Object, ByVal e As EventArgs) 
        ' Code that runs on application startup 
        Dim myDeployedComponent As _ 
            New MyComponentclass() 


        Application("ApplicationStateWebFigure") = _ 
            New WebFigure(myDeployedComponent.getKnot()) 

        'Or 

        Cache("CacheStateWebFigure") = _ 
            New WebFigure(myDeployedComponent.getKnot()) 
    End Sub 

Note   In this scenario, notice a WebFigure is not bound to the Session, since you usually need to share the WebFigures across different sessions. However, it may be useful to use the Cache option, since it provides a way to specify Time To Live so the WebFigure can be regenerated and reattached at a specific time interval. Once the figure is attached to a cache, reference it either from the WebFigureControl as seen in Setting Up WebFigureControl for Remote Invocation or directly from the Web page as in Getting an Embeddable String That References a WebFigure Attached to a WebFigureService.

Back to Top

Upgrading Your WebFigures

If you want to upgrade your version of MATLAB Builder NE and retain WebFigures created with a prior product release, do the following:

1. Delete the WebFigureControl icon from the toolbox.

2. Delete any WebFigures from your page.

3. Upgrade your version of MATLAB Builder NE .

4. Add the new WebFigureControl icon to the toolbox.

5. Drag new WebFigures on to your page.

Back to Top

Troubleshooting

Use the following section to diagnose error conditions encountered when implementing WebFigures for the .NET feature.

In WebFigures, there are two ways to display errors: by turning debug on for the site, and by turning it off. When debug is turned on, some error messages contain links to HTML pages that describe how the problem might be solved. When it is turned off, only the error message is shown.

Common causes of errors include:

• MCR is not installed or is the wrong version (meaning MWArray.dll is the wrong version or WebFigureService.dll is the wrong version).

• Deployed component is a different version than that compatible with the MCR.

• Incorrect framework is being used (only .NET 2.0 Framework is supported as of R2008b for WebFigures).

• WebFigureService is not installed. See Manually Installing WebFigureService.

• WebFigure is not attached to WebFigureService. See Attaching a WebFigure.

• Remote root URL is pointing to an invalid server.

Common errors and their diagnosis follow.

Back to Top

Logging Levels

There are several logging levels that can be used to diagnose problems with WebFigures.

You can manually set the log level by setting an environment variable called mathworks.webfigures.logLevel to one of the above strings.

If you set this environment variable to something other than the above strings or it is not set, it defaults to a level of Warning or Severe only.

By default, all exceptions are shown within the WebFigure control on the Web page when debug mode is on for the site.

If you want more detailed logging information, or log information when debug is not on, set an environment variable called mathworks.webfigures.logLocation to the location where the log file is written. The log file is named yourwebappnameWFSLog.txt.

Back to Top

Web Deployment of Figures and Images

Creating and Modifying a MATLAB Figure

Recommended Products

• MATLAB
• Signal Processing Toolbox
• Optimization Toolbox
• Statistics Toolbox
• Control System Toolbox

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit