Step-by-Step Guide to Creating a ThriveSmart App

Overview

High-Level Steps to a Working ThriveSmart App Diagram Picture Creating a ThriveSmart App is designed to be extremely easy for Ruby on Rails enthusiasts. The image to the right gives you a rough sense of the 5 high-level steps required to get up and running with a ThriveSmart App. For a more detailed overview, please visit the "Introduction To ThriveSmart Apps ".

Step 1: Create A Base Rails App

Just like any other Ruby on Rails Application, the first step is to create the base of the application by running the rails command.

$ rails myapp
$ cd myapp

Now that you're in the directory of your new ThriveSmart-App-to-be, you can prepare your app to create the scaffolding.

Step 2: Install the tsapp_rails Plugin

You install the tsapp_rails plugin just like any other Ruby on Rails Plugin:

~/myapp$ script/plugin install git://github.com/thrivesmart/tsapp_rails.git

This will also install a file that the plugin looks for, at config/tsapp.yml , which contains the API Key and Secret Key for your ThriveSmart App. These will be provided to you when you register your app with www.thrivesmartdev.com (for development), and www.thrivesmarthq.com (for production). We'll [link]fill this in later, when we register our apps[/link].

Alternatively, you can [link]install this plugin as a git submodule for easier updating[/link], but it's not necessary - and not supported by some deployment systems, like Heroku.

Step 3: Create ThriveSmart App Scaffolding

The tsapp_rails plugin comes with a handy generator that's very similar to the scaffold generator, but slightly tuned for the creation of a ThriveSmart App. The usage is as follows, where you fill in the assethost and columns:

 script/generate tsapp PageObject <assethost> <column1:type column2:type column3:type ...>

This should look familiar to any rails developer: it's similar to what you might expect running script/generate scaffold PageObject might look like; and it functions in a very similar way.

At first, a major difference is that the first parameter after the name PageObject is the assethost. The rest of the call looks exactly like script/generate scaffod . Here's a little more insight into what the tsapp generator script creates - all things being necessary to have a functioning ThriveSmart App:

  1. PageObject Migration (db/migrate/yyyymmddhhmmss_create_page_objects.rb )
    Contains the columns specified, as well as an additional urn column of type string - the unique identifier for this PageObbject.  
  2. PageObject Model (app/models/page_object.rb )
    Includes the ThriveSmartObjectMethods module, and specifies the caching directives  
  3. PageObject Controller & Helper (app/controllers/page_objects_controller.rb )
    Includes the PageObjectsControllerHelper module, and adds a custom action: duplicate
  4. Resourceful Route with Custom Methods (config/routes.rb )
    Includes the the extra custom methods required: create_valid , update_valid , and duplicate
  5. Show & Edit Views (app/views/page_objects/[show,edit].html.erb )
    Each use the special tsapp view helper methods.  
  6. Page Object Layout (app/views/layouts/page_object.html.erb )
    Intentionally outputs an empty layout.  
  7. Production & Development Asset Hosts (config/environments/[development,production].rb )
    Necessary for correct asset linkage across servers.

With the exception of the tsapp.yml config file (config/tsapp.yml ), which requires API & secret keys, this scaffolding provides you a fully functional ThriveSmart App. What you'll likely want to do, however, is to customize the views to meet your app's needs, which we'll bring you through next.

Step 4: Customize show.html.erb & edit.html.erb

Just as you're accustomed to with standard Ruby on Rails Applications, ThriveSmart Apps use the [action].html.erb files to render the views. To edit the HTML that's sent to the ThriveSmart Site to render, you simply edit these files, just as you would any other Rails app. Although it's what you're perfectly used to doing, it's worth calling out because your ThriveSmart App will technically be rendering this view to a string, which it then sends to the ThriveSmart App via XML. But it does this in a way that's fairly transparent to the Ruby on Rails Developer (you can see the similar-but-different render_to_page_object calls in the PageObjectsController).

show.html.erb

So go ahead, edit away in apps/views/page_objects/show.html.erb ! You can add in HTML and ERB just as you're used to.

There are a couple minor differences, however, which we'll mention now. Instead of adding javascript_include_tag s and stylesheet_link_tags to the layout (app/views/layouts/page_objects.html.erb ), you use special helper methods provided by the tsapp_rails plugin to specify the javascripts and stylesheets to be used in each view. In your show.html.erb (and edit.html.erb), you'll simply call the 'javascripts' and 'stylesheets' helper methods. These methods are called identically as their rails counterparts ('javascript_include_tag' and 'stylesheet_link_tag'), only they will correctly add the javascripts and stylesheets to the XML that is sent back to the ThriveSmart Site. Given these calls, your view might look like this:

 <% # show.html.erb %>
<% # ------------- %>
<% javascripts 'my-js-file', 'http://ajax.googleapis.com/ajax/libs/jquery/1.3.1/jquery.min.js' %>
<% stylesheets 'my-css-file', 'my-second-css-file' %>

<p>This is my message for the world: <%=h @page_object.message %>!

At this point, it's worth noting how your PageObject will be rendered in the context of the entire Page (which, as you recall, is just a collection of many Page Objects from different ThriveSmart Apps). In adherence to the YSlow guidelines for good page design, we render all of the stylesheets from all PageObjects in the 'head' section of the page, all the HTML for all PageObjects inside their own divs, in order on the page, and then finally all javascript includes for all PageObjects at the bottom of the page, just above the '/body' tag. From the example above, we'd find that the output on the entire page would look similar to the following.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <meta http-equiv="content-type" content="text/html;charset=UTF-8" />
  <title>_PAGE_TITLE_</title>

  <!-- stylesheet includes from PageObjects above this PageObject  -->
  <link href="http://assets.myapp.com/stylesheets/my-css-file.css?1234983487" media="screen" rel="stylesheet" type="text/css" />
  <link href="http://assets.myapp.com/stylesheets/my-second-css-file.css?1234983487" media="screen" rel="stylesheet" type="text/css" />
  <!-- stylesheet includes from PageObjects below this PageObject  -->

</head>
<body class="displaying-page page-_PAGE_URN_ action-show">
  <div id="content">
    <div id="page_object_content">

      <!-- HTML from PageObjects above this PageObject  -->
      
      <div class="page_object show-mode app-_APP_URN_" id="page_object_67">
        <p>This is my message for the world: _HELLO_WORLD_!
      </div>

      <!-- HTML from PageObjects below this PageObject  -->

    <div class="ts-content-end"></div>
  </div>
  
  <div class="ts-footer" id="ts_footer">_THRIVESMART_FOOTER_</div>

  <!-- javascript includes from PageObjects above this PageObject  -->
  <script src="http://assets.myapp.com/javascripts/my-js-file.js?1235082227" type="text/javascript"></script>
  <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.1/jquery.min.js" type="text/javascript"></script>
  <!-- javascript includes from PageObjects below this PageObject  -->
  
</body>
</html>

Although you'll likely use the javascripts and stylehseets helper methods in every ThriveSmart App, there are a few other helper methods you may find useful from time-to-time: link_to_new_page, parent_url, and formatted_site_data_url. These are left to you to view the documentation on!

edit.html.erb

Just as show.html.erb was designed to be as similar to a normal Ruby on Rails App as possible, edit.html.erb was as well. Other than the 'javascripts' and 'stylesheets' helper methods, the most important helper method that every ThriveSmart App will use is 'fields_for_page_object'. The 'fields_for_page_object' helper method works very similar to the Ruby on Rails 'fields_for', and ensures that the form fields in your PageObject's edit view are passed back to your App from the ThriveSmart Site, when the end-user is editing the site. Simply put, 'fields_for_page_object' prepends a specific code to all of your fields that the ThriveSmart Site understands, so it can collect all of these POST parameters on an update, and pass along those values to your ThriveSmart App.

Seeing how this looks in your edit.html.erb is probably the easiest way to understand it, accompanied by seeing how your edit HTML will be embedded in the ThriveSmart Page's edit form.

 <% # edit.html.erb %>
<% # ------------- %>
<% javascripts 'my-js-file', 'http://ajax.googleapis.com/ajax/libs/jquery/1.3.1/jquery.min.js' %>
<% stylesheets 'my-css-file', 'my-second-css-file' %>

<% fields_for_page_object do |f| %>
  <p><%= f.label :message %>: <%= f.text_field :message %>!
<% end %>

And the following is how the above HTML, stylesheets, and javascript code will be layed out on the corresponding ThriveSmart Edit Page:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <meta http-equiv="content-type" content="text/html;charset=UTF-8" />
  <title>Edit Page: _PAGE_TITLE_</title>
  
  <!-- stylesheet includes from PageObjects above this PageObject  -->
  <link href="http://assets.myapp.com/stylesheets/my-css-file.css?1234983487" media="screen" rel="stylesheet" type="text/css" />
  <link href="http://assets.myapp.com/stylesheets/my-second-css-file.css?1234983487" media="screen" rel="stylesheet" type="text/css" />
  <!-- stylesheet includes from PageObjects below this PageObject  -->

</head>
<body class="displaying-page page-_PAGE_URN_ action-edit">
  <div id="content">


    <form action="/pages/_PAGE_URN_" class="edit_page" id="edit_page__PAGE_ID_" method="post">
      <div class="ts-page-edit" id="ts_page_edit">
        <!-- Page Meta-Deta Fields -->
      </div>

      <div id="page_object_content">

        <!-- HTML from PageObjects above this PageObject  -->
        <div class="page_object show-mode app-_APP_URN_" id="page_object__PAGE_OBJECT_ID_">
          <label for="message">Message<label>: <input type="text" name="page[form_page_objects][_PAGE_OBJECT_URN_][message] />
        </div>
        <!-- HTML from PageObjects below this PageObject  -->

      </div>
  
      <div class="ts-page-publish-and-update ts-submit-box" id="ts_page_publish_and_update">
        <!-- Page Publish-Time Fields -->
      </div>
  
    </form>

    <div class="ts-content-end"></div>
  </div>

  <div class="ts-footer" id="ts_footer">_THRIVESMART_FOOTER_</div>

  <!-- javascript includes from PageObjects above this PageObject  -->
  <script src="http://assets.myapp.com/javascripts/my-js-file.js?1235082227" type="text/javascript"></script>
  <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.3.1/jquery.min.js" type="text/javascript"></script>
  <!-- javascript includes from PageObjects below this PageObject  -->

</body>
</html>

As you can see, the edit HTML for your ThriveSmart App's Page Object is placed very similarly to how the show HTML is, only it's embedded in a 'form' tag, which the ThriveSmart Site can correctly parse and send your app only the relevant fields.

There are also several other very important form helper methods that give your ThriveSmart App access to the centralized asset uploading functionality. ThriveSmart Sites provide end-users a single point of asset uploading (image files, documents, and more to come), which you can simply tie into. This allows your App to accept file uploads, which are communicated correctly to your App's input fields via javascript. These methods are: 'asset_urn_fields', 'asset_change_link', 'asset_url_text_field', and 'asset_preview_fields'. Read more about these helper methods in the documentation.

 

To help with development, it's often the most helpful to look at the code of real ThriveSmart Apps.  You'll find the code for all our ThriveSmart Apps on our Sample Code page .

Step 5: Adding & Hosting

The final step in your ThriveSmart App is deploying it on a host, and adding it to our development environment, www.thrivesmartdev.com/apps/new (soon to come).  We'll have recommendations up in a jiffy.