pCOWeb
+030220966 – rel. 1.1 – 12.12.2017
77
API
The library “pw_ajax.js” needs the following functions, which have to be used in the javascript section of the html page:
•
getParams (defined in “pw_ajax.js”, therefore it has to be only executed in the html page)
•
parseResults (from A142 – it is only executed by the pw_ajax.js library, therefore it has to be declared in the html page).
It needs the following arrays to be declared in the html page:
•
digitals
•
integers
•
analogs
And one variable (optional):
•
timestamp (A142)
getParams
The function getParams, using the (very common) browser function “XMLHttpRequest” (
http://en.wikipedia.org/wiki/XMLHttpRequest
), retrieves values from
pCOWeb
executing “xml.cgi”.
“xml.cgi” is an application custom made for
pCOWeb
to generate an xml file containing the values requested by the arguments of the function getParams, the
URL that the browser will request to the
pCOWeb
, following the example, is:
http://<ip_address_pCOWeb>/config/xml.cgi?D|1|2|I|11|12|A|101|102
The syntax of the query is “xml.cgi? + VAR_TYPE|START_INDEX|END_INDEX|”, the string allows to request many ranges of variables, up to the maximum
length allowed by the browser.
Starting from version A142, “xml.cgi” is able to recognize the argument “N” positioned at the beginning of the request, so that the xml file returned by
pCOWeb
will use the new and more performing format; the request now will look like:
http://<ip_address_pCOWeb>/config/xml.cgi?
N
|D|1|2|I|11|12|A|101|102
The library “pw_ajax.js” in “/config” of the firmware >=A142 is automatically using the new format for the xml file; therefore, for the applications designed for
firmware A135 in order to use the new format, they have to:
•
if the web pages are importing the library using the path “/config/pw_ajax.js”, nothing has to be done to update them
•
if the web pages are using a local copy of the library, the new library will have to be copied in the folder to update it, the new library is fully compatible with
the old one.
For custom made pages which are not using the standard “pw_ajax.js” library to use the new format for the xml file, it is necessary to adjust the string sent by
the browser and to adapt the parser of the xml to the new format; keeping the string as for version A135 will use the “old” xml format. Copy and pasting the
same URL to the browser, it will return the following XML (values contained depend on the application running on the
pCO
controller):
New format
<PCOWEB t="
2010-03-22 11:48
">
<PCO>
<
DIGITAL
>
<O I="
1
" V="
1
"/>
<O I="
2
" V="
0
"/>
</DIGITAL>
<
INTEGER
>
<O I="
11
" V="
0
"/>
<O I="
12
" V="
0
"/>
</INTEGER>
<
ANALOG
>
<O I="
101
" V="
0.0
"/>
<O I="
102
" V="
0.0
"/>
</ANALOG>
</PCO>
</PCOWEB>
Old format
<PCOWEB>
<PCO>
<
DIGITAL
>
<VARIABLE>
<INDEX>
1
</INDEX>
<VALUE>
1
</VALUE>
</VARIABLE>
<VARIABLE>
<INDEX>
2
</INDEX>
<VALUE>
0
</VALUE>
</VARIABLE>
</DIGITAL>
<
INTEGER
>
<VARIABLE>
<INDEX>
11
</INDEX>
<VALUE>
0
</VALUE>
</VARIABLE>
<VARIABLE>
<INDEX>
12
</INDEX>
<VALUE>
0
</VALUE>
</VARIABLE>
</INTEGER>
<
ANALOG
>
<VARIABLE>
<INDEX>
101
</INDEX>
<VALUE>
0.0
</VALUE>
</VARIABLE>
<VARIABLE>
<INDEX>
102
</INDEX>
<VALUE>
0.0
</VALUE>
</VARIABLE>
</ANALOG>
</PCO>
</PCOWEB>
After receiving the XML, the library parses it and loads the information to the three arrays declared on the top of the javascript code of the HTML page, it is
very important that the name of the arrays have to be kept to “analogs”, “digitals” and “integers”.
The current time of the
pCOWeb
received will be loaded into the variable “timestamp”.
parseResults (only from version A142)
Starting from Version A142, the “pw_ajax.js” library is using a new function called “parseResults” which is executed as soon as the browser receives the xml
from
pCOWeb
, so that the values shown in the html can be updated without waiting for the next run of the javascript code. Up to version A135 the function
responsible to read from the javascript arrays (digitals, integers and analogs) was executed just after having sent the request for the xml file to the
pCOWeb
before having the new values loaded into the arrays, therefore it was necessary to wait for the next time the function is executed to have the values shown on
the web page, the web pages were always showing the values received on the previous request. This reduces the time-to-values when the web page is
loaded for the first time and the responsively of the web page when values change in the
pCO
. This function is not defined in “pw_ajax.js” which is, instead,
only using it, the function has to be declared in the html page, as shown in the example. To be compatible with web pages developed with firmware < A142,
this function is optional and is executed only if defined in the html file.
