XSCL

Server-side flexibility at design time

[ XSCL Gallery | HTML-Kit Home | Updated on 16-Apr-2001 ]

Contents

Introduction

Web pages tend to use similar code and content over and over, starting with basic HTML document templates and page headers linking main sections of the site to advertisements and advanced dynamic menus. Page templates and code snippets can help a great deal to streamline inserting repetitive code, but overtime you may collect a large number of only slightly different templates making it cumbersome to maintain and use them. Code Wizards are also great tools, but often you may have to use a wizard designed by someone else that doesn't quite address your specific preferences and coding standards.

XSCL aims to provide a language independent method of maintaining a library of highly customizable and programmable snippets or scripts that can be quickly retrieved and tailored on the fly. Its ability to generate multiple pages or versions of content using a single code base, gives it the flexibility found in server-side scripting at the design time. Creating XSCL commands can be as simple as saving a piece of HTML code which requires no experience in script programming. The functionality of these commands can be gradually extended using scripts.

Example 1 -- dynamic templates

You're creating a list of sales contacts in your company. Each entry will display the first name, phone extension and a picture, if available. With XSCL, you would first create a template for a single contact using a regular text/HTML editor. Then indicate which parts of the template will contain variable information, such as the first name and the phone extension. If this template is saved as "contact" you can use it within XSCL by typing following lines, one per contact. Note that Jane does not yet have a picture, but you can teach XSCL commands how to handle such empty fields.

Contact Joe 5556 joe.jpg
Contact Jane 5558
Contact Tom 5559 tom.jpg
Example 2 -- browser specific pages

To get the best out of existing browsers, sometimes you may have to create two or more versions of the same page optimized to specific browsers. Trying to keep the content synchronized in multiple pages can be time consuming, but with XSCL you can create a single command that can generate two versions of the same page. Certain code inside XSCL commands can be blocked out or replaced using simple conditions.

videopage ns
videopage ie
Example 3 -- include multiple files into a single page

You may have to include a file within another file to avoid having to repeatedly enter the same content. XSCL will not only make it easier to embed external files, but it'll also allow you to recursively include one file within another.

Installing the hkXSCL plugin

xscl_actbar.gif (6K)

Before we get into using XSCL, let's make sure that it's properly installed. You must have HTML-Kit Build 290 or higher to use this plugin.

Creating your first XSCL command

As you've seen in examples above, "contact" and "table" are commands in XSCL. These commands are not built-into the XSCL plugin, but implemented by the user. These commands are stored in files with the *.xsc extension under the "HTML-Kit\Plugins\Config\XSCL" directory.

Before getting started, go to HTML-Kit's "Help | About" option and change to the "Program Details" tab. Write down the "Plugins Directory" path and append "\Config\XSCL" to it. For example, if the plugins directory is "HTML-Kit\Plugins" then "HTML-Kit\Plugins\Config\XSCL" is your XSCL directory.

Secondly, we need to add the *.xsc file extension to HTML-Kit because we'll be working on files with that extension. Go to "Edit | Preferences" from the main menu and change to the "File Types" tab. Select the "USER" file (don't uncheck it) and click "Add File Type." Enter "XSCL Files" without quotes and click OK. Enter "*.xsc" without quotes in the "File Type Extensions" field and click the "USER" file to make sure that the newly added file type was saved. Now click "Colorized file types" and enter ;xsc at the end of the "HTML, XML" field. Click OK to go back to the Preferences dialog and click OK again to close it.

We're now ready to create our first XSCL command, which we'll call the "hello" command. It'll simply insert the text "Hello, world!" into the editor.

First start HTML-Kit and open an absolutely empty document (make sure that it does not contain any text or tags). You can do this by holding the SHIFT key down while clicking the new file icon or selecting "File | New Document" menu item. Type "Hello, world!" without quotes and save the file as "hello.xsc" under the XSCL directory. Close the file.

To test your new command, open a new document and change to the XSCL tab on the Actions Bar. Type hello into the command field and press Enter. You should see the text "Hello, world!" inserted into the current document. Maybe it's a simple command, but now you know how to create XSCL commands! Of course you could have typed any other text or HTML tag into the hello.xsc file as well, but we'll get to more advanced XSCL commands later.

Writing XSCL commands using your favorite language

HKScript is the default programming language used in XSCL to create commands. But you can use virtually any scripting language to create commands, including Perl, PHP, Python, Java, Lisp, or any other language that you have an interpreter for. If you have Perl installed on your local machine, you can use perl.exe as the interpreter or php.exe if you have PHP. Simply include #! followed by the executable file name of the interpreter on the very first line in the *.xsc file (similar to the #! line in UNIX scripts).

XSCL command written in Perl

To test this code, save as a file with the *.xsc extension in the XSCL directory (perltest.xsc for example). Then type perltest testing in the XSCL command field.

#!perl.exe

print "Hello, world!\n";
print "First parameter = $ARGV[0]";

XSCL command written in PHP

Note that the -q argument is passed to php.exe to exclude HTTP headers. Following sample assumes that the php.exe file is in the PATH. If not, include the full path (such as c:\php\php.exe)

#!php.exe -q

Hello, world!
First parameter = <?php echo $argv[1] ?>

The rest of this document assumes that HKScript is being used to program commands, since it's the only built-in language, however the same concepts should apply to any other language. Be sure to replace ParamStr[] and ParamCount variables with the equivalent variables in the language being used ($ARGV[] in Perl and $argv[] in PHP, for example. Also note that #if, #endif, #elif and #else lines are only supported in HKScript. Again you can use the equivalent commands in the language you're using.

XSCL commands can take an argument!

Well, the arguments we're talking about here are the parameters passed to XSCL commands. For example, when you typed "hello" above, hello is the command and it did not take any parameters. But in the "contact" example, the contact command took either two or three parameters, depending on whether a picture was available or not. The table command took, at least in the above example, two parameters - the number of columns and rows.

Why are we talking about parameters? We'll be passing additional information to commands using parameters later on, so let's talk about parameters a bit more. Inside the *.xsc file, parameters will be represented using the following code (when using HKScript to write commands):

ParamStr[1]

The number 1 inside the square brackets indicate that the first parameter should be used. Given the following command line (command plus any optional parameters):

Contact Joe 5556 joe.jpg

ParamStr[1] is equal to "Joe" and ParamStr[2] is equal to "5556" and so on. The total number of parameters passed to a command is indicated in the ParamCount variable. In this case, it'll be set to 3 because the contact command took three parameters.

Anything separated by a space is a separate parameter, unless double quotes are used. For example, if the above command line was changed to:

Contact "Joe 5556" joe.jpg

then we have only two parameters, the first is "Joe 5556" and the second is "joe.jpg"

If you need to include a quote as part of a parameter, it must be escaped using the "\" character. For example:

Contact "Joe \"the joker\" 5556" joe.jpg

will become "Joe "the joker" 5556" which is the first parameter.

Back to commands, this time with parameters!

Ready to create your second command? Actually, let's extend the hello command.

Open the "hello.xsc" file from the XSCL directory. Replace the word "world" with the following:

<%=ParamStr[1]%>

so the full line should look like:

Hello, <%=ParamStr[1]%>!

Save the file. Open a new document and type the following into the XSCL command field:

hello joe

Note how it's inserting "Hello, joe!" or whatever the first parameter you've typed for the hello command. "hello mom" would insert "Hello, mom!"

Great! On to the next step...

Oops, what if somebody didn't enter a parameter?

That's right! If you enter the hello command without any parameters, now you'll get an error. This is because the hello.xsc file is expecting a parameter but it didn't find any. Here's the solution, change the following line in the "hello.xsc" file:

Hello, <%=ParamStr[1]%>!

to these three lines:

#if ParamCount > 0
Hello, <%=ParamStr[1]%>!
#endif

We've just programmed the hello command to print the text only if it finds at least one parameter (or technically speaking, more than 0 parameters). Remember that the ParamCount variable contains the number of parameters passed to the command. The "#if" line is used to indicate that the code below it, up to the "#endif" line, should be executed only if the number of parameters is greater than 0. Now when you type the hello command by itself, there won't be an error message, but if a parameter is specified it'll continue to work as before.

Before closing this section, let's add a few more lines of code:

#if ParamCount > 0
Hello, <%=ParamStr[1]%>!
#else
Hello, world!
#endif

See what happens when you type hello by itself. You'll get the text "Hello, world!" because of the "#else" line, which says that if the "#if" line above fails then use the code below the "#else" line.

Why type again when you can include?

If you have a header, a footer or other common piece of text that has to be included in multiple pages, you can place that text in a separate text file and easily include its content into *.xsc files:

<%!c:\banner.txt%>
<%!c:\footer.txt%>

Above code will include the text in the c:\banner.txt file and the c:\footer.txt file into the XSCL command file. Note that included files can also include files, for example the c:\footer.txt file could contain the following code to include the disclaimer.txt file in the current directory:

<%!disclaimer.txt%>

Conditionally including or excluding code

There are cases where you may have to optimize your pages to specific browsers. Rather than maintaining multiple copies of the same page, you can create a single XSCL command file that contain code for different browsers. Parts of that code can be included or excluded while running the XSCL command.

As a test drive, save the following code in a file named videopage.xsc in the XSCL directory:

Code common to all browsers

#if ParamStr[1] == "ns"
Netscape specific code
#endif

#if ParamStr[1] == "ie"
Explorer specific code
#endif

Now you can generate the Netscape specific page by running the command videopage ns or the Explorer specific code can be invoked by running videopage ie. The code shown above can also be written as follows to get the same results:

Code common to all browsers
<% if (ParamStr[1] == "ns") { %>Netscape specific code<% } %>
<% if (ParamStr[1] == "ie") { %>Explorer specific code<% } %>

As you see, the == operator (equal operator) is used to compare the value of ParamStr[1] to either "ns" or "ie" If there's a match, the very next code block starting with { (which is used to indicate the start of a block) and ending with } will be used.

If you have several browser specific code blocks, it can be cumbersome having to type (ParamStr[1] == "..") over and over. Here's one way to reduce the length of the comparison:

<% auto isNS = (ParamStr[1] == "ns"); %>

Code common to all browsers
<% if (isNS) { %>Netscape specific code<% } %>
<% if (!isNS) { %>Explorer specific code<% } %>

The first line compares the first parameter to "ns" and saves the result in a variable named isNS. From that point on, you can use isNS as the condition. The ! operator (not operator) can be used to check if it's not "ns" by using the code !isNS as shown above.

The meaning of <% and %>

<% and %> are used to mark the start and end of sections in XSCL command files that contain scripts. These scripts will get executed by XSCL before serving the final result of a command. The text and code outside of <% ... %> blocks will be passed through without modification.

Lines starting with the # character have special meaning

If # is the first character in a line, rest of that line will be treated differently. For example, if # is followed by a space, rest of that line will be ignored so you can use it to keep comments.

# this is a comment

If # is immediately followed by if, elif, else or endif those lines will act as conditions within the XSCL command file.

#if 2 == 2
Of course 2 is equal to 2, so you'll see this line.
#else
But you'll never see this line in the output.
#endif

Doing more with less code

You've already seen the table command in action. It can generate the HTML code for a table containing the user specified number of columns and rows. Following command will generate a table with 2 columns and 4 rows:

table 2 4

Following code in the table.xsc file does all the work:

<% auto col = 0, row = 0; %>
#if 2 == ParamCount
<table>
<% for( row=1; row<=ParamInt[2]; row++ ) { %>
<tr>
<% for( col=1; col<=ParamInt[1]; col++ ) { %>
<td></td>
<% } %>
</tr>
<% } %>
</table>
#endif

The very first line simply reserves two variables for storing numbers named col and row. These variables are used by the two for commands to create the given number of columns and rows. The second line should be fairly familiar by now, we're simply checking whether the table command received two parameters, the number of columns followed by the number of rows.

Because the 3rd line did not start with a # character and it's not inside a <% %> block, it does not have a special meaning, so it'll simply get passed through to the final output.

Since the two for commands does most of the work, let's examine them closer:

for( row=1; row<=ParamInt[2]; row++ )

It's saying that the row variable, defined at the top as a variable capable of holding numbers, will start at 1 (row=1), and increment one at a time (row++) until it exceeds the value of ParamInt[2] (row <= ParamInt[2]). ParamInt[2] is the same as ParamStr[2] except ParamInt[2] is a number instead of a string of characters (or something that's holding arbitrary text). If you remove the ParamInt[2] from the for command, it could be written as follows to count from 1 to 10:

for( row=1; row <= 10; row++ )

The second for command is the same, except it's dealing with the number of columns instead of rows:

for( col=1; col<=ParamInt[1]; col++ )

So what's happening here? The first for command is going through a loop until it generates the specified number of rows, while the second for loop is generating the specified number of table cells.

Following code can be used to generate a given number of paragraph tags. To test, save the code in a file named paras.xsc in the XSCL directory and run the command paras 5 to generate 5 paragraphs.

#if 1 == ParamCount
<%
auto paragraphs=0;
for( paragraphs=1; paragraphs <= ParamInt[1]; paragraphs++ )
{
%>


<p></p>

<%
}
%>

#endif

Sample commands

Can XSCL really save you time? Let's look at some sample XSCL commands that you could create and use to speedup day-to-day HTML coding.

Beat this table!

Save the following code as fasttable.xsc

#if ParamCount > 0
<table border="1">
<%
auto cells=0;
for( cells=1; cells <= ParamCount; cells++)
{
%>
<tr><td><%=ParamStr[cells]%></td></tr>
<%
}
%>
</table>
#endif

Now simply type fasttable followed by the text you want each cell in the table to contain, and you won't have to enter a single HTML tag. For example, the following line will create a table containing three rows with the specified text:

fasttable "write once" "and" "reuse many times!"

You can modify the above code to create commands to quickly enter multiple paragraphs, images, email addresses, etc. A fastemaillist.xsc command may look like:

#if ParamCount > 0
Contacts: <%
auto address_count=0;
for( address_count=1; address_count <= ParamCount; address_count++)
{
%>
<a href="mailto:<%=ParamStr[address_count]%>"><%=ParamStr[address_count]%></a>&nbsp;
<%
}
%>

#endif

Reference - functions

String and array handing functions

chartoint( <*character> )
Returns the numeric or ASCII value of the character or the first character in the string. Return type: integer. See also: inttochar, strtofloat, strtoint

n = chartoint("A"); // = 65
 
del( <?string OR array> [, <#start position> [, <#number of items> ] ] )
Removes one or more items from a string or an array. If both "start position" and "number of items" parameters are missing, all characters in the string or items in the array will be removed. If only the "number of items" parameter is missing, one item at "start position" will be removed. Return type: integer.

var a1 = new array("a","b","c");
del(a1, 1, 1);
// a1 = {"a","c"}
del(a1);
// a1 = {}

 
floattostr( <#number> )
Returns the floating point number as a string. Return type: string. See also: strtofloat

str = floattostr(45.31);
 
inttochar( <#number> )
Returns the character represented by the number (or ASCII value). Return type: string. See also: chartoint, strtoint

s = inttochar(65); // = "A"
 
inttostr( <#number> )
Returns the number as a string. Return type: string. See also: strtoint

str = inttostr(123);
 
join( [<*separator>, ] <@array> [, <#convert integers to strings>] )
Joins the items in the array into a single string optionally separated by the given separator text. Any integers in the array will be converted to characters, unless the "convert integers to strings" parameter is set to 1. Return type: string.

str = join(",", ary);
 
length( <*string> OR <@array> )
Returns the length of the string or the number of items in the array. Return type: integer.

n = length("text"); // = 4
 
pop( <@array> )
Returns the last item in the array and removes or pops it. See also: push

pop(ary);
 
push( <@array>, <*string> OR <#number> )
Appends the string or the number to the array. See also: pop

push(array1, str);
 
sort( <@array> [, <?comparison function> [, <?user data>]] )
Sorts the items in the array, optionally using an user specified comparison function. If the optional comparison function name is specified, it will be used to sort items in the array. The third parameter can be used to pass a value to the comparison function. Return type: array.

array2 = sort( array1 );
 
sprintf( <*format string> [, <?arguments> [, ...] ] )
Returns a string constructed using a format string and a variable number of arguments. Same as the printf() function, except the constructed string is returned to the caller instead of outputting it. Return type: string. See also: hprint, hsprintf, print, printf

str = sprintf("%s %d", "I'm", 16); // = "I'm 16"
 
strlwr( <*text> )
Returns the lowercase version of the text. Return type: string. See also: strupr

str = strlwr("UPPER"); // = "upper"
 
strtofloat( <*string> )
Returns the string as a floating point number. The string must be a valid floating point number. Return type: float. See also: floattostr

f = strtofloat("99.4");
 
strtoint( <*string> )
Returns the string as an integer. The string must be a valid integer. Return type: integer. See also: inttostr

n = strtoint("78");
 
strupr( <*text> )
Returns the uppercase version of the text. Return type: string. See also: strlwr

str = strupr("lower"); // = "LOWER"
 
subarray( <@array>, <#offset> [, <#number of items>] )
Returns a part of the array. The collection of items in the array starts at the position specified by the offset parameter. The optional length parameter indicates the number of items to include, otherwise every item up to the end will be included. Return type: array. See also: length, substr

array2 = subarray(array1, 5, 2);
 
substr( <*string>, <#offset> [, <#length>] )
Returns a part of the string. The collection of characters in the string starts at the position specified by the offset parameter. The optional length parameter indicates the number of characters to include, otherwise every character up to the end will be included. Return type: string. See also: length, subarray

str = substr("hands", 1, 3); // = "and"
 
unique( <@source array> [, <#case sensitive mode>] )
Returns a new array containing only the unique items in the source array. If the optional case sensitive mode parameter is specified, it should be set to 1 to ignore the case. Return type: array. See also: uniques

var array1 = new array("one", "two", 3, "three", "3", "two");
var array2 = new array();
array2 = unique(array1);
// array2 = {"one", "two", "3", "three"}

 
uniques( <*source string> [, <#case sensitive mode>] )
Returns a new string containing only the unique characters in the source string. If the optional case sensitive mode parameter is specified, it should be set to 1 to ignore the case. Return type: string. See also: unique

var s1 = "abc1bbc32", s2 = "";
s2 = uniques(s1);
// s2 = "abc132"

 

Regular expressions functions

rfilter( <*filter expression>, <@subject array> [, <*options>] )
Returns a new array containing items matching the filter expression. In addition to the option characters described under the rmatch() function, the "-" character can be included in the options parameter to include items that do not match the filter expression. Return type: array. See also: rgather, rmatch

var array1 = new array("one", "two", 3, "three", "3", "two");
var array2 = new array();
array2 = rfilter("t", array1);
// array2 = {"two", "three", "two"}

 
rgather( <*find expression>, <*subject string> )
Returns an array containing matching sub strings in the subject string. Return type: array. See also: rgathers

array1 = rgather("(\\d)", "4 5 6"); // = array1 = {"4","5","6"}
 
rgathers( <*find expression>, <*subject string> )
Returns a string containing matching sub strings in the subject string. Return type: string. See also: rgather

str = rgathers("(\\d)", "4 5 6");
 
rmatch( <*match expression>, <*subject string OR array> [, <*options> [, <@matching sub strings>] ] )
Returns true if there is a match between the regular expression and the subject string or one of the items in the subject array. If specified, the options parameter must contain one or more of the following characters: "i" = ignore case, "m" = multiple lines and "U" = ungreedy mode. An array can be passed as the forth parameter to collect matching sub strings. Return type: integer. See also: rreplace

if( rmatch( "\\d", "55 Mhz") ) { /* found a number */ }
 
rpos( <*pattern>, <*subject string> [, <*options> [, <@array of positions> ] ] )
Returns the location of the first match. Returns -1 if a match is not found. Refer to rmatch() for a list of valid characters for the options parameter. If an array is passed, it will be populated with the starting and ending positions of matching sub strings. Return type: integer. See also: rmatch, rreplace

n = rpos("a", "abca"); // n = 0
n = rpos("a\\Z", "abca"); // n = 3

 
rreplace( <*find expression>, <*replace expression>, <*subject string> [, <*options> [, <#limit> ] ] )
Replaces matching content in the subject string using find and replace regular expressions. In addition to the option characters described under the rmatch() function, the "g" character maybe included in the options parameter to replace all matches. Return type: string. See also: rmatch

str = rreplace("\\d", "*", "55 Mhz", "g"); // = "** Mhz"
 
rsplit( <*split expression>, <*subject string> [, <*options> [, <#limit>] ] )
Splits a string into sub strings according to the split regular expression. Refer to rmatch() for a list of option string characters. The "-" option can be used to exclude empty strings from the returned array. Returns the subject string if the pattern is not found. Return type: string. See also: rgather, rmatch

array1 = rsplit( "\\/", "2/10/2001"); // = {"2", "10", "2001"}
array2 = rsplit( "c", "abcdccef"); // = {"ab", "d", "", "", "ef"}
array2 = rsplit( "c", "abcdccef", "-"); // = {"ab", "d", "ef"}

 
strrepl( <*source string>, <*find regular expression>, <*replace expression> )
[Deprecated] Replaces matching content in the source string using regular expressions. The find expression is a regular expression and the replace expression may use \# to indicate specific matching blocks (# = matched block number). Return type: string. See also: rreplace, strreplall

str = strrepl("ABCA", "A", "a"); // = "aBCA"
 
strreplall( <*source string>, <*find regular expression>, <*replace expression> )
[Deprecated] Replaces all occurrences of matching content in the source string using regular expressions. Same as the strrepl() function, except all matching occurrences are replaced. Return type: string. See also: rreplace, strrepl

str = strreplall("ABCA", "A", "a"); // = "aBCa"
 

File handling functions

faccess( <*file name>, <#access mode> )
Checks the file access mode. Returns true if the specified access is allowed. Valid access modes: 0 = check for file existence, 2 = write permission, 4 = read permission and 6 = read and write permission. Return type: integer. See also: fstat

if( faccess("myfile.txt", 0) ) { /* myfile.txt exists */ }
 
fclose( <?file handle> )
Closes the file associated with the file handle. Returns NULL on error. Return type: integer. See also: fopen
 
fcopy( <*source file name>, <*destination file name> [, <#overwrite mode>] )
Copies the existing source file to the new destination file. If the new file already exists, the function will not copy over it unless the overwrite mode is set to 1. Returns 1 on success. Return type: integer.

fcopy( "file.txt", "newfile.txt" );
 
feof( <?file handle> )
Returns true if the file associated with the file handle has reached its end (end of file). Return type: integer. See also: fclose, fopen
 
fflush( <?file handle> )
Flushes any output buffers associated with the file handle. Return type: void. See also: fclose, fopen, fputs
 
fgetc( <?file handle> )
Returns the next character from the file associated with file handle. Returns NULL on end-of-file. Return type: string. See also: fclose, fgets, fopen, fputc, fputs

while(NULL != (character = fgetc(file_handle))) { /* use "character" */ }
 
fgets( <?file handle> )
Returns a line of text from the file associated with file handle. Returns NULL on end-of-file. Return type: string. See also: fclose, fgetc, fopen, fputc, fputs

str = fgets(file_handle);
while(NULL != (str = fgets(file_handle))) { /* use "str" */ }

 
flength( <?file handle> )
Returns the size in bytes of the file associated with the file handle. Return type: integer.

var f = 0, l = 0;
f = fopen("file.txt", "r");
if(f){ l = flength(f); fclose(f); }
// l = size of the file in bytes

 
flist( <*file path and mask> [, <#file attributes>] )
Returns a list of files in the specified path matching the file mask. The optional file attributes parameter can be specified to limit the number of files and/or directories returned. Return type: array. See also: faccess, rfilter

array1 = flist("*.jpg");
array1 = flist("*.*", 0x00000010); // get a list of directories

 
fmove( <*source file name>, <*destination file name> )
Moves or renames the source file name to the destination file name. If the file name is a directory, both names must be on the same drive. Returns 1 on success. Return type: integer.

fmove( "file.txt", "new_name.txt" );
 
fopen( <*file name> [, <*open mode>] )
Opens the specified file optionally in the given mode. Optional open mode maybe specified using these values: "r" = open for reading only, "w" = create new file for writing or overwrite existing file, "a" = append to the end of an existing file or create new file for writing. Add "+" for update mode. Return type: integer. See also: fclose, fgetc, fgets

var f = 0;
f = fopen("myfile.txt", "r");
if( f ) { /* read the file and close it */ fclose(f); }

 
fprintf( <?file handle>, <*format string> [, <?arguments> [, ...] ] )
Writes a string constructed using a format string and a variable number of arguments, to the file associated with the file handle. Same as the printf() function, except the constructed string is sent to the file associated with the file handle. See also: fclose, fopen, fputc, fputs
 
fputc( <*one character string> OR <#ascii value>, <?file handle> )
Writes the first character in the string or the character represented by the ASCII value to the file associated with the file handle. See also: fclose, fgetc, fopen, fputs

fputc(65, file_handle);
 
fputs( <*string>, <?file handle> )
Writes the specified string to the file associated with the file handle. Return type: void. See also: fclose, fgets, fopen

fputs(str, file_handle);
 
fremove( <*file name> )
Removes the file specified by the file name parameter. Return type: void.

fremove("obsolete_file.txt");
 
fseek( <?file handle>, <#offset>, <#whence> )
Repositions the current read/write location of the file associated with the file handle. The new position is specified in the offset parameter. Whence parameter should have one of the following values: 0 = file beginning, 1 = current position or 2 = end of file. Return type: integer. See also: fclose, fgetc, fgets, fopen
 
fstat( <*file name> )
Returns an array containing information about the specified file. 0 based 2nd item in the returned array = file attributes, 7 = file size, 8 = last access time, 9 = last write time, 13 = long file name, 14 = short file name, 15 = creation time. Return type: array. See also: faccess

aFileInfo = fstat("index.html");
// aFileInfo[7] = file size in bytes

 
ftempname( [<*file name prefix> [, <*file name extension>]] )
Returns the full path to a temporary file name. Both the file name prefix and file extension parameters are optional. The file name extension must start with a period ("."). File names generated using this function should be used only for temporary tasks (within the life of the script/application) Return type: string.

str = ftempname("test", ".htm");
 

HTML and URLs related functions

hprint( <*string> )
Outputs the specified string as a HTML string. Same as the print() function, except following characters in the string are escaped using HTML entities: <, >, " and &. See also: hprintf, htext, print, printf, sprintf
 
hprintf( <*format string> [, <?arguments> [, ...] ] )
Outputs a HTML string constructed using a format string and a variable number of arguments. Same as the printf() function, except following characters in the constructed string are escaped using HTML entities: <, >, " and &. See also: hsprintf, htext, printf, sprintf
 
hsprintf( <*format string> [, <?arguments> [, ...] ] )
Returns a HTML string constructed using a format string and a variable number of arguments. Same as the hprintf() function, except the constructed string is returned to the caller instead of outputting it. Return type: string. See also: hprintf, htext, printf, sprintf

str = hsprintf("%s > %d", "I'm", 16); // = "I'm &gt; 16"
 
htext( <*string> )
Returns the specified string as a HTML string. Refer to hprint() for details. Return type: string. See also: hprint

str = htext("< not html >"); // = "&lt; not html &gt;"
 
hunformat( <*formatted code> [, <#starting token>] )
Returns a string containing the HTML/XML code formatted according to HTML-Kit user preferences. Refer to hkp_c_FormatTag_* constants in the hkpcore.h file for characters used to format the original code. Generally the starting token parameter should be 0. Return type: string.

str = hunformat("<^Tbr^N ^Aclear^N=^Qall^Q>", 0); // = <br clear="all">
 
ugets( <*URL> )
Returns the content at the specified URL as a string. Only http and ftp URLs are supported. Returns NULL on error. Return type: string.

str = ugets("http://localhost");
 
usave( <*URL>, <*file name> )
Retrieves the content at the specified URL and saves to the file name. Only http and ftp URLs are supported. Return type: integer.

usave("http://localhost", "file.txt");
 

Database functions

db_close( <?datasource handle> )
Closes the data source associated with the datasource handle. Return type: integer.

db_close(dbHandle);
 
db_end( <?database result handle> )
Closes the database operation associated with the database result handle. Return type: integer.

db_end(dbResult);
 
db_error( <?datasource handle> )
Returns the last database error and resets it. Return type: string.

str = db_error(dbHandle);
 
db_exec( <?datasource handle>, <*SQL command string> )
Executes the specified SQL command and returns a handle to the result. Return type: integer.

dbResult = db_exec(dbHandle, "SELECT * from MyTable");
 
db_fetch( <?database result handle> )
Fetches a database record and returns true if a row of data was successfully retrieved. Return type: integer.

if( db_fetch(dbHandle) ) { /* successfully loaded a table row */ }
 
db_field( <?database result handle>, <*field name> OR <#field id> )
Returns the value associated with the database result handle and the specified field name or ID. Return type: string.

str = db_field(dbResult, "ProductName");
 
db_fieldcount( <?database result handle> )
Returns the number of fields or columns associated with the database result handle. Return type: integer.

n = db_fieldcount(dbResult);
 
db_fieldid( <?database result handle>, <*field name> )
Returns the field identifier or column number associated with the database result handle and the field name. Return type: integer.

n = db_fieldid(dbResult, "ProductName");
 
db_fieldname( <?database result handle>, <*field id> )
Returns the field name associated with the database result handle and the field identifier. Return type: string.

str = db_fieldname(dbResult, 3);
 
db_info( <?datasource handle> )
Returns any information associated with the last database operation and resets it. Return type: string.

str = db_info(dbHandle);
 
db_open( <*connect string> )
Connects and returns a handle to a database source. The connect string should be ODBC-compatible. Return type: integer.

dbHandle = db_open("dsn=MY_DATA_SOURCE");
 

Misc. functions

abs( <#number> )
Returns the absolute value. Return type: integer.

n = abs(-1); // = 1
 
Alert( <*message text> [, <*title bar text>] )
Displays a message box containing the message and title bar text. Return type: integer.

Alert("message", "title");
 
AppHandle( )
Returns the Windows handle of the current host application. The returned value is a HWND type converted to an integer. Return type: integer.

h = AppHandle();
 
copy( <$variable -- string, array, int or float> )
Returns a new copy of the specified data.

str2 = copy(str1);
 
die( <*message text> )
Generates an error containing the message text and generates an exception or exits/halts the execution of the program/script. This function can be used to raise an exception in try {...} catch {...} blocks. Exceptions that are not handled in such a way will halt the execution. See also: exit

die("out of memory");
 
dllruni( <*DLL file name>, <*function name> [, <?integer or string>] )
Invokes the specified function in the DLL file. This function can be used to invoke functions in user created libraries or Windows functions that take no or one parameter (32 bit integer or pointer to C-style string of character). Returns the value returned by the function or 0. Return type: integer. See also: ExecuteAndWait, WinExec, exec

dllruni("user32.dll", "MessageBeep", 1);
 
equal( <$variable 1 -- string, array, int or float>, <$variable 2> )
Returns true if the first variable is equal to the second.

if( equal(str1, str2) ) { }
 
exec( <*program> [, <#show window> [, <#new shell> [, <@aStdOut> [, <@aStdErr> [, <#show errors> ] ] ] ] ] )
Executes the specified program and optionally collects stdout and stderr streams. If "show window" is set to 0, the program window will be hidden. Setting "show window" to 1 will cause the program to run through a new instance of the command shell (cmd.exe or command.com). Return type: integer. See also: ExecuteAndWait, WinExec, dllruni

exec("notepad.exe", 1);
exec("dir", 1, 1, aStdOut);
exec("mem.exe", 1, 1, aStdOut, aStdErr);

 
ExecuteAndWait( <*program>, <*parameters>, <*starting directory>, <#window show style> )
Executes the specified program and waits for it to finish running. Refer to WinExec() for a list of valid window show styles. See also: WinExec, dllruni, exec

ExecuteAndWait("notepad.exe", "myfile.txt", "c:\\myfiles", 1);
 
exit( [<#exit code> OR <*exit message>] )
Exits or halts the execution of the program/script and returns the specified exit code or the exit message. See also: die

exit(0);
 
getenv( <*environment variable name> )
Returns the value of the specified environment variable. Returns an empty string if the variable is not defined. Return type: string.

str = getenv("PATH");
 
gettime( <*date/time format> )
Returns the current date and/or time according to the specified format. d = day, dd = 2 digit day, ddd = 3 character day name, dddd = full day name, m = month, mm = 2 digit month, mmm = 3 character month name, mmmm = full month name, yy = two digit year, yyyy = 4 digit year, hh = hour, nn = minute, ss = second. Return type: string.

str = gettime("m/d/yyyy") // = "2/9/2001"
 
MessageBox( <*message text>, <*caption>, <#message box style> )
Displays a message box containing the message and title bar text. This function is similar to calling the MessageBox() Windows API function, except the owner window handle is implicitly provided. Return type: integer.

MessageBox("message", "title", 1);

// Yes/No prompt
if( 6 == MessageBox( "Exit?", "Confirm", 4 ) )
{ /* Yes */ }

 
print( <*string> )
Outputs the specified string. See also: hprint, hprintf, printf, sprintf
 
printf( <*format string> [, <?arguments> [, ...] ] )
Outputs a string constructed using a format string and a variable number of arguments. The format string is similar to the first parameter passed to printf() functions in the C language. See also: hprint, hprintf, hsprintf, print, sprintf
 
putenv( <*environment variable name>, <*new value> )
Sets the specified environment variable to the new value. Returns 1 on success. Return type: integer.

putenv("MY_PATH", "c:\\temp");
 
typeid( <$variable> )
Returns the variable type name. Return type: string.

if( "string" == typeid(str) ) { /* this is a string variable */ }
 
use( <*DLL file name> [, <*namespace>] )
Provides easy access to functions defined in the DLL file. If a path is not specified, the HTML-Kit\Plugins\Lib path will be checked first. If a namespace is specified, new functions can be access using that name, followed by a period and the function name. Returns 1 if the DLL is successfully loaded. Return type: integer.

if( use("MyHKSLib") ) { MyHKSLib.newfunc(); }
if( use("MyHKSLib.dll", "XYZ") ) { XYZ.newfunc(); }

 
uudecodef( <*uuencoded input string>, <*output file name> )
Decodes the uuencoded string and writes to the specified file name. Returns 1 on success. Return type: integer. See also: uuencodef

uudecodef(str, "new.gif");
 
uuencodef( <*input file name> )
Returns an uuencoded version of the content in the file as a string. Returns NULL on error. Return type: string. See also: uudecodef

str = uuencodef("picture.gif");
 
WinExec( <*command line>, <#window show style> )
Runs the application specified in the command line. This function is similar to the WinExec() Windows API function. The window style parameter specifies how the application window should be shown: 0 = hide, 1 = normal, 2 = minimized and 3 = maximized. Return type: integer. See also: ExecuteAndWait, dllruni, exec

WinExec("notepad.exe", 1);
 

XSCL Gallery

Looking for more samples and ready-to-use commands? Checkout the XSCL Gallery.

Questions?

Please use the htmlkit.plugins newsgroup to post comments, corrections and questions related to this article.



Copyright (C) Jan-2002, Chami.com. All Rights Reserved.