Get Started with Merb
The following sections will walk you through creating your first Merb project injected with Appcelerator Entourage. We will also build a simple sample application to help get you going with Appcelerator Entourage.
Prerequisites
Before you begin you will need Ruby and Merb installed on your machine. Please visit their respective sites for information on how to install them.
Once Merb is ready you will need to download the Appcelerator Entourage package for Merb. Remember where you put this. We are going to unpack it next.
Create a new project
First we need a Merb project we want to add Appcelerator Entourage to. We could use an existing project, but for simplicity we are going to create a new one. From the command line run the following command:
merb-gen app path/to/your/new/application
Then we need to unzip the Appcelerator Entourage package for Merb into our new project. The process for this is different if you are on Window or *nix.
*nix
Run the following command:
unzip -q -d path/to/your/new/application path/to/entourage-package.zip
Windows
Unpack the archive in Windows Explorer. Select it's entire contents and copy them to the clipboard. Then paste them into your new application directory.
Back to common instructions
On both platforms we will be prompted asking us if we want to over right the router.rb generated for our new merb application. Because this is a new project, we can replace the default router.rb with the one that ships with Entourage.
If this is an existing project, we would want to say no and hand merge the files.
Let's confirm that everything is working correctly. Run the following commands:
cd path/to/your/new/application merb
Then go to http://localhost:4000/servicetester.html and try to execute the example echo service that was included.
Hello World
Let’s start by creating a simple user interface that will test remote messaging. Lets create ./public/hello_world.html and replace the body contents with the following:
<html> <head> <title>Appcelerator Entourage™ Hello World</title> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <script src="/javascripts/entourage.js" type="text/javascript"></script> </head> <body style="visibility:hidden" on="l:app.compiled then visible"> <!-- generate request --> <textarea id="your_message" fieldset="hello_world">type something</textarea> <div> <input type="button" value="click me" fieldset="hello_world" on="click then r:hello.world.request"/> </div> <!-- display response --> <div> You typed: <span on="r:hello.world.response then value[message]" style="color:blue"> nothing yet </span> </div> <!-- mock service --> <script type="text/javascript"> $MQL("r:hello.world.request", function(message) { $MQ({ name: "r:hello.world.response", payload: { message: message.payload.your_message } }); }); </script> </body> </html>
You should be able to test out your new application by accessing it at the following url: http://localhost:4000/hello_world.html
User Interface Explanation
There are several basic concepts covered in this example. First, we use the fieldset attribute to link the TEXTAREA with the INPUT button. When a click event is generated by an element with a fieldset, Appcelerator will look for other input elements with the same fieldset value, and it will include their values in the message generated by the click event. This feature is very useful when creating forms.
Second, we show how an element can subscribe to a message and set its value based on an attribute in the message payload - in this case the message attribute.
Finally, we show an example of how to create a mock service. A mock service is a SCRIPT widget that subscribes to a remote request and responds with a remote response. This is a powerful capability because it enables you to create fully functional user interfaces (UI) without writing a single line of service code. These UIs are also 100% reusable. Once you finish your UI, you can remove your mock services as you create the remote service implementations. We call this Interactive Use Case development. You can learn more about Interactive Use Cases in the Best Practices section of this documentation.
Service
Now we’re ready to implement the service for our Hello World example. First, remove (or comment out) the mock service that you created above. Next, open ./app/services/test_service.rb and create a new service method like the one below:
Service "hello.world.request", :helloWorld, "hello.world.response" def helloWorld {"message"=>params["your_message"]} end
Again, you should be able to test out your new application by accessing it at the following url: http://localhost:4000/hello_world.html
