This documentation is a work in progress, but should be enough to get you started. We just want to get the source code into your hands as soon as possible!
Hemlock is a framework for building real-time, multi-user web applications. It combines the speed and scalability of XMPP with the real-time connectivity and UI robustness of Flash. Read more about it on our blog.
Before you being developing with Hemlock, you'll need to set up a few things on your computer. This documentation is geared towards OS X and other Unix-based systems. Windows documentation is in the works, and has been discussed in our Google group.
First, download the free Adobe Flex SDK.. The Flex SDK is bundled with:
mxmlc: Command-line utility for compiling ActionScript into
a SWF file.fdb: Command-line utility for tracking debug messages
during SWF runtime.
After downloading the SDK, simply unarchive it, and move it to a location
like /usr/local/flex_sdk_3. Next, set the following environment
variables (in your ~/.profile or Unix equivalent):
export PATH=/usr/local/flex_sdk_3/bin:$PATH
export FLEX_SDK_HOME=/usr/local/flex_sdk_3
Update these to correspond to your particular installation path as needed.
Hemlock uses ejabberd as an XMPP server. Download the free ejabberd installer and run it. When the installer asks you about:
localhost.After installing, add an alias to ejabberdctl in your
.profile or equivalent:
# Assuming that you installed at /Applications/ejabberd-2.1:
alias ejabberdctl="/Applications/ejabberd-2.1/bin/ejabberdctl"
Once again, update this to correspond to your particular installation path as needed.
From here on, you can type ejabberdctl in your command line to
speak to ejabberd. For example, start ejabberd like this:
ejabberdctl startThen, check that ejabberd is running properly:
ejabberdctl status
There are also other commands for ejabberd, such as
ejabberdctl stop and ejabberdctl restart. For more
info, see the
ejabberd reference documents.
Ensure that your firewall has ports 5222 and 5280 open. If you're running OS X 10.5 or later, these should be open automatically. With older versions, you can configure this in System Preferences under Sharing > Firewall.
Next, disable secure data transfers in ejabberd for now.
Open /Applications/ejabberd-2.0/conf/ejabberd.cfg
in your text editor. Look for the 5222, ejabberd_c2s block in
the LISTENING PORTS section, and comment out the
certfile line, like this:
%% {certfile, "/Applications/ejabberd-2.0/conf/server.pem"}, starttls,Now find the SERVED HOSTNAMES section in
ejabberd.cfg, and check that it contains
localhost, like so:
{hosts, ["YOUR_COMPUTER_NAME.local", "localhost"]}.A default ejabberd installation only allows one registration every 5
minutes. You will probably want to create accounts more often when you are
testing, so disable the registration time limit. To do this,
find the section ACCESS RULES in your ejabberd.cfg
and add the following to the end:
%% Disable registration time-limit
{registration_timeout, 1}.
Finally, restart ejabberd from command line to enable your changes:
ejabberdctl restartejabberd should have created your admin account during installation. If not, follow the ejabberd instructions on creating an admin account.
You can login to the ejabberd web server with your browser:
http://localhost:5280/admin
When logging in, your username is of the format
USERNAME@localhost. Use the username and password you chose
during ejabberd installation.
From here, you can create additional test accounts for your apps as desired.
Hemlock comes with a few scripts to streamline common tasks like compilation. To run these, you'll need to install:
Hemlock ships with an example app called DrawingDemoContainer. With this app, multiple users can draw pictures together on the same canvas in real-time, using user interface elements that can be easily dropped into any Hemlock app.
We host a live version of this app. You can try it over here.
If you want to get it running locally, just follow these steps:
src/config/environment.as-example, and save a copy of it as
src/config/environment.as. Update your environment's
SERVER and SOURCE_PATH values.rake hemlock:build:drawingDemo. If you've followed the
setup instructions, this should create a file at
src/com/mintdigital/drawingDemo/containers/DrawingDemoContainer.swf.public/index.html. Save a copy to your web
server, or your local computer if you have web sharing enabled.rake hemlock:start:policyd, which starts the daemon running
in the background. This should run from the same domain as your HTML file
(i.e., your web server or your local server).That's it—you're up and running with Hemlock!
Want to see what it's like with multiple people in the room? Just open another browser tab, open the app again, and sign in with a different account. Everything you draw in one window appears in the other!
A Hemlock app is based on two types of components, a HemlockContainer and some HemlockWidgets.
The HemlockContainer is the heart of the Hemlock app, and is the ActionScript compiler's starting point. The container is responsible for maintaining the app's models: it tracks the app's state, such as the list of users playing a game, and how many points each user has. The container also holds a collection of HemlockWidgets, described below.
While the container maintains the app's model data, the HemlockWidget maintains the app's views: creating the user interface and handling user input, such as chat messages and mouse clicks. The widgets packaged with Hemlock are designed to plug into any Hemlock app. For instance, the framework includes ChatroomWidget, which lets users send text-based messages to each other, and DrawingWidget, which lets users draw pictures on a single canvas in real-time. Both of these are demonstrated in the included DrawingDemoContainer.
Hemlock apps use Flash's built-in event system to communicate between a HemlockContainer and its HemlockWidgets. When the app receives data, it is propagated throughout the app like this:
By using this event flow, widgets and containers are loosely coupled—the container never directly tells a widget what to do. Instead, the container announces (by dispatching events on itself) that new data is available, and any listening widgets act on that data independently. As an app matures, this means that old widgets can be swapped out for new ones, and useful widgets can be easily reused in other containers.
To learn more about Hemlock's inner workings, take a look at our Code section.
Check out the Showcase for some project ideas, and to see what Hemlock can do.
Questions? See if the Community can lend a hand.