Search

Edition: Futurama Webservice

Module: Futurama Webservice

User: Front-end developer

Prerequisites:

  • Knowledge of a programming language.
  • Knowledge of Webservices.
  • Knowledge of Session states and cookie management.
 

Description

This document will explain how to create a front-end plugin to access a Futurama back-end server using WebAPI

Introduction

In order to offer Futurama functionality within your application, we have created this development guide, in which we will try to assist you as much as possible. For this reason we have created a sample application in Visual Studio 2012, which you can use to recreate your own functionality.

Preparation

In order to develop a WebAPI front-end, the following requirements must be met:

  • You should have access to a webserver with the Futurama Webservice installed on this server, which will function as the back-end. Its URL will from now on be referenced to as {FuturamaURL}.
  • Place the folder with the Futurama application you wish to (re)use into the hosted webservice folder on the back-end server.
  • WebAPI must be enabled in the web.config file. The required changes are documented here.
  • (optional) Set the mapping section in the web.config to point to the desired folder/document like you would do within Futurama Website (see here).

The WebAPI's WSDL should now be accessible through the relative path {FuturamaURL}/WebAPIService.svc?wsdl on the back-end server.

The sample application

We have created a small sample application that can be examined using Microsoft Visual Studio 2012 or later, or possibly within a text editor. It contains a Basic page (BasicSample.ashx), and an Advanced page (AdvancedSample.ashx), which allows a degree of incremental understanding of the implementation method. The basic sample is able to connect to a back-end, and retrieve the default page (set in the back-end configuration). It loads a HTML form containing the entire page, and allows this form to be submitted, so that any changes actuates an update in the loaded document.

The WebAPI service

When the preparation phase has been completed, the back-end should be completely functional. Now it's up to you to create a functional front-end. First we will look at the webservice method 'GetPage' that will return the HTML code of a Futurama Page, which is accessed through the {FuturamaURL}/WebAPIService.svc URL. A typical request for this method looks like this:


   
   
     
         myForm
         AppName
         calc.xml
         
            3
            4
         
         
            
               __EVENTTARGET
               15
            
            
               __EVENTARGUMENT
               Hello world
            
         
      
   

In this example, it can be seen that the method GetPage has five input arguments:

  • formName: Specifies the name of the generated form element in which all rendered Futurama objects are contained. The rendered HTML elements will contain an ID attribute which will correspond to the ID of a Futurama object. For instance, if a Button shows its ID as 23 within the Futurama Editor, then it can will be rendered within this example as 'id_myForm_23'.
  • folder (optional): The name of the folder that contains the Futurama applications XML file. If this value is not provided here, it must be defined within the WebAPI configuration section in the back-end web.config.
  • document (optional): The filename of the Futurama application. This can also be configured within the the WebAPI configuration section in the back-end web.config.
  • panelIDs (optional): This argument contains a list of WebPanel objects to retrieve. If this argument is not provided, the complete starting page of the Futurama application will be retrieved. A list of WebPanels can be provided to only get those specific parts of a WebPage. If a specific page is desired, it's ID can be entered here as well, just as if it is a WebPanel to retrieve.
  • Parameters (optional): This argument contains a list of key/value pairs that can be used to update the current state of the Futurama application, after which the updated state is rendered and returned to the caller. Whenever the returned HTML form is directly placed within the front-end HTML code, any postback within that form will be posted to the front-end server. It is possible to collect the list of form-variables, and reshape them as a list of key/value pairs. This list can be used as parameters, so that the call to GetPage will update the back-end with any changes within the form, and return updated HTML code of that same form.

Finally the returning data consists of a Response object, that contains the following fields:

  • HtmlSource: The HTML source code of any rendered objects, wrapped within a generated form element.
  • ScriptReferences: A list of script elements that need to be included within the front-end page in order to facilitate all functionality within the returned HTML code.
  • Errors: A list of occurred error descriptions (if any).

Maintaining session

The Futurama document and objects that a user is retrieving and updating is maintained in a session object within the Back-end server. This is needed to maintain the current document state between user postbacks. By introducing a front-end between the users browser and the Futurama back-end this became a little more involved.

When the front-end calls the back-ends WebAPI service, it will return the requested data, but will also contain a cookie containing the SessionID for the back-end with the name 'ASP.NET_SessionId'. It is up to the front-end to maintain this sessionID/cookie for the current user, and re-use it for every returning call to that same document.

Using the WebAPI resource proxy

Because the WebAPI renders its Futurama objects to HTML code, it will often create elements that rely on external resources, such as an image element that links to a file located on the back-end server. However, the back-end server is not reachable from the clients browser, so the image cannot be retrieved, and a broken link will occur. The solution we developed works like this: In all the generated HTML, WebAPI searches for elements containing the 'src' attribute, and that link is checked whether it is a relative link. When this occurs, the link is replaced with a generated link that can be configured in the WebAPI configuration section on the back-end servers web.config file. This generated link will need to contain an encrypted resource identifier and a session ID. This allows the front-end proxy to contain an encrypted querystring, and should point to an address on the front-end server. It's up to the front-end developer to create a system at this address that can accept the request, and pass-on the encrypted querystring to the back-end address {FuturamaURL}/FutResource.ashx. The returning data contains the requested resource, and should be passed on back to the clients browser.

If the hosting environment for your application supports ASP.NET, we advise you to reuse the proxy.ashx file from the sample for your own purposes.

The generated link will also contain a 'sid' parameter, which contains the sessionID to re-use when calling the back-end. The created request for the resource should include a cookie containing the name 'ASP.NET_SessionId', and the sessionID as value.

 

The sample

The sample consists mainly of the following files:

  • Service references: This contains the proxy that is able to communicate with the WebAPI webservice, and is generated out of the WSDL that is exposed from the WebAPI URL.
  • index.html: A simple start page.
  • Basic.ashx.cs: A simple HTTP handler that acts as a page, by reading a request, and returning HTML that includes the reponse from the configured Futurama (using the folder/document that is configured within the back-end web.config).
  • Advanced.ashx.cs: A HTTP handler that contains the advanced sample. Here you can override the WebAPI request by defining folder, document and panelID's that need to be retrieved from the back-end.
  • proxy.ashx.cs: The proxy HTTP handler that passes the Futurama Resource calls from the client to the back-end, and back again.

Related Topics

- WebAPI overview: An overview of the Futurama WebAPI system

- WebAPI configuration: How to configure the Futurama WebAPI system

Feedback

If you have any questions about this subject or if you want to provide us feedback please send us an e-mail.

Updated: 2014-02-04