HOW TO USE PHPLIVEX ? (Version 2.4)

For older versions, please take a look at downloads section.
The properties shown in blue are added in version 2.4 and the crossed out ones are removed with this version.

ConstructorDescription
PHPLiveX($functions, $url) Starts to handle ajax requests. Exports php functions for ajax.
$functions: Optional. Takes function names (if more than 1, seperated by commas);
$url: Optional. The URL of the file in use. When complex URLs are used, the class might not read them itself. It is solved by using this property.

MethodDescription
Export("functionNames,...") Exports the functions for ajax. Can only be called over run method.
Parameter Value:
1) Function names (if more than 1, seperated by commas).
2) "ALL" for all user defined functions.
ExportClassFunctions("objectName-> methodName,...")
ExportObjectMethods("objectName-> methodName,...")		 Exports object methods for ajax. Can only be called over run method.
Parameter Value:
objectName (like myObject in "$myObject = new myClass();").
methodName is name of the object method (if more than 1, seperated by commas).
ExportMethods("objectNames,...") Exports all methods of the classes for ajax. Can only be called over run method.
Parameter Value:
Object names (if more than 1, seperated by commas);
Run() Creates javascript codes to handle ajax requests. Must be called between outside script tags

Property Description
ExternalJS (boolean) Default is "false". With "true" value, java script codes automatically created by the library are included in with another file. In this case, the user do not see the most of phplivex codes in source.

At first, you must create the phplivex object. To export your functions, you can use both constructor function and export method. 

<?

function myFunction($text){
   return $text;
}

$plx = new PHPLiveX("myFunction");
### OR
$plx = new PHPLiveX();
$plx->Export("myFunction");

?>

If you want to export a class function, you must create the instance at first. Then you can export its functions as in the example. Note that this property uses session so it needs session_start() ahead. 

<?

class myClass(){
    var $Text;
  
    public function __construct($text){
        $this->Text = $text;
    }

    public function setText(){
        return $this->Text;
    }
}

$test = myClass("it's very easy-to-use");
	
$plx->ExportObjectMethods("test->setText");
### OR
$plx->ExportObjects("test");

?>

You must call run method between script tags anywhere on the page. But give attention that methods under run method does not work. So it's better to call it at the end of the page if you are using complex template systems, but if it is not a problem for your system in any way, you'd better prefer "head" tags. 

<script language="javascript">
<? $plx->Run(); ?>
</script>

You can call your exported functions via javascript. The global functions are called directly with its name (e.g. myFunction) but the class functions are called with #instanceName__methodName# (e.g. test__setText).
In order to call these functions, you must use necessary parameters below within one last argument. But all of these properties are optional. If you don't use any of them (pass the argument empty), the function runs without returning a value.

Parameter Description
type Can take only one value "r". If you want to get returned value of the function (e.g. pass the value to a variable). And if this parameter is used, the others except "mehod" and "url" cannot be used. Note that if this parameter is used, the ajax request runs synchronously. (During the process, no other function runs and it is slower.)
target Takes the ID value of a DOM element and returned value of the function is printed to its attribute which is defined by "targetProperty". If this parameter is used as "target=alert", the returned value is alerted. If it takes more values, these are given in this way: "target=id1:id2:id3" (This property was removed because the same operation can be done with "onFinish" and "onUpdate" parameters).
mode The default value is "rw"(rewrite) which means rewriting the returned value to an attribute(defined by "targetProperty") of the "target". If you use "aw" (append), the value is appended to the initial value of attribute, whereas "asw" "pw" prepends it.
preload Can take the ID value of a DOM element used for preload. It must be hidden(style= "visibility:hidden" or "display:none") initially. During the process, the foregoing element is made visible and then hidden when the process finishes. Note that this parameter can not be used with type together, because it needs an asynchronous request.
method Can take "post" and "get" values. These are the http-methods of the xmlhttp request. Default value is "POST". When used with "SubmitForm" method, it becomes the form method.
onRequest The value must be a javascript function. This function runs just before the request is sent.
onFinish The value must be javascript function. This function runs when the response of request is taken, but before it is written to page. In addition, the response code is passed as an argument to the function. If it returns something, the response code to be written is replaced with this returned value.
onUpdate The value must be a javascript function. This function runs when the response of request is taken, but after it is written to page. In addition, the response code is passed as an argument to the function.
hideContent clearValue Can take boolean values (Default is "false"). "true" value means that during the preloading, the content of target dom element is emptied.
interval Can take a time interval in milliseconds. With this interval, the function is called repeatedly.
myPreload This parameter, which gives users the possibility to create their own preloading, was deprecated, because the same operation may be done with "onRequest" and "onUpdate" parameters.
targetProperty By default, "innerHTML" or "value" attributes (which is supported) of the target dom element are manipulated. "targetProperty" can change the attribute manipulated (e.g. by using targetProperty: "style.backgroundColor", the background color of target dom element can be changed).
hideProperty preloadStyle It is "visibility" or "display" attribute (used for hiding and revealing element) of the dom element for preloading. Default is "display".
url It can be used for three different functions:
  1. By using with "ExternalCall" method, URL of another page is passed to send ajax request to that file.
  2. By using with "SubmitForm" method, URL of another page is passed to assign it as form action.
  3. When using nested ajax requests (e.g. include another page containing new phplivex exports with ajax), ajax functions defined in the ajax response (included page) do not work properly, because browser read the page once. So, you must pass this functions "url" parameter containing the file URLs in which they are defined.

Methods Description
ExternalCall(parameters) Used to send ajax requests to another page. (e.g. new PHPLiveX().ExternalCall({preload: '...', target: '...', url: 'test.php', ...}))
SubmitForm(form, filterFunction(default is null), parameters) Used to send forms by ajax request. The first argument is a form element. The second is a function for filtering (e.g. error controls. Default is null) form values and called before sending form. (e.g. <form onsubmit="return new PHPLiveX().SubmitForm(this, null, {url:'test.php', target: 'alert', method: 'get', ...});">). 

<a href="
javascript:myFunction('it is an example', {target: "showText", preload: "loadSpan"});
">test it</a>

<span id="showText"></span>
<span id="loadSpan" style="display:none;">Loading...</span>

<!--
If you use "visibility" attribute instead of "display", hideProperty parameter must take "visibility" 
value.
-->

The function ahead prints "it is an example" to the innerHTML of the DOM element(span) whose id is "showText". It also uses preloading by displaying "Loading..." text during the process. The mode parameter is "rw" by default. By each click on the anchor, foregoing span shows the same text. But if "mode=aw" parameter is added, the text will append to the initial value. For example; after 3 calls, innerHTML of the span becomes "it is an exampleit is an exampleit is an example". If you don't use preload parameter, there won't be any preloading. In addition, you don't have to use target method. For example; supposing that your function just updates database, you don't define a target and it doesn't print anything.

<script>
function changeResponse(resp){
	return "This text is added to returned value of myFunction. " + resp;
}

function showContent(resp){
	alert(document.getElementById("showText").innerHTML);
}
</script>

<a href="javascript:
myFunction('It is another example', 
{target: "showText", preload: "loadSpan", onFinish: changeResponse, 
onUpdate: showContent});">test it</a>

The function above prints "This text is added to returned value of myFunction. It is another example" to the target dom element (showText). When it is done, an alert box containing this text appears. 

<script language="javascript" >
var output = test__setText("an example", {type: "r"});
# ...
</script>

As this function use "type=r" parameter, the value it returns may be passed to a variable.

ExternalCall and SubmitForm Methods


<a href="javascript:new PHPLiveX().ExternalCall({url: 'test.php', preload: '...', target: '...', ...});">
click to send an ajax request to "test.php" and retreive the page output if exists.
</a>


<form onsubmit="
return new PHPLiveX().SubmitForm(this, null, {url: 'test2.php', method: 'get', onFinish: '...', ...});
">
<input type="text" name="username">
<input type="password" name="password">
<input type="submit">
</form>