HTTP
Tunnel and Redirector
Skin Directories
params.txt and GIFs
The
imagejar
Skins.txt
"Help
with this Droplet"
Dripline CGI
Troubleshooting
The
Droplets Platform uses a Web server to serve image and parameter files
to its client-side GUIs. Droplets can interoperate with any Web server
to this end, but in order to use the Droplets Platform HTTP
Tunnel (and thus communicate over port 80) or Redirector
you need to use either the Apache or IIS Web server.
Droplet
creates an apache directory
upon installation with the files outlined below. You'll find it in your
Droplets SDK installation at DropletsSdkx.x/apache. This
directory contains several files which you will need to place in your
apache Web server directory as outlined in the table below:
| Directory | Description | Instructions |
| droplets\apache | Apache server conf file for the Droplets Server (droplets.conf). | Put this file into your Apache server's configuration directory, and add an include for it in httpd.conf. |
| droplets\apache\lib\perl | HTTP Tunnel (HttpTunnel.pm) and Redirector (Redirector.pm) files | Put all files contained within lib/perl into the Apache server directory where your Perl modules are stored, maintaining the "droplets" and "Apps" sub-folders. |
| droplets\apache\htdocs | ZIP files necessary to run Droplets as applets. The files are named dropletclient.zip and droplet-components.zip. | Place into your Apache directory's documents root, which is usually called htdocs. |
| DropletSupport\Images | Application-independent images served by the Droplets Server (for instance, the Droplets logo and the "loading" image. |
Place
these files in $APACHEDOC_ROOT\
DropletSupport\Images
|
In addition, the following Apache sub-directories should be defined,
and the files below (which your developers will write for their applications)
placed into them:
| File Type | Description | Instructions |
| imagejars | Zip files that serve as imagejars for each hosted application. | Place into your Apache directory's documents root, which is usually called htdocs. |
Skin image files params.txt Online help files |
Holds Skin files (including the application's params.txt and any GIF files that are served with the skin(s)) and any online help files for the application. |
Create a sub-directory beneath htdocs (or other docroot name) called DropletConfig\apps\AppName for each hosted application. Each application should have a params.txt and a set of image files which are stored here. Online help is optional. |
| AppNameDripline.pm | Desktop alert CGI | Place them in lib\perl\droplets\Apps. There must be one CGI for each Droplet with alerts that you host. |
We go through the necessary permissions settings for each of
these directories in the sections below.
The HTTP Tunnel and the Redirector
The HTTP tunnel (HttpTunnel.pm) is a Perl module that allows the Droplets Server to wrap its protocol in HTTP (in conjunction with the Apache Web server) and communicate over port 80. This is necessary because many Internet users access their Droplets from work behind a firewall which has the Droplets protocol's native port (8194) or other configured ports closed. When there is no firewall (or the firewall is configured to accept connections over port 8194), the Droplets Server and Client speak to one another through a persistent connection over 8194 using the Droplets protocol. When this is not possible, the HTTP Tunnel wraps the Droplets protocol in HTTP and sends it over port 80 via the Web server. The HTTP Tunnel should always be installed on the same machine as its Web server.
The Redirector (Redirector.pm) is a specialized tool for the serving of graphics files (GIFs and JPEGs) to your Droplets when they run as applets. It fetches images from specific URLs on behalf of the Droplets Client, because when running as an applet the Client can speak to only one server.
Upon tar unpacking, the HTTP Tunnel is placed at droplets\apache\lib\perl\droplets. Move the lib\perl\droplets folder, including both of these files, to the Apache Server directory where your Perl modules are stored.
Two separate directories must be in place within your Web server's file structure in order for an application skin to be served, (1) a custom application directory which contains params.txt and (2) an imagejar. In addition, if you're going to serve multiple skins from your Web server, you'll need a separate params.txt directory and imagejar for each of them, plus a skins.txt file with information on all skin directories.
Creating a skin directory
For each application skin that you serve with your Droplets application(s), there must be a corresponding directory that contains the following files:
•
params.txt;
• All GIF files that are to be served as a part of the skin.
By default, these files should be located in a single directory located at: htdocs(or whatever your document root is)\DropletConfig\apps\AppName. If you're serving multiple skins to a single application, you should have a sub-directory for each one of these skins.
Each skin directory must be indicated correctly in the Droplets application's .drp file, which is generated by one of your Web pages; you should therefore make sure that the location of your skin directory matches the imagedir location as defined in your .drp-generating Web page. See Web site Integration for more information on this.
params.txt is a text file that gives the Droplets Client its appearance parameters. For more information on skinning, see the Skinning Droplets document for developers.
Important
note: The entire look and feel of an application GUI is
often determined by params.txt.
Thus, if the Droplets Client fails to retrieve its application's
params.txt file,
the entire application may fail. The Client retrieves its params.txt
from the imagedir
parameter in its application .drp
file. If the Client can't retrieve these skin files, it will display
an error message that the URL cannot be accessed; see
Web Site Integration for
more information on how to set the imagedir
variable.
The imagejar
The imagejar is a zipped version of the Skin directory structure. While it's not strictly required by the Droplets Platform, it is highly recommended because it greatly speeds application performance. Using it, applications fetch all of their graphics files in a single connection (as opposed to one HTTP connection per image).
If you do use an imagejar, you should have one imagejar for each of the skins that you are serving in your deployment, and they must be located in the root directory of your Apache server's docs directory, which is typically called htdocs. The imagejar usually has a descriptive name that associates it with its skin, for example:
wwwroot\purpleskin.zip or wwwroot\appname_purpleskin.zip
depending on whether you're serving one or more Droplets applications.
Important
Note: You can use most standard zip softwares in order
to create your imagejar, but you cannot use Java's JAR
software, as the Droplet Platform will not be able to unzip it.
If you do use an imagejar, you'll still have to have a separate skin directory with the application skins' params.txt file, but there will be no need to store the individual GIFs in the Web server directory.
Skins.txt
In order to serve multiple application skins per Droplets application, a file named skins.txt should be placed in:
htdocs/DropletConfig/apps/AppName/skins.txt
where "htdocs" represents the doc root directory within your Apache Web server installation, and "AppName" represents the "calc" value in the application .drp file (i.e. its name) with which these skins should be associated.
The purpose of skins.txt is to alert the Droplets Platform to the names and locations of each skin directory (more on that in the next section). This file is simply a listing of skin names along with the URL of their params.txt file and the name of its associated GIF file. Each has the format skin name | reserved | skindir | skinjar:
|
Important
Note: the second position of the URL is reserved, and should
be kept blank as shown above.
"Help with this Droplet"
It's possible to include online help with Droplets applications, using either online help generators or written yourself in HTML. When you do use online help with the Droplets Platform, it must be placed in the DropletConfig directory as follows:
htdocs\DropletConfig\apps\AppName\help.html
Important
note:
The root file of your online help must be named help.html
(this name is required and not optional). Many
online help generators like RoboHelp use the .htm
suffix instead of .html.
You'll thus need to change the suffix manually (or employ a redirect
script) before deploying online help with your Droplet.
Dripline
CGI
If your Droplets applications feature Dripline desktop alerts to the client-side even when the hosted application is closed on the client, your Web server will also need to host a Dripline CGI page for each application that uses alerts. See the Dripline documentation for full details on how to write this page; it should have access to the Droplets UI Server's associated database, and be accessible to the client-side polling agents via a RegisterChannel() call in the application logic.
The Dripline CGIs for all of your Droplets applications should be placed in Apache Server directory's Perl module folder.
Important
Note: This location can be over-ridden in the application
logic by passing a different DriplinePollingUrl
string argument to the Droplets API's RegisterChannel
method; you should therefore double-check to make sure that your developers
haven't specified a different location in their application logic
before placing it in its default directory.
Apache Troubleshooting
If you're experiencing problems serving Droplets over your Web server, make sure that the Web server's permissions have been appropriately set for all of the above directories and files. Any additional, custom files included by your developers that are necessary for application functionality must have appropriate Web server permissions set for them as well. If there are additional files, make sure that the Web server is set to accept executables from their directory.