Home | Quick Reference


dynapi.util.IOElement - Quick Reference

Inherit: DynLayer 


Add-Ons

IOElementSoda
 Enable RPC/Web Service connections to the server

IOElementSync
 
Enable Synchronous connections 


Constructor

IOElement(hiddenThreads,useXFrames);
hiddenTbhreads	– total number or threads or ports (0-8);
useXFrames	– use eXternal Frames for post request in NS4 and other browsers

Events

onresponse(e,s) - Triggers after a  server response.
e - (EventObject)
s - (Boolean) True is request was successful
 
onrequest(e) - Triggers after a request has been sent to the server.
e - (EventObject) 

example:

var url="ibook.asp";
var io=new IOElement(1); // create single threaded ioelm
 
io.addEventListener({
 onrequest:function(e){
    var o=e.getSource();
   if(o.api.loadmsg) o.api.loadmsg.setVisible(true);
 }
});

// load app
io.get(url);

Public Methods

failTime - (Integer) Time in which a server a timeout notification is triggered

isSync - (Boolean) True is synchronous mode was activated  


activateSyncMode(fn,useJava) - Activate Synchronous Transfers Mode.  IOElementSync  

fn 	– callback or returned function
useJava	- forces the use of a java applet for synchronous communication

cancel(id) - Cancels the specified request.

id - (String) request id

example:

var io=new IOElement(1);
var id=io.get('mypage.html');
io.cancel(id);
 
cancelAll() - Cancel current and pending requests.

example:

var io=new IOElement(1);
io.get('mypage1.html');
io.get('mypage2.html');
io.cancelAll();
 

createWebService(name, url, fn, useSync, uid, pwd, method) - Creates a connection to a SODA-RPC web service.  IOElementSoda 

name – (String) local name used to identify the service
url – (String) SODA web service url
fn - (Function) Callback function
useSync - (Boolean) Activate Synchronous transfers
method – method used for request; POST or GET
uid - user id - for use with server-side login event when
a connection is created
pwd - user password - for use with server-side login
event when a connection is created

The following are methods exposed by a the web service object. obj represents the created service

obj.isConnected  - (Boolean) True if a connection was established with the server.

obj.call(name, params, fn, cargo) -  Calls a remote method on the server. This method is available  to newly create web services.  IOElementSoda 

name – name of method(s) on the server
params – parameters to pass to the method(s);
multiple params are passed as an array
fn – callback or returned function.
When set to false a synchronous call is made.
 

example:

io=IOElement.getSharedIO();
io.createWebService('srv',url,OnWSConnect,false);

function OnWSConnect(ws,s,errorText) {
   if (s!=true) {
      alert('An Error occured while creating web service: '+errorText);
      return;
   }
   frm=document.forms['myform'];
   frm.txtname.value=ws.getWebName()
   frm.txtcomment.value=ws.getWebComment()
};

obj.getWebName() Returns the name of the web service.

obj.getWebComment() 

obj.importWebMethods() - Import web methods exposed by a web service. Returns true if successful.

disconnectWebService(name, fn) - Disconnects the web service object band triggers the logout event on the server.  IOElementSoda 

name – (String) local name used to identify the service
fn - (Function) Callback function

execInParent(fn) - Executes JavaScript codes within the scope of the parent element.

fn - (Function/String) JavaScript code to be executed

example:

//from within the requested page
var io={};
var dynapi = parent.dynapi;
if (dynapi) io = parent.IOElement.notify(this);
else alert('Error: Missing or invalid DynAPI library');

io.execInParent(function(){
    tpLogin = new parent.Template('This is a test Layer',0,0,0,0);
    tpLogin.setAnchor({left:100,top:100,bottom:100,right:100});
    tpLogin.setDefaultFieldValue(' ');
    tpLogin.generate();
    dynapi.document.addChild(tpLogin);
});
io.execInParent("alert('This is executed from within the parent')");

get(url, data, fn, cargo) - Submits data to the server using the GET method.

url - (String) URL to upload the the data to.
form - (FORM Element)  
fn - (Functions/String) Executed upon server response.
When set to false a synchronous call is made
cargo - (Object) An object that's can be used to store values
that can be accessed upon server response.
 

When a response is received from the sever the fn argument is executed. If all goes well then a success argument is passed to fn if fn is a Function. After each successful response the current Request object is deleted from the Requests Collection object and the Request Index counter is incremented.  

There are times when you'll need to preserve the current request object for later use. To do this you must return the Boolean "false" from within the "fn"  callback function:

io.get('page.cgi'null,fn);
function fn(e,s){
   var o=e.getSource();
   if(s) {
      // improper response - display message
     return;
   }
   var r=o.getVariable("error"); // customer error
   if(r) {
      // display custom error message
      // return false to cancel the request session and
      // preserve the request object
      return false;    }
};

The cargo object is very useful when you're working with multiple forms that have to be updated separately.

example:

// user clicked on form1

var formid='f1';

// store formid in cargo object
var cargo={
   fid:formid
}
// this request was sent from form1
io.get('info.asp',{id:formid},srvResponse,cargo);

:
:

// user clicked on form2 while waiting for form1 to load

var formid='f2';

// store formid in cargo object
var cargo={
   fid:formid
}
// this request was sent from form2
io.get('info.asp',{id:formid},srvResponse,cargo);



function srvResponse(e,s){
   var o=e.getSource();
   var cargo=o.getCargo();
   // ^ getCargo() should only be called from within the callback function/event
   // once it is called the cargo will be offloaded

   document.forms[cargo.fid].txtcomment=o.getVariable('comment');
   // ^ now we now which of the forms to update
}
getCargo(dontRemove) - Returns stored cargo.
dontRemove - This leaves a copy of the cargo in storage for
later use during a server call

The cargo object will allow you to store data when a request is sent to the server, and retrieve that data when the server sends back a response.

getCargoID() - Returns the current cargo or request id. Used during server-side responses.

getScope() - Returns the frame or layer or the current calling scope.

getVariable(name) - Returns a javascript variable returned by the server.
name - (String) name of variable
 

getResponse() - Returns a response object containing the returned value from the server and and error object.  IOElementSoda 

isBusy() - Returns true if the calling threads are busy.

post(url, data, fn, cargo) - Submits data to the server using the POST method.

url - (String) URL to upload the the data to.
form - (FORM Element)  
fn - (Functions/String) Executed upon server response.
When set to false a synchronous call is made
cargo - (Object) An object that can be used to store local values
that can be retrieved (using getCatrgo()) during a server call.

Note: See get()  function for more details

retry(id) - Retries a failed asynchronous request. Calling retry() without an id will retry the last failed request. Returns true is retry was successful.
id - (String) request id 
setTimeout(ms) - Sets the server-response timeout.
ms - (Integer) Milliseconds 
upload(url, form, fn, cargo) - Uploads a file to the server.
url - (String) URL to upload the the data to.
form - (FORM Element)  
fn - (Functions/String) Executed upon server response
cargo - (Object) An object that's can be used to store values
that can be accessed upon server response.
 
useSingleThread(b) - Switches between multithreaded and single threaded calls.
b - (Boolean) Enables or disables single threading

Private Methods

 


Static Methods

createGUID() - Returns a Globally Unique Identifier string

getSharedIO(useXFrames) - Returns a shared instance of the IOElement object. This is useful when implementing data bounded widgets.

useXFrames - (Boolean) Enable NS4 Browsers to send data via post methods

example:

var io=IOElement.getSharedIO();
io.get('myhtml.html');
  
notify(elm, fn)  - Notify the IOElement object of a server-side response. This method is normally used inside the html returned from the server.
elm - (object)  frame element
fn - (Function/String) Executed after the document has loaded

example:

var dynapi = parent.dynapi;
var ioelement;
if (!dynapi) alert('Error: no dynapi');
else {
   // run init() when this page loads
   ioelement = parent.IOElement.notify(this, init);
}

function init(){
 // some code here
}
 
getAbsoluteUrl(url, docUrl)

 


Server-Side Scripts

JScript (ASP) 
ioelmsrv.jscript.asp
ioelmsrv.soda.jscript.asp
 
PHP
ioelmsrv.php
 
Perl
ioelmsrv.pl
ioelmsrv.pm
 
VBScript (ASP)
ioelmsrv.vbscript.asp
ioelmsrv.soda.vbscript.asp