Madrona Appliance Tutorial

We assume you have already:

This tutorial will walk through creating an app using the Madrona App Generator and then getting started customizing that app. The apps created by the App Generator use the Google Earth Plugin, which is just one of the mapping clients that you can use with Madrona. See the Madrona experience page for more examples and their full source code.

  1. In your running VM, click the Start Using the Madrona VM button Madrona VM startup screen

  2. The App Generator is now running. Follow the instructions onscreen to configure your host system to send web requests for madrona to the VM’s IP address.

This IP address could be different every time you start the VM, in which case you will need to change it.

Madrona VM instructions

Creating the initial demo app

Now that your networking is setup, access the Madrona App Generator from a web browser in your host operating system not the VM.

Why access the App Generator from your operating system? Because this version of the App Generator uses the Google Earth Plugin, which is not available for Linux. So you will need to access it from a Windows or OSX host system. This will change in the future when the App Generator uses a 2D mapping client.

  1. Open the URL http://madrona/

  2. Sign in. The username and password are both madrona

  3. Click the Generate New Madrona App button to begin.

  4. Provide the App with a name, we’ll be using ‘Test App’’ throughout this tutorial.

  5. Enter the description ‘Test Application’ or whatever you want.

  6. Draw a study region on the map. The studyregion is used to define the geographical extent of your project. For best results, draw a smaller region.

  7. Under Features, select the AOI feature.

Features are spatial entities that the user will be able to draw, edit and share with other people.

  1. (Optionally) Create one or more additional features by clicking the + button. Give them a name and a type (point, line, polygon or folder). Once you create more you need to select them all in the Features list by holding down the Ctrl key and selecting them all.

  2. Select one or more of the available KML data layers to make available to your user.

  3. (Optionally) Click the + button to add your own KML file if you know the URL.

  4. Click the Save button. You should now see a summary of your app. App summary

Initialize and Activate Your App

  1. Click the Initialize button.
The initialization process can take up to a minute so be patient. Under the hood this is generating the code for your app using some simple commands.
  1. Once initialization is complete, click the Activate button.
Under the hood this is configuring the Apache web server to make your app available on port 81. You can only have one app active at a time.

Activate the app

Test Out Your New App

  1. In the admin, click the Go To App button. This will open a new tab and load your new app being served at http://madrona:81/. When the app loads it will automatically zoom the map to the study region that you drew.
Loading may take a little while the first time as it caches your requests in order to speed up subsequent loads. If you don't already have the Google Earth Web Plugin installed you will be asked to at this time. Once you do, refresh the page

  1. Click the Login button in the top right. The username and password are both madrona

  2. Click the Data Layers icon in the top left.

This is next to the __Tools__ icon which looks like a gear

  1. You should see a Test App folder which has a data layer for your study region. Try turning this on and off. Double-click to zoom into it.

  2. You should also see a Base KML Data folder which has all of the data layers that you added. Try turning them on and off.

  3. Now let’s create some features. Click the My Shapes tab in the top left. If you don’t see this tab you probably aren’t logged in and should go back to step 2.

  4. Click the Create button and then click AOI which generically stands for Area of Interest.

  5. Click the Draw Shape button and then draw a polygon on the map by clicking once for each vertice and the double-clicking the last point to finish.

Madrona will now validate your shape, make sure you didn't draw any bowties or any other type of self-intersecting polygon. If it's valid you now have the option of editing your shape or if you are happy click the __Next__ button.

  1. Give your new feature a name, any name. Optionally, give it a description.

  2. Click the Submit button

  3. You’ll now be presented with detailed information for your feature. Close this window by clicking the ‘X’.

  4. You should now see your feature listed under Features and Collections

  5. Now let’s create a new folder. Do it the same way you created an AOI, through the Create menu.

  6. Once you create your folder and see it under Features and Collections, click and drag your feature into the folder. This allows you to organize your features any way you like.

There are many more things you can do with these features and folders out of the box including edit, delete, copy, share and download. Try selecting one or more features or folders and performing these actions, for example download an entire folder of features as KML.

Viewing and editing the generated code

To view the code behind this application that was generated by the App Generator using the information you provided, start by going back to the Virtual Machine window.

  1. Click the Start button in the lower-left, it’s the button that looks a little strange. Click Start -> Accessories -> LXTerminal to open a command line terminal window

  2. Now Click Start -> Accessories -> Sublime Editor 2 to open your text editor

  3. In Sublime Text click File -> Open Folder

  4. Now open /usr/local/userapps/testDemoProject/testdemoproject

In this step you are selecting and opening a folder which might seem a little strange. By doing this Sublime gives you a view of the entire folder in the left panel letting you quickly open any file under it.

Terminal window

Nice work, next up: