p2gChinchilla™ is a FREE, very small (3.5 MB) HTTP
presentation server for the Microsoft Windows OS. It requires no
installation and does not mess with the registry or other system
settings. For beginners, p2gChinchilla™ is an ideal server
to test small web sites locally. More advanced web programmers use it as
a runtime for HTML applications and presentations, e.g. as a
“quick and dirty” alternative to Adobe AIR.
p2gChinchilla™ essentially requires no configuration - just
dump all files in the directory where the server binary lives and they
are served from there.
Entry-Level Local Test Server
If you're just starting out with HTML, CSS, and JavaScript programming,
you might need an easy solution to test the functionality of your new
web site locally. However, if you're still shying away from the learning
curve of setting up a production server like Apache,p2gChinchilla™ can help! First, download
p2gChinchilla™ and unpack the archive. Create a new
folder anywhere on your system and copy p2gChinchilla.exe
there. Lastly, start the program. p2gChinchilla™ disappears
into the Windows notification area (system tray) but opens a window with
the server documentation. For now, iconize the documentation
window; you can look at it later. Just don't close it, as this would
kill the server. Then open your text editor and create two HTML files
named test1.html and test2.html like this:
The folder where the p2gChinchilla™ binary lives is always
your SERVER ROOT. Move the file test1.html to the directory
containing p2gChinchilla.exe and point your browser to the
address http://127.0.0.1:50000/test1.html. Your web browser
should now show "HELLO FROM FILE NO. 1". Create a new folder under the
server root directory and name it TEST. Move the file
test2.html to the newly created TEST folder
and browse to the address
http://127.0.0.1:50000/TEST/test2.html. What do you see?
After this super-mini tutorial, the relationship between the server root
on the local file system and the http://127.0.0.1:50000/
web address should be clear, right? BTW, this would be a very good time
to look at the documentation…
<TOP>
Setting start page and directory index
(…) After looking at the manual, quit
p2gChinchilla™ by closing the documentation window, or you
can click the tray icon and close the server window. Open the file
p2gChinchilla.ini (in the _p2gChinchilla
folder) in your text editor. Locate the [BrowserWindow]
section. A setting of UseBrowser=YES makes
p2gChinchilla™ open its built-in Internet Explorer window
on startup. UseBrowser=NO opens the user's default system
browser.
Now look at the [Server] section: If you change the
StartPageURL setting to /TEST/test2.htmlp2gChinchilla™ will open file #2 next time it's run. If you
enter only a / the server will start with a file list of
the server root directory. However, renaming test1.html to
index.html will use file #1 as a directory index instead of
the yellow list. Lastly, if you delete the StartPageURL
setting alltogether and set UseBrowser=NOp2gChinchilla™ will quietly disappear in the system tray
and be ready to serve a document when you open your browser and
enter an appropriate http://127.0.0.1:50000/... URL.
<TOP>
Browser-Based HTML Presentations
HTML, CSS, JavaScript, and RIA tools like Open Laszlo are well
suited to make impressive stand-alone DHTML presentations, e.g. a
product documentation or an intro for a CD/DVD. Many tools for the
creation of great looking HTML pages without coding are available to
designers - even office software worth its salt, e.g. OpenOffice.org can
output HTML pages.
However, especially under MS Windows, there a few pesky problems with
this: Usually, the end user must locate the start page in the file
system, open the browser manually and point it to the start page. The
designer or programmer must take great care to reference pages and
includes in code, because it is not necessarily clear what the document
root on the end user's machine might be. A lowly space
character in the pathname can render the links in a presentation
useless. And Internet Explorer just seems to love ruining the
coolest presentations with scary safety warnings, just because there is
a Flash applet somewhere on a page…
By comparison, putting together an app or a browser presentation with
p2gChinchilla™ is a snap: First, download
p2gChinchilla™ and spend a few minutes to get acquainted with the product. Then, create
your content under the server root directory and test as you go along -
just like you would building a small web site. Lastly, open the
configuration file /_p2gChinchilla/p2gChinchilla.ini in
your text editor, enter the StartPageURL to your first HTML
page, and set UseBrowser=NO – and you're off to the
races!
<TOP>
Starting p2gChinchilla™ starts your application
From now on, starting the p2gChinchilla™ server will
automatically open the default browser (which is not
necessarily Bill Gates' Internet Explorer) and load your HTML page. This
is perfect for a CD/DVD intro, because the p2gChinchilla™
binary is easily referenced in the CD's or DVD's
autorun.inf file. No installation, no guesswork about
paths, no batch files, no registry dust - starting
p2gChinchilla™ starts your app! Here is an
autorun.inf example for a p2gChinchilla™
application in the folder D:\mykillerapp on CD:
[AutoRun]
label=My Killer Application On CD
icon=mykillerapp\_p2gChinchilla\img\p2gChinchilla.ico
action=Start My Killer Application!
open=mykillerapp\p2gChinchilla.exe
There are a few refinements you can make to the basic setup above. For
example, you can rename the p2gChinchilla™ executable to
something like My Killer App.exe which might be more
meaningful to your end users. Using an icon/resource editor like IcoFX you could swap the
original p2gChinchilla™ executable icon for an icon of your
own and reference this icon in the <head> section of
your pages as a shortcut icon, to further polish your handiwork.
Furthermore, placing all your content in a subdirectory under the server
root will leave My Killer App.exe as the only file in the
installation folder, to further illustrate where the user must click to
start your app.
<TOP>
Terminating the server when users browse away from your app
Consider incorporating JavaScript code in your pages to terminate
p2gChinchilla™ when the user closes the browser or
navigates away from your pages, e.g.
<head>
<script type="text/javascript">
onbeforeunload = function() {
var answer = confirm("Keep p2gChinchilla running?");
if(answer) {
// Returning anything here will pop an ugly,
// canned dialog box in most web browsers!
return;
}
else {
// The script returns "204 No Content", so you won't
// notice anything - p2gChinchilla will just die quietly:
location.href = "/_p2gChinchilla/cspl/csplKillServer.cspl";
}
};
</script>
</head>
The file csplKillServer.cspl is a special little CGI script
to take down p2gChinchilla™ whenever it's loaded in the
browser. It's always a good idea to ask for confirmation before killing
off the local server, because with the full-featured system browser, the
user could go anywhere on the net. If the user clicks the Back
button later, s/he should be aware that s/he terminated
p2gChinchilla™ and the local app will not function anymore.
<TOP>
Serving a Windows HTML Application (HTA)
For those of you who like to program Windows HTAs, the
p2gChinchilla™ server makes a ShellExecute
call instead of offering the HTA file for download, whenever
StartPageURL is set to a HTA. With this feature, you can
harness the power of p2gChinchilla's Perl 5.10 interpreter from your HTA
without having to worry about installing Perl script on the user's
machine. The small drawback of using this technique is, all URLs in the
HTA have to be absolute whenever p2gChinchilla™ has to
participate in the action. To overcome this, use the HTA only as a
“wrapper” to get a custom window and quickly load a HTML
page into it. Check the _p2gChinchilla/doc folder for a HTA
sample wrapper. The script below can close your HTA window when the user
kills the server with the system tray icon:
<!-- Import p2gChinchilla's AJAX library: -->
<script src="/_p2gChinchilla/cspl/ajaxCSPL.js" type="text/javascript"></script>
<script type="text/javascript">
//
// Poll p2gChinchilla every 1.5 seconds:
//
var pollingInterval = 1500;
var cgiScript = '/_p2gChinchilla/cspl/csplProductVersion.cspl';
//
setInterval(function() {
csplAjaxRequest(serverIsAlive, cgiScript);
}, pollingInterval);
//
// AJAX callback function to close the app:
//
serverIsAlive = function(strAnswer) {
if(strAnswer.indexOf('Chinchilla') == -1) {
close();
}
}
</script>
This “stupid” little trick works remarkably well in most
situations and beats tying yourself in knots getting a window handle and
trying to close a “non-owned” window. Naturally, you can
poll p2gChinchilla™ more often than 1.5 seconds, but I
wouldn't overdo it. Not everybody has a fast processor, so it's prudent
to keep the server from frantically spinning its wheels.
<TOP>
“Real” Windows Applications With Perl CGI And AJAX
What really sets p2gChinchilla™ apart from other great
presentation servers you may find around the web is the concept of starting a browser or opening an HTA
window together with the server. Taking this idea one step further,
I recently endowed p2gChinchilla™ with a fully customizable
window hosting Internet Explorer as an ActiveX control. With this
feature, you can make your humble HTML app “pose” as a
“real” Windows program. This can be a viable, time-saving
alternative to VisualBasic or Adobe AIR development, especially if you
already have an existing RIA or (D)HTML pages from your web site for the
user interface.
From a user perspective, s/he starts a “real” executable,
which opens an appropriately titled window. Any shortcuts to the
application binary can show an application icon of your chosing,
not Adobe's. By utilizing a small (but extensible) AJAX API, you can
make p2gChinchilla™ open Windows common dialogs and message
boxes instead of canned JavaScript alerts. Lastly, the
p2gChinchilla™ Perl 5.10 interpreter lets you run CGI
scripts that make your HTML or Flash application as powerful as any
“real” Windows program.
To get started, download
p2gChinchilla™ and get
acquainted with your new server. Then, create a
browser app as shown above. Open
/_p2gChinchilla/p2gChinchilla.ini in your text editor, set
StartPageURL in the [Server] section to your
first HTML page, and customize the [BrowserWindow] and
[ExitMessage] sections. Each setting is well commented and
no further instructions are necessary. Just remember,
p2gChinchilla™ “owns” this browser window, so
you can't use JavaScript to manipulate it, and you don't have to worry
about taking it down when the user quits. Perhaps the most useful
settings of the new browser window are InnerWidth and
InnerHeight which make the window fit your application like
a glove.
As a finishing touch, rename p2gChinchilla.exe to whatever
name you like; it doesn't care what it's called. Also, use a resource
editor like the one in the award-winning IcoFX freeware icon editor to swap the icon in the
server binary for the one used in your application. Now start
p2gChinchilla.exe and – presto – there's your
very own “real” Windows application! If you like you can download the
p2gStereoStage™ stand-alone app (includes the full
p2gChinchilla™ binary) for a real world example of how
convincingly p2gChinchilla™ can “fake” a
Windows application with HTML and Flash.
<TOP>
OpenLaszlo Stand-Alone App Tutorial
OpenLaszlo is a
phantastic tool to easily create Rich Internet Applications. Wouldn't it
be great if you could take your OL RIA and run it as a local MS Windows
application? There are ways of doing this already (e.g. Adobe AIR). In
this tutorial, however, I'll show you a different approach: We'll create
a trivial OL Flash app and host it on a synchronized
p2gChinchilla™ HTTP server listening on a local loopback
address. There are some advantages to this over other methods:
Your finished application does not require a specific runtime (e.g.
AIR). Every component needed is already installed on your user's machine
– especially if you deploy your OL SOLO app to DHTML.
No install procedure is required. Your user only unzips the app archive
and double-clicks an .EXE file. If you deploy to DVD, you can start your
app with autorun.inf - your app runs straight off the DVD.
No registry dust in either case.
Only a tiny learning curve for you. You already know 99% of the required
tasks like the back of your hand. Basically, you're designing a
“mini web site” with OL's HTML wrapper as the only page.
Your “mini web site” is hosted by
p2gChinchilla™ which takes care of the rest. Customizing
the server to “fake” a Windows app is a matter of 5 minutes
max., because p2gChinchilla™ was designed to do just that.
No guesswork about paths and file locations on the user's machine. You
create whatever directory structure you need under the server root (the
folder with the p2gChinchilla™ binary). System paths are
available through the server's environment variables.
Your app looks and feels like a real compiled MS Windows binary. The
server consists of only one .EXE file, which you can rename to your
liking. You can even swap the server icon with a resource editor, so
shortcuts created later by the user have your application icon. The app
window is native to Microsoft Windows, and you can use common Windows
dialogs and message boxes.
Your application can use the full power of the Perl 5.10 interpreter
inside p2gChinchilla™ to accomplish whatever task you can
dream up.
<TOP>
Creating the OL application
Did I get you all fired up with these advantages? Great! Let's start
by making a small OL app. I will keep this deliberately simple to
illustrate the principles. Our app will open a Windows "File Open"
dialog and let the user select a text file from the local file
system. The pathname of the text file is then returned to OL. Here we go:
<canvas>
<!--
// (1) Use p2gChinchilla's AJAX library and
// instantiate an ajaxCSPL object:
-->
<include href="ajaxCSPL.lzx"/>
<ajaxCSPL id="server_ajax"/>
<view width="100%" height="100%">
<view
x="${parent.width / 2 - this.width / 2}"
y="${parent.height / 2 - this.height / 2}"
>
<simplelayout axis="x" spacing="15"/>
<image src="OL_CH_Logo.png"/>
<view>
<simplelayout axis="y" spacing="15"/>
<text width="370" multiline="true">
This program demonstrates how to create a simple
Windows<br/>application with OpenLaszlo and the free
p2gChinchilla server.<br/>Clicking the button will
bring up a Windows "File Open" dialog<br/>and return a
value to OpenLaszlo:
</text>
<view width="${result_text.width}" height="5" bgcolor="red"/>
<text id="result_text" fontstyle="bold">
<!--
// (2) Implement a callback function for
// server_ajax.csplBrowseForFile():
-->
<method
name="callbackMethodForChinchilla"
args="strText"
>
result_text.setAttribute('text', strText);
</method>
Path to a file appears here...
</text>
<view width="${result_text.width}" height="5" bgcolor="red"/>
<button text="Open File">
<handler name="onclick">
//
// (3) Declare the port number where the server will be
// listening for AJAX requests from our application:
//
server_ajax.csplPort = '50000';
//
// (4) Tell p2gChinchilla to open a standard Windows "File"
// dialog box for us and report the user's choice to the
// result_text.callbackMethodForChinchilla() method:
//
server_ajax.csplBrowseForFile(
result_text.callbackMethodForChinchilla,
'OPEN',
'Open File For OpenLaszlo:',
'C:/',
'',
'Text Files',
'*.txt;*.text'
);
</handler>
</button>
</view>
</view>
</view>
</canvas>
STOP! Before you rush to compile this source code in
your OL environment, you need to get a hold of p2gChinchilla's
ajaxCSPL.lzx library (comment #1) and place it in your OL
app directory. If you haven't done so already, download and un-rar
the server package. Then run p2gChinchilla.exe at least
once - don't worry about the documentation right now, just close it. On
first run, the server creates a directory named
_p2gChinchilla in the binary's path. In this folder, there
is another one named cspl, where you'll find the
ajaxCSPL.lzx library. For a bit of polish, right-click the
logo on the left and save it to your OL app directory, too. Now create a
new source file named MyKillerApp.lzx with the above code,
compile it to SWF 9 (!!!) and SOLO-deploy the sample app. For
neatness, create a subdirectory named OLAPP next to the
p2gChinchilla.exe server binary and move the unzipped OL
output there.
Believe it or not, this was the hardest part! You can now run a first
test. Run p2gChinchilla.exe and iconize the documentation
window - don't close it! Open your web browser and go to
http://127.0.0.1:50000/OLAPP/. Click on your
HTML wrapper page MyKillerApp.lzx.html - the app should
run. Before we move on, a few explanations about the source code
are in order:
Right below the comment #3, there is a line that reads
server_ajax.csplPort = '50000'. This is the
port on which the server is listening for requests from our app. Each
application should have its own port number, so they don't interfere
with one another, and port numbers should be in the 49152 to 65535
dynamic range. In the file _p2gChinchilla/p2gChinchilla.ini
you can change the port setting as needed. Comments #2 and #4 illustrate
the general principle how OpenLaszlo and p2gChinchilla™
communicate. OL makes a AJAX request to the server, which executes a CGI
script, which in turn funnels its output back to a callback function in
the OL app. Easy, simple, and efficient enough for most applications.
<TOP>
“Faking” The Windows Application
Now it's time to turn our “mini web site” into a stand-alone
application. We do this by simply editing the
p2gChinchilla.ini setup file in the
_p2gChinchilla directory – that's all it takes! Open
the file in your text editor and locate the [Server]
section. Set the StartPageURL to your
/OLAPP/MyKillerApp.lzx.html application wrapper. Look
further down at the [BrowserWindow] section and make sure
UseBrowser has a setting of YES. Unlike other
presentation- or test servers you may find around the Internet,
p2gChinchilla™ comes with its own web browser window, which
can be fully customized in the [BrowserWindow] section of
the server setup file. As you can see, the file is well commented
– so go ahead and tweak the settings to your liking, but don't
forget to save Chinchilla.ini when you're done.
Now restart p2gChinchilla™ and admire your finished
application. Even reading this long tutorial sermon, it should not have
taken longer than a few minutes to this point. Please note, if you did
not compile to SWF 9 as told above, you will probably get all
kinds of JavaScript errors. This is due to the shoddy auto-generated
HTML wrappers from OL and has, of course, nothing to do with the
p2gChinchilla™ server! Naturally, you can deploy to any
runtime, you just have to create your own, clean wrapper pages.
<TOP>
Adding The Finishing Touches
Your work is almost done. Change the name of the
p2gChinchilla™ binary to whatever you like –
p2gChinchilla™ doesn't care what it's called. Lastly, use a
resource editor like the one in IcoFX to add your own application icon to the
executable. And there you have it: A pretty convincing MS Windows
application in no time flat! Please remember, the use of
p2gChinchilla™ is FREE for non-commercial projects only. If
you're using this for a job, I'd like to hear from you. Happy coding!
STOP! Before you rush to compile this source code in
your OL environment, you need to get a hold of p2gChinchilla's