mxit-rails 0.3.1 → 0.3.2

data/README.md

@@ -2,32 +2,43 @@ Mxit Rails
 ==========
 
 A gem that includes a simple and opinionated templating framework for Rails-based Mxit apps.
-This includes a rough layout, support for styles similar to CSS classes, wrapped inputs, and
+This includes a layout framework, support for styles (similar to CSS classes), abstraction of inputs and multi-step forms, and
 an elegant way to support Mxit's conversation-based interface.
 
+It also includes a browser-based *emulator* with a lot of functionality to simplify and streamline the development process.
+
 Later versions will also include wrappers for important Mxit APIs.
 
+
 Sample App
 ----------
 A basic to-do app has been set up as an example of the gem in use.  It can be seen at [mxit-to-do](https://github.com/linsen/mxit-to-do).
 
+
 Installation
 ------------
 To use the gem, just include the gem your rails projects' gemfile:
 
-    gem 'mxit-rails', '~> 0.2.7'
+    gem 'mxit-rails', '~> 0.3.2'
+
+[Heroku](https://devcenter.heroku.com/articles/rails3) provides the simplest way to get a rails app running on the web.
+
+[Showoff.io](https://showoff.io) is a great tool for development, allowing you to access localhost from Mxit.
+
+Look at [Mxit Apps](wiki/Mxit-Apps) on the wiki for more information.
 
-The newest version is 0.2.7 - it is not recommended to use any earlier versions.
 
 Basic usage
 -----------
-To set up a controller to use the gem, you need to include the `MxitRails::Page` module:
+To set up a specific controller to use the gem, you need to include the `MxitRails::Page` module:
 
     include MxitRails::Page
 
 This creates a few helper methods that can be used within that controller
 
 - `input input_name, input_label` - Define the page's input field with a name (symbol) and text label
+- `select select_name, select_label, select_options, options` - Create a single-select input with a name (symbol) and text label
+- `multi_select select_name, select_label, select_options, options` - Create a multi-select input with a name (symbol) and text label
 - `validate type, [parameter], message` - Set up validations on the input field.
 - `validate message, &block` - A custom message with a block providing a `true` (valid) or `false` (invalid) value.  
   Note that the block must not use a `return` statement
@@ -40,6 +51,10 @@ Currently the following validations are available:
 - `:length, exact_length`
 - `:min_length, min`
 - `:max_length, max`
+- `:min_value, min`
+- `:max_value, max`
+- `:cellphone_number`
+- `:sa_id_number`
 
 
 Multi-step forms
@@ -57,14 +72,19 @@ The gem allows the easy set up of multi-step forms within a single controller ac
 
 The order in which steps are defined will be the order they are presented to users in.  Each step should have its own view file, in
 `app/views/controller/action/step`.  Each step has access to the same helper methods as the controller itself.  For steps that don't
-have an input field, a `proceed` helper method is provided
+have an input field (either `input`, `select` or `multi_select`), a `proceed` helper method is provided
 
 - `proceed message` - Show a proceed link rather than a form input
 
 Users will only proceed to the next step in the form if all validations of the previous step pass.
-
 If the action has a `submit` block (defined outside of the `form`), it will only be executed after the last step is completed.
 
+There are three methods to change flow within a form.  All will create a redirect, but a `return` statement should accompany them in the action
+to avoid double rendering.
+- `skip_to step_name` - Skip to the specified step
+- `reset!` - Reset the whole form
+- `submit!` - Submit the form with whatever values have been filled in so far
+
 
 Styles
 ------
@@ -75,25 +95,28 @@ and can be declared in any controller with the `mxit_style` macro.  It is recomm
 
 To include a style in a template, use the `mxit_style` helper method.  Any number of styles can be given as parameters to this method.
 
-    <p style="<%= mxit_style :author %>">Lewis Carroll</p>
+    <span style="<%= mxit_style :author %>">Lewis Carroll</span>
 
 The following special styles are used in the overall layout, and it is thus recommended that they be defined.  Note that links can only be styled per-page, not per link.
 
 - `:body` - The page body (`body` element in html)
-- `:title` - The page title
 - `:link` - The colour of links in the page
 - `:link_hover` - The colour and background colour of highlighted links.
 
 
 Layout
 ------
-The gem currently includes a default layout that has a title bar, an optional navigation link, and a form input below the body where appropriate.
-The title and navigation should be defined with `content_for` blocks, addressing `:title` and `:navigation` respectively.
+The gem currently includes a default layout that creates the necessary html headers, and includes the form at the bottom of the page.
+
+There is a `mxit_table_row` helper method (which takes a list of styles) that will create a new table cell.
+All cells will be 100% width, and are intended to be used only to create blocks of colour in the app (e.g. title bars).
+
+Calling `mxit_table_row` with no parameters will create a row with the `body` style applied
 
 
 Emulator
 --------
-The mxit-rails gem is provided with an emulator to aid development.  It can be accessed at `/emulator`.  The url will dynamically update to show
+The mxit-rails gem is provided with a feature-rich emulator to aid development.  It can be accessed at `/emulator`.  The url will dynamically update to show
 the current URL of the page shown as a suffix, e.g. `emulator/path_to/page`.  Certain parts of the app can similarly be loaded directly by
 navigating to their corresponding URL.
 
@@ -104,12 +127,32 @@ To set the root URL of the emulator, add the following line to `config/applicati
 
 Mxit Headers
 ------------
-The gem automatically parses (some) Mxit headers and makes them available in the `mxit_params` hash.  When using the emulator these values are spoofed with cookies, but in a way transparent to the app itself.  Currently the following are available:
-
-- `:mxit_id` - The user's Mxit ID (m-ID). From the `X-Mxit-UserId-R` header
-- `:mxit_login` - The user's Mxit Login name. From the `X-Mxit-Login` or `X-Mxit-ID-R` header
-- `:display_name` - The user's current nickname. From the `X-Mxit-Nick` header
-- `:distribution_code` - The distribution code corresponding to the specific installaction of the Mxit app on the user's phone. 
-  The first part of the `X-Mxit-Device-Info` header.
-- `:mobile_number` - The user's mobile number as in their profile. The second part of the `X-Mxit-Device-Info` header.
+The gem automatically parses (some) Mxit headers and makes them available in the `mxit_params` hash.  When using the emulator these values are spoofed with cookies, but in a way transparent to the app itself.  Look at Mxit's [Documentation](http://dev.mxit.com/docs/mobi-portal-api#headers) for more details. Currently the following are available:
+
+- `:mxit_id` - The user's Mxit ID (m-ID). From `X-Mxit-UserId-R`
+- `:mxit_login` - The user's Mxit Login name. From `X-Mxit-Login` or `X-Mxit-ID-R`
+- `:display_name`, `:nick` - The user's current nickname. From `X-Mxit-Nick`
+- `:screen_width` - From 'UA-Pixels'
+- `:screen_height` - From 'UA-Pixels'
+- `:device_user_agent` - The agent string of the requesting device, e.g. "SonyEricsson?/K800i". From `X-Device-User-Agent`
+- `:contact` - The Mxit service name, e.g. "books@mxit.com". From `X-Mxit-Contact`
+- `:location` - The user's current location. From `X-Mxit-Location`. Automatically split into components (in `mxit_params`) as well:
+    - `:country_code` - ISO 3166-1 alpha-2 Country Code
+    - `:country_name`
+    - `:principal_subdivision_code`
+    - `:principal_subdivision_name`
+    - `:city_code`
+    - `:city_name`
+    - `:network_operator_id`
+    - `:client_features_bitset`
+    - `:cell_id`
+- `:profile` - The user's profile details. From `X-Mxit-Profile`. Automatically split into components (in `mxit_params`) as well:
+    - `:language_code` - ISO_639-1 or ISO_639-2 language code
+    - `:registered_country_code` - Registered ISO 3166-1 alpha-2 Country Code
+    - `:date_of_birth` - A ruby Date object where it can be parsed to a Date, otherwise just the string from the header
+    - `:gender` - a symbol (`:male`, `:female` or `:unknown`)
+    - `:tariff_plan` - a symbol (`:free`, `:freestyler` or `:unknown`)
+- `:user_input` - Any input typed in not matching a link on the page. HTML escaping is undone. From `X-Mxit-User-Input`.
+    - Note that spaces are converted to `+` characters, and `+` characters are not escaped, so if the user enters a `+` it will appear as a space in rails.
+    - This field wil *only* be set if the user enters text that is not a link on the page (case sensitive match to the link text), and if there isn't a form input on the page.
 

data/app/assets/javascripts/mxit_rails/emulator.js

@@ -35,23 +35,17 @@ Emulator = (function() {
 
     setCookie: function() {
       // Create cookies.  Use only lowercase cookie names - the server expects this (case insensitivity seems dodgy)
-      $.cookie('x-mxit-login', localStorage.getItem('mxit-login'), {path: '/'});
       $.cookie('x-mxit-userid-r', localStorage.getItem('mxit-id'), {path: '/'});
+      $.cookie('x-mxit-login', localStorage.getItem('mxit-login'), {path: '/'});
       $.cookie('x-mxit-nick', localStorage.getItem('mxit-nick'), {path: '/'});
+      $.cookie('x-mxit-contact', localStorage.getItem('mxit-contact'), {path: '/'});
+      $.cookie('x-mxit-location', localStorage.getItem('mxit-location'), {path: '/'});
+      $.cookie('x-mxit-profile', localStorage.getItem('mxit-profile'), {path: '/'});
       $.cookie('x-mxit-device-info', localStorage.getItem('mxit-distribution-code') + ',' + localStorage.getItem('mxit-msisdn'), {path: '/'});
 
-      if (MXIT_PATH && (MXIT_PATH != ''))
-        Emulator.setUrl(MXIT_PATH);
-      else
-        Emulator.home();
-    },
+      $.cookie('ua-pixels', '240x320', {path: '/'});
+      $.cookie('x-device-user-agent', 'EMULATOR', {path: '/'});
 
-    clearCookie: function() {
-      // Create cookies.  Use only lowercase cookie names - the server expects this (case insensitivity seems dodgy)
-      $.cookie('x-mxit-login', null, {path: '/'});
-      $.cookie('x-mxit-userid-r', null, {path: '/'});
-      $.cookie('x-mxit-nick', null, {path: '/'});
-      $.cookie('x-mxit-device-info', null, {path: '/'});
 
       if (MXIT_PATH && (MXIT_PATH != ''))
         Emulator.setUrl(MXIT_PATH);
@@ -86,8 +80,9 @@ Emulator = (function() {
     editCredentials: function() {
       $('#center').hide();
       $('#inputs').show();
+      $('#link').hide();
 
-      values = ['id', 'login', 'nick', 'distribution-code', 'msisdn'];
+      values = ['id', 'login', 'nick', 'contact', 'location', 'profile', 'distribution-code', 'msisdn'];
       for (var i in values) {
         var str = values[i];
         var value = localStorage.getItem('mxit-' + str);
@@ -95,15 +90,27 @@ Emulator = (function() {
       }
     },
 
+    clearCredentials: function() {
+      values = ['id', 'login', 'nick', 'contact', 'location', 'profile', 'distribution-code', 'msisdn'];
+      for (var i in values) {
+        var str = values[i];
+        $('#mxit-' + str + '-input').val('');
+      }
+    },
+
     saveCredentials: function() {
-      values = ['id', 'login', 'nick', 'distribution-code', 'msisdn'];
+      values = ['id', 'login', 'nick', 'contact', 'location', 'profile',, 'distribution-code', 'msisdn'];
       for (var i in values) {
         var str = values[i];
-        localStorage.setItem('mxit-' + str, $('#mxit-' + str + '-input').val());
+        var val = $('#mxit-' + str + '-input').val();
+        if (val == '')
+          val = $('#mxit-' + str + '-input').attr('placeholder');
+        localStorage.setItem('mxit-' + str, val);
       }
 
       $('#inputs').hide();
       $('#center').show();
+      $('#link').show();
       Emulator.setCredentials();
     },
 

data/app/assets/stylesheets/mxit_rails/emulator.css.scss

@@ -87,7 +87,13 @@ iframe {
 }
 #inputs {
   display: none;
-  padding: 10px;
+  padding: 20px 10px 10px 10px;
+  position: absolute;
+  top: 37px;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  background-color: #fff;
 }
   #inputs label {
     font-size: 12px;
@@ -100,7 +106,7 @@ iframe {
     font-size: 16px;
     border: 1px solid #bbb;
     border-radius: 5px;
-    width: 208px;
+    width: 95%;
     height: 22px;
   }
 #save {
@@ -108,6 +114,11 @@ iframe {
   display: block;
   text-align: center;
 }
+#clear {
+  position: absolute;
+  right: 20px;
+  top: 3px;
+}
 
 
 .link .icon {

data/app/assets/stylesheets/mxit_rails/included.css.scss

@@ -5,6 +5,59 @@ html, body {
   font-weight: normal;
 }
 
+.emulator td {
+  padding: 2px;
+}
+
 .emulator form {
   display: none;
 }
+
+.emulator .emoticon {
+  height: 32px;
+  line-height: 32px;
+  width: 32px;
+  display: inline-block;
+  background-repeat: no-repeat;
+  text-indent: 100px;
+  overflow: hidden;
+
+  &.happy {background-position: 0px 0px;}
+  &.sad {background-position: -32px 0px;}
+  &.winking {background-position: -64px 0px;}
+  &.excited {background-position: -96px 0px;}
+  &.shocked {background-position: -128px 0px;}
+  &.surprised {background-position: -160px 0px;}
+  &.tongue_out {background-position: -192px 0px;}
+  &.embarrassed {background-position: -224px 0px;}
+  &.cool {background-position: -256px 0px;}
+  &.heart {background-position: -288px 0px;}
+  &.flower {background-position: -320px 0px;}
+  &.male {background-position: -352px 0px;}
+  &.female {background-position: -384px 0px;}
+  &.star {background-position: -416px 0px;}
+  &.chilli {background-position: -448px 0px;}
+  &.kiss {background-position: -480px 0px;}
+  &.idea {background-position: -512px 0px;}
+  &.extremely_angry {background-position: -544px 0px;}
+  &.censored {background-position: -576px 0px;}
+  &.grumpy {background-position: -608px 0px;}
+  &.coffee {background-position: -640px 0px;}
+  &.mr_green {background-position: -672px 0px;}
+  &.sick {background-position: -704px 0px;}
+  &.wtf {background-position: -736px 0px;}
+  &.in_love {background-position: -768px 0px;}
+  &.rolling_eyes {background-position: -800px 0px;}
+  &.crying {background-position: -832px 0px;}
+  &.thinking {background-position: -864px 0px;}
+  &.drooling {background-position: -896px 0px;}
+  &.sleepy {background-position: -928px 0px;}
+  &.liar {background-position: -960px 0px;}
+  &.nerdy {background-position: -992px 0px;}
+  &.pirate {background-position: -1024px 0px;}
+  &.bored {background-position: -1056px 0px;}
+  &.cold {background-position: -1088px 0px;}
+  &.confused {background-position: -1120px 0px;}
+  &.hungry {background-position: -1152px 0px;}
+  &.stressed {background-position: -1184px 0px;}
+}

data/app/helpers/mxit_rails_helper.rb

@@ -50,7 +50,7 @@ module MxitRailsHelper
 
     output = "<a href=\"#{target}\">"
     if @_mxit.numbered_list
-      output += "#{@_mxit_select_index}</a>) #{content}"
+      output += "#{@_mxit_select_index})</a> #{content}"
     else
       output += "#{label}</a>"
       output = (selected ? '+ ' : '- ') + output

data/app/views/emulator/index.html.erb

@@ -45,35 +45,49 @@
   <div id="phone">
     <div id="screen">
       <iframe id="center" class="content" onLoad="Emulator.updateIframe()"></iframe>
-
-      <div id="inputs">
-        <div>
-          <label for="mxit-id-input">Mxit ID</label>
-          <input type="text" placeholder="Mxit ID" id="mxit-id-input" value="m987654321" />
-        </div>
-        <div>
-          <label for="mxit-login-input">Mxit Login</label>
-          <input type="text" placeholder="Mxit Login" id="mxit-login-input"/>
-        </div>
-        <div>
-          <label for="mxit-nick-input">Display Name (Nick)</label>
-          <input type="text" placeholder="Nickname" id="mxit-nick-input"/>
-        </div>
-        <div>
-          <label for="mxit-distribution-code-input">Distribution Code</label>
-          <input type="text" placeholder="Distribution Code" id="mxit-distribution-code-input" value="DISTRO_CODE"/>
-        </div>
-        <div>
-          <label for="mxit-msisdn-input">MSISDN (Cell No)</label>
-          <input type="text" placeholder="MSISDN" id="mxit-msisdn-input" />
-        </div>
-
-        <a id="save" class="go link" onclick="Emulator.saveCredentials()">Save <span class="icon"><span class="image"></span></span></a>
-      </div>
     </div>
     <input id="phone-input" type="text" autocomplete="off" />
   </div>
 
+  <div id="inputs">
+    <a id="clear" class="go link" onclick="Emulator.clearCredentials()">Clear All <span class="icon"><span class="image"></span></span></a>
+    <div>
+      <label for="mxit-id-input">Mxit ID</label>
+      <input type="text" placeholder="m987654321" id="mxit-id-input" />
+    </div>
+    <div>
+      <label for="mxit-login-input">Mxit Login</label>
+      <input type="text" placeholder="MxitLogin" id="mxit-login-input"/>
+    </div>
+    <div>
+      <label for="mxit-nick-input">Display Name (Nick)</label>
+      <input type="text" placeholder="Nickname" id="mxit-nick-input"/>
+    </div>
+    <div>
+      <label for="mxit-contact-input">Contact</label>
+      <input type="text" placeholder="ContactName" id="mxit-contact-input" />
+    </div>
+    <div>
+      <label for="mxit-location-input">Location</label>
+      <input type="text" placeholder="ZA,South Africa,11,Western Cape,23,Kraaifontein,88,13072382,8fbe253" id="mxit-location-input" />
+    </div>
+    <div>
+      <label for="mxit-profile-input">Profile</label>
+      <input type="text" placeholder="en,ZA,1984-01-01,male,1" id="mxit-profile-input" />
+    </div>
+    <div>
+      <label for="mxit-distribution-code-input">Distribution Code - Only available to authorised apps</label>
+      <input type="text" placeholder="DISTRO_CODE" id="mxit-distribution-code-input" />
+    </div>
+    <div>
+      <label for="mxit-msisdn-input">MSISDN (Cell No) - Only available to authorised apps</label>
+      <input type="text" placeholder="27820123456" id="mxit-msisdn-input" />
+    </div>
+
+    <p>Leave fields blank to set them to the default value</p>
+    <a id="save" class="go link" onclick="Emulator.saveCredentials()">Save <span class="icon"><span class="image"></span></span></a>
+  </div>
+
   <div id="fadeout"></div>
 
 </body>

data/app/views/layouts/mxit.html.erb

@@ -7,10 +7,11 @@
 
   <meta name="mxit" content="no_prefix,show_progress,clear_on_new,no_heading" />
 
-  <% if request.headers['x-mxit-login'].nil? %>
+  <% if @_mxit_emulator %>
     <!-- Include a CSS file, but only in a browser/emulator, not on mxit -->
     <%= stylesheet_link_tag "mxit_rails/included" %>
     <style type="text/css">
+      .emulator .emoticon { background-image: url(<%= image_path("mxit_rails/emoticons.png"); %>) }
       a:focus { outline: none; <%= mxit_style :link_hover %> }
     </style>
   <% end %>
@@ -33,13 +34,13 @@
 
   <br />
   <% if @_mxit.input %>
-    <% if @_mxit.input_label %>
+    <% unless @_mxit.input_label.blank? %>
       <%= mxit_proceed @_mxit.input_label %>
     <% end %>
 
   <% elsif @_mxit.select %>
     <% if @_mxit.multi_select %>
-      <% if @_mxit.select_label %>
+      <% unless @_mxit.select_label.blank? %>
         <%= @_mxit.select_label %><br />
       <% end %>
 
@@ -50,7 +51,7 @@
       <%= mxit_proceed link_to(@_mxit.multi_select_next, "#{request.path}?_mxit_rails_submit=true&_mxit_rails_multi_select=#{@_mxit.select}") %>
 
     <% else %>
-      <% if @_mxit.select_label %>
+      <% unless @_mxit.select_label.blank? %>
         <%= mxit_proceed @_mxit.select_label %>
       <% end %>
       <% @_mxit.select_options.each do |value, label| %>

data/lib/mxit_rails/engine.rb

@@ -1,4 +1,7 @@
 module MxitRails
   class Engine < ::Rails::Engine
+    initializer "precompile", :group => :all do |app|
+      app.config.assets.precompile += %w( mxit_rails/emulator.js mxit_rails/emulator.css mxit_rails/included.css )
+    end
   end
 end