We will update this documentation regularly. It is not complete but you should have enough to get you started here. We just wanted 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, there are a few things you need to set up on your computer. Here, we'll walk you through those steps.
Hemlock relies on the Adobe Flex SDK. This is a free download from Adobe.com, and you can get it here.
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 installation, you also need to set some environment variables (in your ~/.profile or equivalent in OS X, Linux, or Unix). Assuming that you installed at /Applications/Flex SDK 3, add this:
export PATH=/Applications/Flex/ SDK/ 3/bin:$PATH
export FLEX_SDK_HOME="/Applications/Flex/ SDK/ 3"
Update these to correspond to your particular installation path as needed.
Hemlock uses ejabberd for XMPP. Dowload the free ejabberd installer here and run it. ejabberd will ask you for a virtual host; make sure you enter localhost here.
You will also need to add an alias for ejabberd to your profile or equivalent (OS X, Linux, Unix):
alias ejabberdctl="/Applications/ejabberd-2.0/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. To start ejabberd, just type this:
ejabberdctl startThere are also other commands for ejabberd, such as ejabberdctl stop, ejabberdctl restart, and ejabberdctl status. For more information, see the ejabberd reference documents.
Please ensure your computer has ports 5222 and 5280 open. If you're running OS X, these should be automatically open in 10.5 (Leopard); with older versions, you can configure under Firewall in System Preferences.
Next, we will 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 line resembling:
{certfile, "/Applications/ejabberd-2.0/conf/server.pem"}, starttls,You should also ensure that ejabberd.cfg lists localhost as a virtual host. To do this, check that ejabberd.cfg contains localhost in the “SERVED HOSTNAMES” section, and add localhost to hosts if necessary, 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. Therefore we will 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 propagate the changes.
ejabberd should have created you an Admin account at installation. If not, follow the instructions here to create an admin ejabberd account.
You can login to the ejabberd web server with your admin account at
http://localhost:5280/admin
From here, you can create additional test accounts for your apps.
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.
Here's how to try it out:
config/environment.as-example, and save a copy of it as 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.