PERSONAl C# REFERENCE
FOR WEB APPLICATIONS
=====================
When you write a program to run as a desktop application, you make your class extend the
PC# class "pcs". If you like to run your program as a web application, you make your class
extend class "pasp". "pcs" is for "Personal C Sharp" while "pasp" is for "Personal ASP".
The two classes are similar in much of their contents. Here are the major differences
between the two:
** Class "pcs" extends the ".NET" class "System.Windows.Forms.Form" while class "pasp"
extends class "System.Web.UI.Page"
** Class "pcs" can install controls into a window form which can run as a desktop
application. Class "pasp" can install controls into a web form which can run using a
browser.
** Class "pcs" can display text on the "Console", on the "Text Screen" or into a dialog
box. Class "pasp" cannot. It can only display text on the browser's screen. However, it
allows you to display text for debugging purposes by saving the text for you into a
file which you can later display on the Console using tool "out" as will be explained
later.
** Within the run() method of class "pcs", jumping from one code block to another is
allowed. Class "pasp" does not contain run() method or block jumps, however we'll show
you a technique which allows a different type of jumping using the "query string".
** Class "pcs" allows multi-threads and serialization, class "pasp" does not.
NEW PROGRAMMING TOOLS:
======================
Some of the tools which are usable for desktop development are of no use here and some
are used for the purpose of debugging only. "pcp" and "pcpr" are of no use since they are
for creating executable files which are not necessary for web development. "pcl" and "ln"
can be used for debugging purpose only as will be explained later under the title of
"Error Handling". Meanwhile, there are few new tools which are:
pcw: Creates the ".aspx" file which is necessary for the execution of a code file. To
create a web page you write the C# code file which generates the page and save it as
a ".cs" file. The browser cannot make use of the code file directly. It requires a
".aspx". By using this tool, you generate a short ".aspx" which acts as an interface
between the browser and the code file.
Example: After creating the code file "MyPage.cs", you should type the following at
the Command mode prompt:
pcw MyPage [Enter]
in order to generate the file "MyPage.aspx" which can be requested by the browser.
pcwm: Compiles the code file of a "master page" and stores the library (.dll) file
produced into the "Bin" subfolder of the application folder.
Example: After creating the code file "MasterPage.cs" for a master page, you should
type the following at the Command mode prompt:
pcwm MasterPage [Enter]
in order to generate the file "MasterPage.dll" and store it into the "Bin" subfolder.
out: This tool displays the content of the text file "output.txt" on the Console then
deletes the file. All the texts generated when a "Runtime error" takes place, and
when methods tm(), wr() or wrln() are called within the code file are stored into
file "output.txt". This tool displays the text for you.
Example: After executing a web page, you may type the following at the Command mode
prompt in order to see the text which has been generated :
out [Enter]
To know more about using methods wr() and wrln() for debugging see "Error Handling".
The page file: Here is the listing of "MyPage.aspx" file generated by the tool "pcw":
--------------
IMPORTANT REMARK: We have replaced all "angled brackets" with "square brackets" in order
to force your browser to display the listed code lines instead of executing them.
[%@ Page Language="C#" CodeFile="MyPage.cs" Inherits="MyPage" Debug="true" %]
[html]
[head][/head]
[body]
[form runat="server"]
[asp:Table ID="table" runat="server" /]
[/form]
[/body]
[/html]
PROGRAM STRUCTURE
===================
using System.Security; // Additional "using" directives
public partial class MyPage:pasp { // Class declaration. Class name must match
// code file name (.cs) and page file name (.aspx)
double price; // Variable declarations (Optional)
public override void init() { // Method init() (necessary)
base.init(); // Must be last statement
}
public override void setup() { // Method setup() Necessary only when you
} // like to install web controls.
public override void update() { // Method update() A must for any web page
}
}
Method update():
----------------
Here is the minimum code which method update() may contain if there are some controls
to be installed:
public override void update() {
if(cs.Equals("pl")) { // If event is "Page_Load"
setup(); // Execute setup()
MakePage(table); // and Make the page
}
}
If there were no controls to be installed into the page, but there are other actions to be done
when Page_Load event is raised, the second and third lines may be eliminated.
EXECUTION SEQUENCE:
===================
The first method to run is method init() Whenever the Page_Load event or any other event is
received, method update() is called. Your code inside method update() calls method setup()
and method MakePage(table) whenever necessary. So the execution sequence is:
init() ---> update() ---> setup() ---> MakePage(table)
REMARK: Method MakePage(table) is inside class (pasp) Your class does not override it.
WHERE TO PLACE FILES?
=====================
The ASP.NET has its own requirement for the placement and format of each of the files
which produce the page. To make things easy, let us assume that we have created the
code file "a.cs" and used the tool "pcw" to generate the file "a.aspx". Here is what
the ASP.NET expects:
(1) File "a.aspx" is expected to be located into the application folder.
(2) File "a.cs" is expected to be located into the application folder as is, which means
uncompiled.
(3) File "pasp" which class "a" extends is expected to be located into the "Bin" subfolder
of the application folder as the library file "pasp.dll" which means compiled.
As a general rule, if we have a hierarchy of classes the code file which contains the
top class should stay into its ".cs" form and should be placed into the application
folder and every other file should be compiled into a library file and placed into the
"Bin" subfolder.
WHERE IS THE ROOT FOLDER?
=========================
The root folder to the web is not the same as the root folder to the system. To the
browser "wwwroot" is the root folder. To the system this folder is not the root, its path
could be "c:\inetpub\wwwroot" assuming that "c" is the containing drive.
To the system, the back slash is the file/folder seperator character. To the web the
forward slash is. The back slash character must be doubled when we write C# code since
this character has a special meaning in C# language.
When we supply the path for an image in a web page to method wm() for the purpose of
setting up a control or generating html code we must use the web's formula. When we
supply the path of a file or image to method fm(), method gm() or any method other than
wm(), we must use the system's formula.
Method wm() has two modes which provide help with this issue. Calling wm("pn") returns to
you the name of the page file you are working on. Also, you can convert a file path from
web's formula to system's formula by calling wm("fp").
=========================================================================================
THE PRESENT OBJECT FOR WEB CONTROLS AND OTHER RELATED OBJECTS:
==============================================================
Examples on How to obtain them:
------------------------------
All objects can be obtained by calling method wm() at mode "O" (This is upper case 'O')
(1) cs="bt0";wm("O"); // Makes (btp) a reference to button bt0's object.
(2) cs="tf2";wm("O"); // Makes (tfp) a reference to text field tf2's object.
(3) cs="";wm("O"); // Return general object references only (like cfp)
cfp Application's Configuration object
btp Button
lbp Label
cbp CheckBox
rbp RadioButton
chp DropDownList
lsp ListBox
tfp Text Field
tap Text Area
pnp Panel
tlp Table
igp Image
hlp HyperLink
ltp Literal
cap Calendar
lop Login
cup CreateUserWizard
cpp ChangePassword
vsp ValidationSummary
fup FileUpload
ibp ImageButton
gvp GridView
You may have noticed that "tlp" is the present object reference name for a table although
"tbp" was the name expected. The reason we had to do so, is that the name "tbp" was used
in Graphics to represent the "Texture Brush" object. We are using "tb0, tb1,..etc" as
keynames for tables despite that.
Control setup Parameters and update values:
-------------------------------------------
Method wm() at modes which start with "s" is used for setup. You supply it with the control's
keyname assigned to (cs) in addition to the required setup parameter(s). Some parameters are
common for all controls and some are special for each one.
Common setup modes:
-------------------
sC : Set color. The method receives a combined Foreground-Background color code assigned to
(cls) It can be made of either 4 characters or 6. The opacity digits are not usable
with web controls except that some controls can be made with transparent background,
Label, Table and calendar controls are examples of that kind. To make the background
of a control transparent, the 6th character of (cls) should be "0".
sF : Set Font. The method receives the font code assigned to (fns).
sA : Set Attributes. Adds the key and value (ks,os) to the Attributes of the control.
sB : Set Bounds. Sets the width,height at (i,o) and the border width at (jd)
sx : Set focus at the control.
sE : Set Enable. Receives (jb) and disables the control if (jb=true)
st : Set tool tip value. Assigns (cts) to the control's tooltip.
Special setup modes:
--------------------
BUTTON:
sl: Set Botton's label at (cis)
LABEL:
sl: Set Label control's text at (cis)
LITERAL CONTROL:
sl: Set Literal control's text at (cis)
CHECK BOX:
sl: Set CheckBox control's text at (cis)
su: Set CheckBox's state according to (cus) cus="1" means checked.
RADIO BUTTON:
sl: Set RadioButton control's text at (cis)
su: Set RadioButton's state according to (cus) cus="1" mean checked.
DROPDOWN LIST:
su: Set Item to be selected by default. Item order should be assigned to (cui)
sL: Set labels. Assign text of all items to CIS[] before calling this mode.
LIST BOX: At this mode the ListBox is checked to see if it is of Single Selection type
or of Multiple selection type before proceeding with setup.
su: If Single selection list, The item whose index is in (cui) will be the selected one.
If multiple selection list, CUS[] rows will be checked. When "1" is found to be the value
of a row, the list item with the same index as that row will be checked.
sL: Set labels. Assign text of all items to CIS[] before calling this mode.
sb: Set list type according to (ib) If (ib=true) it will become a "Multiple Item List".
TEXT FIELD: This is a single line TextBox.
su: Set Text Field's default text at (cus)
sb: Set Boolean flag (ib) If (ib=true) make it a "Password" TextBox where characters are
displayed as astrisks.
se: Set editability according to (ob) If (ob=true) make it a "Read Only" TextBox".
ss: Set Size. Set the visible size in characters to (jf)
Sets the max (visible & invisible) number of char's it can take to (od)
TEXT AREA: This is a multiple line TextBox.
su: Set Text Area's default text at (cus)
se: Set editability according to (ob) If (ob=true) make it a "Read Only" TextBox".
ss: Set Size. Sets the visible horiz size in characters to (jf) & vert size in lines to (kf)
Sets the max (visible & invisible) number of char's it can take to (od)
PANEL:
sg: Set Background Image to (ims)
TABLE:
sb: Set grids visibility. If (ib=true) grids will be made visible.
sg: Set Background Image to (ims)
ss: Set Cell spacing size at (kd)
IMAGE:
sg: Set Image of the Image control at (ims) where ims= Image's URL.
HYPER LINK: It can be either a text link or a clickable image.
sl: Set HyperLink's text at (cis)
sg: Set Image of the HyperLink control at (ims) where ims= Image's URL.
su: Set the URL of the page to be retrieved or the e-mail address to send a message to at (urs)
sb: Set target window. If (ib=true) web page will be displayed into a seperate window.
CALENDAR:
sb: Set grids visibility. If (ib=true) grids will be made visible.
ss: Set Cell spacing size at (kd)
VALIDATION SUMMARY:
sl: Set header text at (cis)
IMAGE BUTTON:
sg: Set Image of the ImageButton control at (ims) where ims= Image's URL.
=========================================================================================
ACCESSING THE WEB.CONFIG FILE PROGRAMMATICALLY:
===============================================
The "web.config" file can be read from or written to programmatically. PC# helps you by
supplying a reference to the application's configuration object in (cfp) The rest you
should do by yourself. Let us have an example.
Consider the web.cofig file: (Please note that all angled brackets have been replaced
with squared brackets to overcome a display problem).
[configuration]
[system.web]
[customErrors mode="Off"/]
[/system.web]
[/configuration]
We are going to obtain the value of "mode" and display it on the page.
----------------------------------------------------------------------------------
using System.Web.Configuration; // This namespace is necessary for the operation
public partial class a:pasp { // Page's class
public override void init() {
base.init();
}
public override void update() {
if(!cs.Equals("pl")) return; // If not "Page Load" event return;
cs="";wm("O"); // Get all general objects
CustomErrorsSection ces; // Instanciate desired section
ces = (CustomErrorsSection)cfp.GetSection("system.web/customErrors");
// and get the section object
os=ces.Mode.ToString();wm("rw"); // Display the value on the page.
}
}
----------------------------------------------------------------------------------
Remarks:
--------
(1) You have to be careful. As you may have noticed the name "CustomErrors" start
with an upper case char in the Section class name and starts with a lower case
char in "system.web/customErrors".
(2) Some of the values can easily be assigned to a string, boolean or numeric variables
while others come in the form of enumeration objects.
(3) You can change a value of any parameter in the web. config file by assigning it
a different value then executing [cfp.Save();].
=========================================================================================
ERROR HANDLING
==============
RUNTIME ERRORS:
---------------
When you work with ASP.NET classes, error handling becomes no easy task. When you have
been troubleshooting desktop applications, you have been able to use the "Console.Write()"
method to display information which can lead you to the source of the problem. Here we
have no Console to display on. You can't use the text screen or a dialog box for display
either. The only display media you have is the browser and normally the browser will not
display your messages if there has been an error.
All the "aspx" files generated by the tool "pcw" contains the directive (Debug="true")
which allows you to get all the information you can get about the error which ASP.NET can
give. Unfortunately in many cases they are not too helpful or even misleading.
AND THIS IS OUR SOLUTION FOR THIS PROBLEM:
------------------------------------------
We use a file to do all display. This file name is "output.txt". Class (pasp) writes
all text output into it. All the error messages which PC# used to send to the Console are
written into this file. All the troubleshooting messages which you like to display go to
this file.
To write any text to the file you have two choices:
(1) Assign the message to (os) and call tm("dl") or tm() to display the message then move
to next line or tm("d") to display the message only.
Method tm() as you know resets all GUV's after it completes its job. This makes it
inconvenient for displaying error messages within your program.
(2) Use the method wrln("Your Message") to display message and move to next line or
wr("Your Message") to display only.
This method is the better choice for error handling since it does not change the value
of (os), the GUV's or any other variable.
To display the file's text from command mode type: out [ENTER] or use NotePad.
ERROR HANDLING EXAMPLE: We are going to be using "pg3" page which has been created in
example 3 of application "WPDI". The page creates a calendar control which we are not
interested in, so we have removed that section. The section we are interested in creates 3
variables, a page, a session and an application variable. It also creates a button which
when clicked, all variables are incremented.
In order to generate an error, we have removed the code section which initializes the
variables by assigning zeros to them and using wm("vs") to store them. This means that
when the user clicks the button and method wm("vg") is called to get the variables, it
will not find them and this should generate an error.
public partial class pg3:master1 {
public override void init() {
base.init();
}
public override void setup() {
base.setup(); // Run setup() of master page first
//----------------------------------- tb3 Contents ----------------------------------
cns="tb3"; // tb3 is made of 1 col, 1 row
cs="bt0";cis="Increment Counters";ds="c"; // button control
fns="trb14";cls="b0y0";wm("i");
}
//-----------------------------------------------------------------------------------
public override void update() {
//------------------------------------ Page Load ------------------------------------
if(cs.Equals("pl")) { // If event is "Page_Load"
/* // *** start of code to be removed
ks="c_a";wm("vg"); // test to see if variable is null
ob=false;if(os.Length<1) ob=true; // Use ob as a flag of being null
if(ob || !IsPostBack) { // If sample was found null for any
ks="c_a";os="0";wm("vs"); // reason or if this was first page
ks="c_s";os="0";wm("vs"); // retrieval, store"0" into all
ks="c_p";os="0";wm("vs"); // 3 var's.
}
*/ // *** end of code to be removed
setup(); // Execute setup()
MakePage(table); // and make page.
PageNumber(3); // Calling master class's method
} // to display this page's number
//----------------------------------- Variable Updates ----------------------------------
if(cs.Equals("bt0")) { // If button clicked
wm("l"); // Add "leave as is" tag to cis
cis+="c_a=";ks="c_a";wm("vg");om("ti"); // Get application var, convert to int
o++;om("fi");cis+=os;ks="c_a";wm("vs"); // increment it,display it,save it.
cis+=" c_s=";ks="c_s";wm("vg");om("ti"); // Do same to session var.
o++;om("fi");cis+=os;ks="c_s";wm("vs");
cis+=" c_p=";ks="c_p";wm("vg");om("ti"); // Do same to page var.
o++;om("fi");cis+=os;ks="c_p";wm("vs");
wm("c"); // Close all HTML tags
cs="lb01";ds="c";wm("sl"); // Display text in (cis)
}
}
}
After saving the modified (pg3.cs) file, generating and running (pg3.aspx), here is what
the browser displayed:
========================================================================================
Server Application Unavailable
The web application you are attempting to access on this web server is currently unavailable.
Please hit the "Refresh" button in your web browser to retry your request.
========================================================================================
So, we have got nothing which can give us a clue about what the source of the error
could be.
Now let us see what our file has received. By typing out [ENTER], we get:
========================================================================================
-------------------- Immediately before the Exception ------------------
i=0 j=0 k=0 ib=False jb=False kb=False ls=ti js= ks=
o=1 of=0 od=0 ob=False ob=False ol=0 oo= oy=0 os=
------------------------------------------------------------------------
C# Exception om("ti"); Input string was not in a correct format.
========================================================================================
This is much better. The bottom line shows the exception generated and the method where
the exception took place. We can easily tell that calling method wm("vg") has returned
the value (os="") and when we tried to convert it to integer using method om("ti"), the
exception was generated since there is no number into (os) which can be converted.
Actually, method wm("vg") must have generated an exception too since the value it was
trying to retrieve was null, except that it has caught the exception and returned (os="")
instead.
As you already know, there are 4 levels of error handling which are:
(1) Level 0: Which expects you to handle the exception by yourself.
(2) Level 1: Which gives you the information you have got in this example.
(3) Level 2: Which gives you a more specified message made by PC# describing the problem
and if it finds no message, it gives the same information as in Level 1.
(4) Level 3: Which gives everything Level 2 gives and additionally it displays all the
methods your program has called since it started and upto the moment the
error took place.
The default Level is Level 2 which is what this example was set for. Method om() did not
have a message for this error, so the error handling defaulted to Level 1.
Now let us change the error level to Level 3. Modify method init() to:
public override void init() {
eri=3;
base.init();
}
and run it again then check the "output.txt" file. Here is what you get:
========================================================================================
wm("i");wm("i");wm("i");wm("i");wm("i");wm("i");wm("dp");wm("i");wm("i");wm("i");
wm("i");wm("i");wm("i");wm("i");wm("i");wm("i");wm("i");wm("i");wm("i");wm("sl");
wm("l");wm("vg");om("ti");
-------------------- Immediately before the Exception ------------------
i=0 j=0 k=0 ib=False jb=False kb=False ls=ti js= ks=
o=1 of=0 od=0 ob=False ob=False ol=0 oo= oy=0 os=
------------------------------------------------------------------------
C# Exception om("ti"); Input string was not in a correct format.
========================================================================================
This should help more since it allows you to see the execution sequence upto calling the
method which has generated the exception.
Additionally, you could have inserted at any location of the program calls to method
wr() or wrln() to display the value of any variable which could tell you what causes the
error.
COMPILATION ERRORS:
-------------------
The ASP.NET contains its own compiler. It could be similar to the standard compiler, but
not exactly the same. Normally when it finds a compiling error it displays to you the five
lines of code which include the error and lets you know the number of the line where the
error has occured. This works fine in some cases but not all. When it does not work right,
it makes your debugging job extremely hard. Let us have an example.
Example 6 of WPDI draws two objects dynamically, one of them is a jewel the other one is a
group of shapes. We are going to modify its code in order to cause a compiling error as
follows:
(1) Remove a semicolon any where in the code of "pg6.cs" file then run the page using your
browser. You'll get a helpful message indicating where the problem is.
(2) Now Remove a semicolon any where in the code of either "jewel.cs" or "shapes.cs" file.
Run the page and see what happens. No errors displayed and the page shows up without
the drawings. When ASP.NET discovered the compiling error, it has just neglected your
drawing file leaving you with no clue of what went wrong.
AND THIS IS OUR SOLUTION FOR THIS PROBLEM:
------------------------------------------
Use your standard compiling tool "pcl" which uses the standard C# compiler to generate a
"dll" file and places it at the same directory as the source file. We know that you have
no need for the "dll" file, but if there were any compiling errors in your source file,
you'll know it. You'll also know the line number and the char order where the error is
located. You can then use tool "ln" to see your error line with 10 lines above and
10 lines below. You may then delete the "dll" file which you have no need for.
For the files "jewel.cs" and "shape.cs", you are going to have no problem when you use
tool "pcl". However, you need to do two adjustments to file "pg6.cs" before using the tool.
The two needed adjustments are:
(1) Since this class extends master1 class, you need to state where that class can be found
The way to do so is to place the commented statement "//assembly Bin\master1.dll"
above the class declaration statement. The "Dsktop PC# Reference" has discussed this
subject in more details.
(2) The statement "MakePage(table);" located at the "Page Load" section of method update()
must be temporarely commented since the standard compiler will complain about the name
(table). The name (table) in "pg6.cs" matches the name (table) used in file "pg6.aspx"
to indicate the ID of the table which contains the page. Only the ASP.NET compiler
can understand what that mean, the standard compiler cannot. Remember to uncomment the
statement after compiling the file.
This is how the file "pg6.cs" should look like before using the tool:
========================================================================================
//assembly Bin\master1.dll; // master1.dll location declaration
public partial class pg6:master1 {
// ******** Keep all code the same from here down *************
public override void update() {
if(cs.Equals("pl")) {
// ******** Keep all code the same from here down ********
// MakePage(table); // Comment this statement temporarely
}
// ******** Keep all code the same from here down ********
}
}
========================================================================================
To use the tool, from command mode type: pcl pg6 [ENTER].
If the error message says that the error line number was (n), type ln n [ENTER] to
display the block where that line is.
========================================================================================
JAVASCRIPT
==========
This section describes some of the technical matters in handling JavaScript by PC#. This
information improves your understanding of what goes on when you call PC#'s methods to
perform JavaScript operations. You should have studied all the JavaScript examples and also
looked at the JavaScript section of "PC# methods" before you read this section.
PC# support for JavaScript:
===========================
PC# helps you in simplifying your JavaScript code and sending your code to the browser by
doing the following:
(1) It sends a PC# script file to the server which contains pre-defined variables and methods
(in JavaScript) which are very much the same as the ones at the server except that they
are fewer and not as capable.
(2) Can receive a script file from your program and send it to the browser. The file is
placed at the top of the page next to the PC# script file.
(3) Can receive any number of script code blocks from your program and send them to the
browser to be executed whenever a condition which you specify is met.
The PC# JavaScript file:
========================
General Use Variables (GUV's):
------------------------------
Most of PC#'s General Use Variables (GUV's) available for C# are also available for JavaScript.
The GUV's declared in JavaScript are:
i,j,k,o, ic,jc,kc,oc, id,jd,kd,od, is,js,ks,os, ib,jb,kb,ob, of,ol
REMARK: In C#, we replaced (if,is) with (lf,ls) since (if,is) have been C# keywords. In
JavaScript we don't have this difficulty since we don't define the float number (if) and (is)
is not a keyword.
Predefined "1-char + type" var's: x,y,n xs,ys,cs,ds
---------------------------------
Predefined "2-char + type" var's: cls,fns,urs,ims,cis,cus,ers,plb,ieb
---------------------------------
Arrays: OS,CUS,IMS
-------
Object reference variables:
---------------------------
dtp (Present Date), wnp (Present Window), wna (Container window), cnp (Present Control)
Internal use variables:
-----------------------
There is no way to declare a variable as "private". So you need to know about these ones
in order to avoid duplicating them.
ffs,fsi,fws,fss,tds, lvb,itb,fnb,blb,cnb,unb, tmi typs,typ,
RD,GN,BL,CLI,IMO,IMI,IM0,IM1,IM2,IM3,IM4,IM5,IM6,IM7,IM8,IM9
DETERMINING THE BROWSER USED:
-----------------------------
The boolean variable (ieb) is the "Internet Explorer Flag". At the start of the page, PC#
script software examins the browser available. If it finds that it is the Internet Explorer
it makes the assignment (ieb=true) You should use this flag to determine which code is
necessary whenever different browsers expect different code.
Setting the color of a control:
-------------------------------
Function cm() at mode "sc" sets the foreground color and at mode "scb" sets the background
color. The color code supplied to the function is expected to be a PC# 2-char or 3-char
color code assigned to cls. The 3rd character which represents opacity is neglected except
for the label and table controls which can be either fully transparent or fully opaque.
The color code is converted to a hex code before the color is set. If you assign a valid hex
code for a color to (cls), the function can also accept it. Method om() can help in converting
between integer and hex formats.
Setting the font of a control:
------------------------------
Function cm() at mode "sf" sets the font. It expects a valid PC# font code assigned to fns.
Before the setup takes place, the font code is supplied to a method which analyzes the font
code and outputs the following internal variables:
ffs=font family, fsi=font size, fws=font weight, fss=font style, tds=text decoration
Method cm() uses those variables to set the font for the control.
THE PAGE "onload" EVENT:
------------------------
An event must be handled by one script function only. PC# needed to handle the page's
"window.onload" event in order to perform some internal jobs. We know that you may need to
do the same so we inserted this statement within the PC# function which handles that event:
if (plb) pl();
If you are using your own script file and you have a block of code which must run when that
event is raised, place the following script at the top of the page:
plb=true;
function pl() {
// Place your code block here.
}
This way your code block will be executed when the "window.onload" event is raised.
Although this method can work in all situations as long as the "JavaScript level (jsi)" is
not set at zero, you need to do that only if you are using a script file for your code.
If you are using method wm("js") to execute your code block, just assign "pl" to both
(cs) and (ks) and the method will do the job for you.
USING YOUR OWN JAVASCRIPT FILE:
===============================
The file name must use the extension "js". You should either place it into the application
folder or use its full path name. You can also use a URL instead of a file name. The file
name or the URL should be assigned to (fls) before calling wm("jf").
SENDING A SCRIPT BLOCK:
=======================
Method wm() at mode "js" sends a block of JavaScript code to the browser, but this is only
part of what it does. Before it sends your code, it analyzes your code and the values
assigned to (cs,ks,i,j) to determine what it should do. Here are some scenarios:
(1) If it finds that you have supplied (cs=ks="pl"), it knows that you want to run your
script whenever the page's onload event is raised. Therefore, it adds (plb=true;),
inserts your code into function pl() as explained above, then places the script at
the top of the page.
(2) If it finds that you have assigned a value to (i), it creates a function around your
code and makes it repeat itself each (i) milliseconds.
(3) If it finds that you have assigned a value to (j), it makes the necessary adjustment
to the function so that the animation stops after the specified number of repititions.
(4) If it finds that your script contains an AJAX call, it also makes the necessary
adjustments in order to set your code to the specs of the AJAX handling method at the
browser. More details are available under the title "AJAX CALLS".
(5) If it finds that your script should run whenever an event takes place on a specific
control, it sets the event and the code as an attribute for that control.
THE JAVASCRIPT LEVEL:
=====================
The integer value (jsi) is the JavaScript level. Its default value is 1. If you are a
professional in JavaScript and like to use your own JavaScript file and feel that the PC#
script file contents are causing you problems, make the assignment (jsi=0) into method
init(). This will prevent class pasp from sending the PC# script file to the browser.
At level 0, you can still use method wm() at modes "jf" and "js" to send your script file
and/or any script blocks as normal.
One question which you may ask here is "if my code was accompanied with the assignment
(cs=ks="pl") while (jsi=0), what would method wm("js") do? The answer is that it will
modify your code to:
window.onload="Your code";
AJAX CALLS:
===========
AJAX browser to server calls can either use method "GET" or method "POST". The data sent
using method "GET" is limited to 500 bytes. For this reason we use method "POST".
When you use wm("js") to send a script block to the client for you, the method checks to see
if your code includes an AJAX call. If it does, it splits your code block into two pieces:
(1) The part which starts at the beginning of the code block and ends by calling cm('ja')
(2) The rest of the code which includes what to do with the data received from the server.
The second part is inserted into a function named ajaxHandler() and placed as a seperate
script at the top of the page.
The AJAX call can be either synchronous (jb=false) or asynchronous (jb=true) If it was
asynchronous, function ajaxHandler() is called after making the AJAX call. If the call
was synchronous, the function is executed when the server data becomes ready.
If you are using a script file instead of script blocks sent to the browser using wm("js"),
you need to do the code seperation on your own.