Item class

From PhiWiki
Jump to: navigation, search

Describes the settings for an element in a Web- or Intranet document. You can change i.e. colors, opacity, values, positions, transformations, etc. (through the Style class) of an item. Effects on items may be set with the Effect class.

Usage

The Item class has many additional functions in the server environment and Phi native mode which are not available in HTML so they will be ignored if you use them in HTML mode. Those functions are marked with Phi.

Since v1.3.0 we recommend to use the wrapper class for the client environment which provides a clean programming interface which is transparently usable in both modes.

You reference an element by its id (the ID you set in the Aphilo editor):

var item1=phi.getElementById( 'id' ); // prefered version for the client environment
var item2=window.document.getElementById( 'id' ); // client environment
var item3=document.getElementById( 'id' ); // client environment v1.3.0
$('item4'); // wrapper - client environment v1.3.0
var item=document.getElementById( 'id' ); // server environment

Additional properties are also available through the item sub classes Style class and Effect class.

Note: some settings make only sense to be set in the server scripting environment.

Properties

  • String accessKey [read|write] Phi
  • Boolean checked [read|write]
  • String delimiter [read|write] Phi
  • Boolean disabled [read|write]
  • Number fadeInterval [read|write] Phi
  • Number fadeTime [read|write] Phi
  • String imageId [read|write] Phi
  • String label [read|write] Phi
  • Number maxLength [read|write] Phi
  • String name [read]
  • String parentName [read|write] Phi
  • StringArray pictureBookIds [read|write] Phi
  • StringArray properties [read] Phi
  • Boolean readOnly [read|write]
  • String styleSheet [read|write] Phi
  • Number tabIndex [read|write] Phi
  • String title [read|write] Phi
  • Number type [read] Phi
  • String url [read|write] Phi

All properties can be set and read (replace <prop_name> with one of the above property names) with:

var item=document.getElementById( 'id' ); // server
var item=phi.getElementById( 'id' ); // client
var prop=item.<prop_name>;
item.<prop_name>=value;

String accessKey

Single char access key available in all input items. Mostly accessible in the browsers with Alt+Shift+Key or Ctrl+Shift+Key. The control keys are dependent of the browser and can not be changed.

item.accessKey='S'; // item becomes activated by pressing control keys and 'S'

Boolean checked

Only available in radio buttons and checkboxes.

if ( mycheck.checked ) doSomething();

String delimiter

Defines the delimiter of text sources for list boxes and selections. This is usually a ':' or '\n'.

item.delimiter=','; // sets a comma as delimiter of the input text source

Number fadeInterval

v1.1.0 Sets the fading interval of a DiaShow item in seconds. The interval includes the fading time.

item.fadeInterval=5;

The fadeInterval must be higher than the fadeTime.

Number fadeTime

v1.1.0 Sets the fading time of a DiaShow item in seconds (time to fade from one image to another).

item.fadeTime=3;

The fadeInterval must be higher than the fadeTime.

Boolean disabled

Disables or enables an item.

item.disabled=true;

String imageId

Sets the URL for the image. In the client scripting environment this has no effect because the image is already loaded.

item.imageId='/images/myimage.png';

String label

Sets the text label of an checkbox or radio button. This is currently available in the server scripting environment only.

item.label='my new text for the checkbox';

Number maxLength

Sets the maximum input length (allowed character length) of an text input item.

item.maxLength=3; // maximum of three chars

String name

Name of the item. In Phi this is the same as the item id.

var name=item.name;

String parentName

This is the name (id) of the parent item. This reflects usually a layout container or a group of elements (i.e. checkboxes and radio buttons). In a POST request this name is sent for checkboxes and radio buttons.

check1.parentName='checkgroup';
check2.parentName='checkgroup';

Warning: misuse of setting this property may cause unpredictable behavior (i.e layouts depend on correct settings).

StringArray pictureBookIds

Represents the string array of different image URLs i.e. for rollover buttons, picture books or Dia-shows.

image.pictureBookIds[0]='/images/image1.png';
image.pictureBookIds[1]='/images/image2.png';

StringArray properties

Returns the available property names for the item.

var int i=0;
while ( item.properties[i] ) print( item.properties[i++] );

Boolean readOnly

Sets the read only flag for an input element.

item.readOnly=true;

String styleSheet

Sets the style sheet (CSS) for an item.

item.styleSheet='color: red; background-color: blue;';

Warning: this function is experimental. Please report any issues to mailto:bugs@phisys.com to help us improving this feature.

Number tabIndex

Sets the tab ordering number of the item.

item.tabIndex=3;

String title

Sets the tool tip (title) of an item.

item.title='description of item';

Number type

Returns the type id of the item.

var type=item.type;

Warning: this property is differently used in HTML and Phi. In HTML you obtain the input type as a string (like text or radio) with this function and not an id number like in Phi mode.

String url

Sets the URL for click- and rollover buttons or external HTML documents. Use this in the server scripting environment only!

item.url='http://wiki.phisys.com';

Some special Phi variables like the session and page language are automatically appended to the URL.

Functions

Note: These functions are available in the client environment only.

Void blur()

v1.2.0 Removes the focus of an input item.

var myitem=phi.getElementById( 'myitem' );
myitem.blur();
$('myitem').blur(); // v1.3.0 (recommended)

See also: $('myitem').blur().

Void click()

v1.2.0 Generates a click on button elements.

var mybutton=phi.getElementById( 'mybutton' );
mybutton.click();
$('myitem').click(); // v1.3.0 (recommended)

Void focus()

v1.2.0 Sets the current focus on myitem.

var myitem=phi.getElementById( 'myitem' );
myitem.focus();
$('myitem').focus(); // v1.3.0 (recommended)

Event handler

Event handler are available in the client (browser) scripting environment only. Since v1.3.0 we recommend to use the event handler of the wrapper class.

onblur

Called if the item looses focus.

item.onblur=function() { doSomething(); }
$('myitem').blur(function(){ doSomething();}); // v1.3.0 (recommended)

onchange

Called if the value or check state (ie. checkboxes and radio buttons) of an item changes.

item.onchange=function() { doSomething(); } 
$('myitem').change(function(){ doSomething(); }); // v1.3.0 (recommended)

ondblclick

Called whenever the item is double clicked.

item.ondblclick=function() { doSomething(); }

Note: the handlers item.onmousedown and item.onmouseup will also be called.

onclick

Called if an item is clicked. For submit and reset buttons you should return true or false. Returning true for submit buttons will send the formular or for reset buttons the form will be reset to default values.

submit.onclick=function() {
  if ( formElementsCheck() ) return true;
  return false;
}

See also: Submit button, Reset button.

onfocus

Called if the item receives focus.

item.onfocus=function() { doSomething(); }
$('myitem').focus(function(){ doSomething(); }); // v1.3.0 (recommended)

onkeydown

Called if the item has focus and the user presses a key. In Phi this is the same as onkeypress.

item.onkeydown=function() { doSomething(); }

onkeypress

Called if the item has focus and the user presses a key. In Phi this is the same as onkeydown.

item.onkeydown=function() { doSomething(); }

onkeyup

Called if the item has focus and the user releases a key.

item.onkeyup=function() { doSomething(); }

onmousedown

Called if the mouse button is pressed.

item.onmousedown=function() { doSomething(); }

onmousemove

Called if the mouse is moved over an item.

item.onmousemove=function() { doSomething(); }

onmouseout

Called if the mouse cursor is moved out of an item.

item.onmouseout=function() { doSomething(); }

onmouseover

Called if the mouse enters the region of an item.

item.onmouseover=function() { doSomething(); }

onmouseup

Called if the mouse button is released.

item.onmouseup=funtion() { doSomething(); }

Additional notes

Other functions and properties are currently not supported by Phi since they are rarely used. Please let us know if you really need specific functions and we will consider to implement them in future releases.