Documentation

HDPage

The HDPage object represents a page of your web application. Using the object's properties, you can set visual attributes such as background color and the default font, as well as define events that are called when the page is loaded or the device is rotated.

// set the page title
page1.title = "The new page title";

// change the page background color, saving the old color
var oldBackgroundColor = page1.backgroundColor;
page1.backgroundColor = "white";

// Change the value of label1 when the device orientation changes.
page1.onOrientationChange = function(event) {
	if(page1.orientation == 0)
	{
		label1.value = "Portrait";
	}
	else
	{
		label1.value = "Landscape";
	}
};

Regardless of the page's ID, you can always reference the current page using the "page" variable.

// assuming the page ID is "testPage", 
// change the backgroundColor property:
testPage.backgroundColor = "white";

// but, this also works:
page.backgroundColor = "white";

View full object documentation on HandheldDesigner.com.

Object Properties & Methods

Background
 backgroundAttachmentDetermines whether the background scrolls with the page, or remains fixed.
 backgroundColorThe background color of the object.
 backgroundGradientThe background gradient of the object.
 backgroundImageThe background image of the object.
 backgroundPositionDetermines the starting position of the background image.
 backgroundRepeatSets how the background image will be repeated.
 colorThe default color of the objects added to the page.
 cssIncludesList of URLs of additional CSS files to be included on page.
 domElementMethod that returns the HTML DOM element associated with the HD object
Events
 onClickEvent that occurs when the object is tapped/clicked.
 onLoadEvent that occurs when the page document is fully loaded and ready.
 onOrientationChangeEvent that occurs when the device is rotated.
 onSubmitEvent that occurs when the page's form is submitted.
 onTouchEndEvent that occurs at the end of a touch event.
 onTouchMoveEvent that occurs during a touch event when the touch point moves.
 onTouchStartEvent that occurs when the object is touched.
Font & Text
 fontFamilyThe font family used to render the text associated with object.
 fontSizeThe font size used to render the text associated with object.
 fontStyleThe font style used to render the text associated with object.
 fontWeightThe font weight used to render the text associated with object.
 letterSpacingIncrease or decrease the amount of space between characters.
 lineHeightIncrease or decrease the amount of space between lines of text.
 textAlignThe font style used to render the text associated with object.
 textShadowDefines a shadow displayed behind the text.
 formThe form data returned by the server.
 formActionThe URL to which the form will be submitted
 formMethodThe HTTP method used to submit the form
 heightThe height of the page, measured in pixels.
 idThe object's unique identifier. Also used as the variable name in code.
 javascriptIncludesList of URLs of additional JavaScript source files to be included in page.
 loadingDisplay the "loading" spinner.
 objectByIDReturns the Handheld Designer object associated with an ID string.
 parametersParameters in the page's URL
Server Events
 onGET
 onPOST
 submitFormSubmit the form on the page to the server
 themeThe jQuery Mobile theme used by the page
 titleThe page's title
 userdataAn object for storing user data.
 widthThe width of the page, measured in pixels.

backgroundAttachment

PropertyFirst available in version 1.0.0

Determines whether the background scrolls with the page, or remains fixed. Can have one of the following values:

"scroll" (or empty)Background scrolls with the page.
"fixed"Background is fixed and does not scroll with the page.

Example:

// Set the background to fixed and not scroll with the page.
object1.backgroundAttachment = "fixed"; 

backgroundColor

PropertyFirst available in version 1.0.0

The background color of the object. Colors can be specified as:

  • by name: "red", "blue", "green"
  • by hex format: "#c0c0a0"
  • by red/green/blue values: "rgb(12,34,56)"

Example:

// get the background color of object1
var c = object1.backgroundColor;

// set the color of object1 to grey
object1.backgroundColor = "grey"; 

backgroundGradient

PropertyFirst available in version 1.0.0

The background gradient of the object. Can set to a string, using the CSS3 linear gradient syntax.

The HDGradient class provides an easy way to construct gradients. In addition, the HDGradient class allows you to construct more complex gradients, including radial and repeating gradients.

Note: when setting a background gradient on an HDPage object, you almost certainly want to set the backgroundAttachment property to "fixed". Otherwise your gradient will probably not be displayed correctly.

Example:

// set the background gradient of object1
// using CSS3 linear gradient syntax:
o1.backgroundGradient = "90deg, #00ABEB, blue 50%, red";

// same gradient, using HDGradient:
var g = new HDGradient();
g.angle = "90";
g.addStop("#00ABEB");
g.addStop("blue", "50%");
g.addStop("red");
o1.backgroundGradient = g;

backgroundImage

PropertyFirst available in version 1.0.0

The background image of the object.

Example:

// set the background image of object1
object1.backgroundImage = "images/background-image-1.png"; 

backgroundPosition

PropertyFirst available in version 1.0.0

Determines the starting position of the background image. Can be specified using one of the following forms:

KeywordsA keyword specifying horizontal position (left/center/right) and one for vertical (top/center/bottom). For example: "left bottom".
PercentageHorizontal position, then vertical position, expressed as percentages. For example: "25% 50%".
PixelHorizontal position, then vertical position, expressed as number of pixels. For example: "30px 50px".

Example:

// Position the background centered on the page
object1.backgroundPosition = "center center"; 

backgroundRepeat

PropertyFirst available in version 1.0.0

Sets how the background image will be repeated. Can have one of the following values:

"repeat" (or empty)Repeated both vertically and horizontally.
"repeat-x"Repeated horizontally.
"repeat-y"Repeated vertically.
"no-repeat"Not repeated.

Example:

// Set the background to only repeat horizontally.
object1.backgroundRepeat = "repeat-x"; 

color

PropertyFirst available in version 1.0.0

The default color of the objects added to the page. Colors can be specified in a number of ways:

  • by name: "red", "blue", "green"
  • by hex format: "#c0c0a0"
  • by red/green/blue values: "rgb(12,34,56)"

Example:

// get the color of object1
var c = object1.color;

// set the color of object1 to red
object1.color = "red"; 

// set the color of object1 to red
object1.color = "#ff0000";

// set the color of object1 to red
object1.color = "rgb(255,0,0)";

cssIncludes

PropertyFirst available in version 1.0.0

List of URLs of additional CSS files to be included on page. These are in addition to any project-wide CSS include files defined in the project settings.

Note: This property is not available at runtime and can only be defined within the Handheld Designer application. In addition, setting this property at the page level is not supported when using AJAX page loading. Set any required CSS includes at the project level.

domElement

MethodFirst available in version 1.0.0

Method that returns the HTML DOM element associated with the HD object.

Example:

// Get the object's DOM element
var element = object1.domElement();

onClick

EventFirst available in version 1.0.0

Event that occurs when the object is tapped/clicked. The property is set by selecting an HDFunction object within Handheld Designer, or defined at runtime.

In code, the property can be set to reference an existing function:

object1.onClick = someExistingFunction;

Or, you can define an anonymous function containing the code to be executed by the event:

object1.onClick = function(event) {
	// this code will be executed when the event is triggered
	object2.value = "The event was triggered";
};

onLoad

EventFirst available in version 1.0.0

Event that occurs when the page document is fully loaded and ready. Code in this event can safely initialize or modify other objects or properties.

Note: This property is not available at runtime and can only be defined within the Handheld Designer application.

onOrientationChange

EventFirst available in version 1.0.0

Event that occurs when the device is rotated. You can retrieve the current device orientation from the .orientation property.

In code, the property can be set to reference an existing function:

// Call someExistingFunction when the device orientation changes 
page1.onOrientationChange = someExistingFunction;

Or, you can define an anonymous function containing the code to be executed by the event:

// Change the value of label1 when the device orientation changes.
page1.onOrientationChange = function(event) {
	if(page1.orientation == 0)
	{
		label1.value = "Portrait";
	}
	else
	{
		label1.value = "Landscape";
	}
};

onSubmit

EventFirst available in version 1.0.0

Event that occurs when the page's form is submitted. You can cancel the submission of the form by returning false from the handler.

In code, he property can be set to reference an existing function:

// Call someExistingFunction when the form is submitted
page1.onSubmit = someExistingFunction;

Or, you can define an anonymous function containing the code to be executed by the event:

// If the checkbox1 is checked, cancel the form submission.
page1.onSubmit = function(event) {
	if(checkbox1.checked == true)
	{
		// cancel form submission
		return false;
	}
};

onTouchEnd

EventFirst available in version 1.0.0

Event that occurs at the end of a touch event. The property is set by selecting an HDFunction object within Handheld Designer, or defined at runtime.

In code, the property can be set to reference an existing function:

object1.onTouchEnd = someExistingFunction;

Or, you can define an anonymous function containing the code to be executed by the event:

object1.onTouchEnd = function(event) {
	// this code will be executed when the event is triggered
	object2.value = "The event was triggered";
};

Note: In most cases, the onClick event is simpler and more reliable then the lower-level touch-based events (onTouchStart, onTouchMove, and onTouchEnd). However, the touch-based can be used if you need immediate access to each touch event.

Event Properties

The event parameter passed to the onTouchEnd event has the following key properties:

  • touches: An array of "touch" objects, one for each finger touching the screen.
  • targetTouches: An array of "touch" objects, one for each finger touching the object.
  • changedTouches: An array of "touch" objects, one for each finger involved in the current event.

Each "touch" object contains the following properties:

  • identifier: A unique identification number for the touch point.
  • screenX: The horizontal coordinate of point relative to the screen, in pixels.
  • screenY: The vertical coordinate of point relative to the screen in pixels.
  • pageX: The horizontal coordinate of point relative to the viewport in pixels, including any scroll offset.
  • pageY: The vertical coordinate of point relative to the viewport in pixels, including any scroll offset.
  • clientX: The horizontal coordinate of point relative to the viewport in pixels, excluding any scroll offset.
  • clientY: The vertical coordinate of point relative to the viewport in pixels, excluding any scroll offset.

Example:

object1.onTouchEnd = function(event) {
	// display the touch coordinates in a label
	var touch = event.targetTouches[0];
	label1.value = "Loc: " + touch.pageX + ", " + touch.pageY;
};

onTouchMove

EventFirst available in version 1.0.0

Event that occurs during a touch event when the touch point moves. The property is set by selecting an HDFunction object within Handheld Designer, or defined at runtime.

In code, the property can be set to reference an existing function:

object1.onTouchMove = someExistingFunction;

Or, you can define an anonymous function containing the code to be executed by the event:

object1.onTouchMove = function(event) {
	// this code will be executed when the event is triggered
	object2.value = "The event was triggered";
};

Note: In most cases, the onClick event is simpler and more reliable then the lower-level touch-based events (onTouchStart, onTouchMove, and onTouchEnd). However, the touch-based can be used if you need immediate access to each touch event.

Event Properties

The event parameter passed to the onTouchMove event has the following key properties:

  • touches: An array of "touch" objects, one for each finger touching the screen.
  • targetTouches: An array of "touch" objects, one for each finger touching the object.
  • changedTouches: An array of "touch" objects, one for each finger involved in the current event.

Each "touch" object contains the following properties:

  • identifier: A unique identification number for the touch point.
  • screenX: The horizontal coordinate of point relative to the screen, in pixels.
  • screenY: The vertical coordinate of point relative to the screen in pixels.
  • pageX: The horizontal coordinate of point relative to the viewport in pixels, including any scroll offset.
  • pageY: The vertical coordinate of point relative to the viewport in pixels, including any scroll offset.
  • clientX: The horizontal coordinate of point relative to the viewport in pixels, excluding any scroll offset.
  • clientY: The vertical coordinate of point relative to the viewport in pixels, excluding any scroll offset.

Example:

object1.onTouchMove = function(event) {
	// display the touch coordinates in a label
	var touch = event.targetTouches[0];
	label1.value = "Loc: " + touch.pageX + ", " + touch.pageY;
};

onTouchStart

EventFirst available in version 1.0.0

Event that occurs when the object is touched. The property is set by selecting an HDFunction object within Handheld Designer, or defined at runtime.

In code, the property can be set to reference an existing function:

object1.onTouchStart = someExistingFunction;

Or, you can define an anonymous function containing the code to be executed by the event:

object1.onTouchStart = function(event) {
	// this code will be executed when the event is triggered
	object2.value = "The event was triggered";
};

Note: In most cases, the onClick event is simpler and more reliable then the lower-level touch-based events (onTouchStart, onTouchMove, and onTouchEnd). However, the touch-based can be used if you need immediate access to each touch event.

Event Properties

The event parameter passed to the onTouchStart event has the following key properties:

  • touches: An array of "touch" objects, one for each finger touching the screen.
  • targetTouches: An array of "touch" objects, one for each finger touching the object.
  • changedTouches: An array of "touch" objects, one for each finger involved in the current event.

Each "touch" object contains the following properties:

  • identifier: A unique identification number for the touch point.
  • screenX: The horizontal coordinate of point relative to the screen, in pixels.
  • screenY: The vertical coordinate of point relative to the screen in pixels.
  • pageX: The horizontal coordinate of point relative to the viewport in pixels, including any scroll offset.
  • pageY: The vertical coordinate of point relative to the viewport in pixels, including any scroll offset.
  • clientX: The horizontal coordinate of point relative to the viewport in pixels, excluding any scroll offset.
  • clientY: The vertical coordinate of point relative to the viewport in pixels, excluding any scroll offset.

Example:

object1.onTouchStart = function(event) {
	// display the touch coordinates in a label
	var touch = event.targetTouches[0];
	label1.value = "Loc: " + touch.pageX + ", " + touch.pageY;
};

fontFamily

PropertyFirst available in version 1.0.0

The font family used to render the text associated with object. Can be a generic family ("serif", "sans-serif") or a specific font family ("Helvetica", "Times New Roman").

Example:

// get the font family property of object1
var f = object1.fontFamily;

// Set the font family of object1 to Helvetica Neue
object1.fontFamily = "Helvetica Neue";

fontSize

PropertyFirst available in version 1.0.0

The font size used to render the text associated with object, in pixels.

Example:

// get the fontSize property of object1
var f = object1.fontSize;

// Set the font size of object1 to 12
object1.fontSize = 12;

fontStyle

PropertyFirst available in version 1.0.0

The font style used to render the text associated with object. Property value can be:

"normal" (or blank)Normal text style
"italic"Italic text style
"oblique"Oblique text style

Example:

// get the fontStyle property of object1
var f = object1.fontStyle;

// Set the font style of object1 to "italic"
object1.fontStyle = "italic";

fontWeight

PropertyFirst available in version 1.0.0

The font weight used to render the text associated with object. Property value can be:

"normal" (or blank)Normal font weight
"bold"Bold font weight
"bolder"Bolder font weight
"lighter"Lighter font weight

Example:

// get the fontWeight property of object1
var f = object1.fontWeight;

// Set the font weight of object1 to "bold"
object1.fontWeight = "bold";

letterSpacing

PropertyFirst available in version 1.0.0

The letterSpacing property increases or decreases the amount of space between characters.

Example:

// add one additional pixel between characters
object1.letterSpacing = 1;

lineHeight

PropertyFirst available in version 1.0.0

Increase or decrease the amount of space between lines of text. Can be specified in the following forms:

"normal" (or empty)The default line height.
"number"Multiple (or fraction) of the current font size.
"numberpx"Line height in pixels.
"number%"Percentage of current font size.

Example:

// set the line height to 120% of the current font size
object1.lineHeight = "120%";

textAlign

PropertyFirst available in version 1.0.0

The text alignment used to display the text associated with object. Property value can be:

"left" (or blank)Aligns text with the left edge of the object.
"right"Aligns text with the right edge of the object.
"center"Centers the text in the object.
"justify"Full justification; adjusts the text so each line takes the full width of the object.

Example:

// get the textAlign property of object1
var a = object1.textAlign;

// Set the text alignment of object1 to "center"
object1.textAlign = "center";

textShadow

PropertyFirst available in version 1.0.0

Defines a shadow displayed behind the text. You can define the color of the shadow, the x-axis and y-axis offsets, and the shadow's blur radius.

The text shadow is defined using CSS text-shadow syntax:

shadow-color x-axis-offset y-axis-offset blur-radius

For example, the value: "#cccccc 1px 1px 2px" defines a text shadow with color #cccccc, a 1-pixel offset on both the x- and y-axis, and a 2-pixel blur radius.

Code Example:

// get the textShadow property of object1
var a = object1.textShadow;

// Set the text shadow of object1
object1.textShadow = "#cccccc 1px 1px 2px";

form

PropertyFirst available in version 1.0.0

The form data returned by the server.

If a server function (i.e. onGET or onPOST) sets a value in the response.form object, that value will be present in the page's "form" property.

Example:

// in the server's onPOST function:
response.form.calculationResult = 42;

// In a client function:
var result = page.form.calculationResult;

formAction

PropertyFirst available in version 1.0.0

The location to which this page's form will be submitted. If this property is not provided, the form will be submitted to this page's URL.

You can set this property to an arbitrary URL, or use a page ID from a HDPage defined in your project.

Example:

// submit the form to "searchPage" defined in this project
page1.formAction = "searchPage";

// set the form action to another URL
page1.formAction = "http://google.com/search";

When setting this property to an HD page name, remember you are setting it to the name of another page, and not a page variable. (i.e. set it to a literal string rather than a page variable.)

// Wrong. searchPage is not a valid variable in page1.
page1.formAction = searchPage;

// Right. 
page1.formAction = "searchPage";

formMethod

PropertyFirst available in version 1.0.0

The HTTP method used to submit the form. If this property is not provided, the HTTP GET method will be used.

Example:

// set the form method to POST
page1.formMethod = "POST";

height

PropertyFirst available in version 1.0.0

A read-only property returning the height of the page, in pixels.

Example:

// get the height of the page
var w = page1.height;

id

PropertyFirst available in version 1.0.0

The object's unique identifier. Also used as the variable name in code.

Example:

// get height of object with the id "object1".
var h = object1.height;

javascriptIncludes

PropertyFirst available in version 1.0.0

List of URLs of additional JavaScript source files to be included in page. These are in addition to any project-wide JavaScript include files defined in the project settings.

Note: This property is not available at runtime and can only be defined within the Handheld Designer application. In addition, setting this property at the page level is not supported when using AJAX page loading. Set any required JavaScript includes at the project level.

loading

MethodFirst available in version 1.4.0

Method to display (or hide) the "loading" animated spinner. This can be useful to indicate to the user that some action is in progress. (Executing an AJAX call, for example.)

Usage:

page.loading(action);

Arguments:

actionEither the string "show" to show the spinner, or "hide" to hide it.

Example:

// Show the spinner
page.loading("show");

objectByID

PropertyFirst available in version 1.0.0

Returns the Handheld Designer object associated with an ID string.

Example:

// Assuming a page has an object "searchField", get a reference to the object:
var field = page1.objectByID("searchField");

parameters

PropertyFirst available in version 1.0.0

Parameters in the page's URL, returned as a JavaScript object.

Example:

// Getting the value of the "item" parameter
var item = page.parameters.item;

onGET

Server EventFirst available in version 1.0.0

The onGET event handler is executed on the server when the page is requested by the client using the HTTP GET method. (The HTTP GET method is the method typically used when a user navigates to a page, versus the HTTP POST method, typically used when a user submits a form.)

Note: This property is not available at runtime and can only be defined within the Handheld Designer application.

Example:

// initialize the textbox1 value
response.form["textbox1"] = "A default string value";

onPOST

Server EventFirst available in version 1.0.0

The onPOST event handler is executed on the server when the page is requested by the client using the HTTP POST method. (The HTTP POST method is the method typically used when a user submits a form, and is determined by the value of the HDPage.formMethod property.)

Note: This property is not available at runtime and can only be defined within the Handheld Designer application.

Example:

// get the value of the textbox1 form object
var theValue = request.form["textbox1"];

submitForm

MethodFirst available in version 1.0.0

Submit the form on the page to the server. The HTTP method used to submit the form is defined by the formMethod property. Use the formAction property to define the URL to which the form will be submitted.

Usage:

page.submitForm();

Example:

// submit the form of page1
page1.submitForm();

theme

PropertyFirst available in version 1.4.0

The color scheme used by the page. The specific colors used are defined by the jQuery Mobile theme used by your application. If you are using the default theme, values "a" through "e" are defined.

This property is not available at run-time.

title

PropertyFirst available in version 1.0.0

The page's title.

Example:

// Setting the page title.
page1.title = "The Page Title";

userdata

PropertyFirst available in version 1.0.0

An JavaScript object for storing user data. You can use this property to store data for later use. (For example, to share data between event handlers.)

Example:

// track the number of times a button is clicked:
function button1_onClick(event) {
	if(button1.userdata.timesClicked === undefined)
	{
		button1.userdata.timesClicked = 0;
	}
	else
	{
		button1.userdata.timesClicked++;
	}
}

width

PropertyFirst available in version 1.0.0

A read-only property returning the width of the page, in pixels.

Example:

// get the width of the page
var w = page1.width;

Copyright © 2010-2017, Handheld Designer, LLC, All Rights Reserved.
Made by hand in New England, USA.