Search

 

User: Developer

Prerequisites

  • Intimate knowledge of XSL transformations.
  • Experience in changing Futurama markup.
  • Knowledge of basic HTML and HTTP website behavior.

Introduction

This document will extend the possibilities of changing the way a Futurama WebControl returns its value (within the browser) to the server where Futurama is installed.

 

Description

At the Futurama Intermediate Control Output page is explained how to use a XSLT in order to create customized XSLT. When the alteration of the Futurama HTML output is taken beyond a simple HTML-markup change, and the values of these controls are altered by the user, it might be of use how Futuama deals with postbacks. In this page is explained how the input of a Futurama webcontrol is returned back to the server where Futurama is installed.

Overview

Whenever a webpage is changed by the user, or some other client-side process within the browser, then the changed information must be returned to the Futurama server to cause any changes within the Futurama document. This is done in a regular HTTP Post message like it would in any other website. The changed information must be provided in the form collection. An example to make this clear.

How the FICO of FileUploader is transformed into HTML code for a customized visual style

The FileUploader uses an HTML element input with its type “file”, which has a fixed user experience in current webbrowsers. Suppose you would like to change this look to a button with an icon, but regular CSS styling will not allow this. So how does Futurama achieve this? It creates an img element with the icon that the user can click on, but at the same time an invisible file-input element floats in front of this image, so when the user clicks on the image, it is actually clicking on the invisible file input. When a file has been selected, the data that is sent back at the postback must be connected to the correct webcontrol. This is be done within Futurama by making sure that the file-input has a name attribute containing the ID of the webcontrol in question. This ensures that a submitted form will send the selected filename to the Futurama server, and that it can find the WebControl that must handle this returned data.

Default behavior

The default expected postback behavior of Futurama WebControls is as follows:

If a rendered and enabled WebControl contains a value, then a submitted html form (postback) must contain a field with name “id13”, and the contents of the WebControl as its value. The simplest example is a TextBox with an ID of ‘13’, and the value ‘Hello World’. Should this page be submitted to Futurama by a buttonclick, then a parameter is expected that has the following name/value pair: {name=’id13’, value=’Hello World’}.

Take note that whenever a Futurama WebControl ID is used, then it is prefixed with the term ‘id’.

The postbacktarget

Whenever a postback is performed, another two fields are added to the postback form collection (please note the two underscore characters in front of the name):

  • __EVENTTARGET: This contains the ID of the webcontrol that caused the postback. For instance, if a user entered some values in various textboxes (that have their autopostback set to ‘false’), and consequently clicks on a submit button, then the button is the eventtarget.
  • __EVENTARGUMENT: This field is only used for a Textbox with its postbackOnEnter property set to ‘true’.

Partial “AJAX” Postbacks

For a partial postback when only part of a page is re-rendered, there is a slightly different way to indicate the postbacktarget:

  • triggercontrol: This field replaces the ‘__EVENTTARGET’ field, but has the same function. It contains the ID of the Webcontrol responsible for the postback (for example: ‘id13’).
  • __EVENTARGUMENT: This field is not changed compared with a normal postback.
  • panelToUpdate: This is a new field, which contains the ID for the webpanel to update and retrieve with this postback. It should be in the form of “id36” for a panel with ID set to ‘36’.
  • idprefix: This field should be filled with the value of the idPrefix property of the webcontrol causing the postback (postbacktarget).

Postback-capable webcontrols and their behavior

Button

A button can cause a postback, but it cannot transmit any data, because it contains no user-defined information. So it can only be mentioned as a postbacktarget.

CheckBox

When a checkbox is submitted to Futurama, it expects its value to be formed in this way:

Name: id

Value: "on" means checked, any other value means NOT checked.

DateBox

The value of a datebox must be submitted in a parameter where the name contains the id.

The value must be formatted in the 'yyyy-MM-dd' pattern, meaning that the date 10th of september 2015 must be formatted as '2015-09-10'.

DropDownList

The value of a DropDownList is stored in a parameter with the id for a name, and the value must be set to the selected index, where the index for the first element is '0'.

FileUploader

The fileuploader does not use any posted parameter, but requires that the HTTP post has its content-type set to "multipart/form-data", and and the accompanied structure for attaching files according to the HTTP specification.

The easiest way to achieve this, is by using a HTML input element with its type attribute set to "file", and making sure that it contains the path to the users desired file.

RadioButton

The selected radiobutton is set in a similar way to a checkbox, namely by setting a parameter with the name set to the id of the radiobutton, and setting the value to 'checked' if it is checked.

Should the radiobutton also be part of a radiobutton group, then a parameter must also be set with its name set to the id of the radiobutton's group id, and the value to the id of the selected radiobutton within that group.

So if a group with id=13 has a radiobutton with id=14 and a radiobutton with id=15, and the second radiobutton is checked, then a parameter must be present where name is set to 'id13', and the value to 'id15'.

TextBox

The TextBox has a very simple functionality, namely a single posted parameter where the name is set to the ID of the TextBox, and the value to the contents of the TextBox.

Should the textbox contain a value different than a string datatype, then it is converted using the configured culture within Futurama. So if the culture is set to 'United States' (en-US), then a double number must have a decimal point ('.'), while the date value of Februari 1st of 2001 should be formatted as '2/1/2001'. If this is done correctly, then Futurama will convert these values from its text representation to the specified datatype.

Should the textbox be set to “postbackOnEnter”, then the usage of the Enter key must be triggered by setting this textbox as the postbacktarget (see above), and setting the __EVENTARGUMENT parameter to the value ‘OnKeyEnter’. This signals Futurama that the postback was caused by an enter-key.

WebSlider

The WebSlider uses a parameter with the name set to the Webslider ID, and the value must be a decimal, where any decimal point is denoted by a '.' sign. So a value of three-and-a-half is '3.5'.

Extra parameters

There are some extra parameters that can be provided with a postback procedure:

  • WID: This parameter should contain the window in which the postback is triggered. The value is 0-based, so the first window is ‘0’, and the second windows would be ‘1’, and so on.

Related Topics

- Futurama Intermediate Control Output: Shows how to change the markup of Futurama Webcontrols.

Feedback

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

Updated: 2016-07-29