Skip to content
A gem to make creating mxit apps in Rails fast and pleasant.
Ruby JavaScript
Latest commit 0a076ef Jun 22, 2013 @drubin drubin Merge pull request #20 from marshally/update_readme_to_v0_4_3
update README to v0.4.3

Mxit Rails

A gem that includes a simple and opinionated templating framework for Rails-based Mxit apps. 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.

A wrapper for some of Mxit's APIs is included.

See the ChangeLog for latest changes.

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.


To use the gem, just include the gem your rails projects' gemfile:

gem 'mxit-rails', '~> 0.4.3'

Heroku provides the simplest way to get a rails app running on the web. is a great tool for development, allowing you to access localhost from Mxit.

Look at Mxit Apps on the wiki for more information.

Basic usage

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
  • submit &block - A code block that will only be executed if the input was submitted and passed all validations.


Currently the following validations are available:

  • :not_blank
  • :numeric
  • :length, exact_length
  • :min_length, min
  • :max_length, max
  • :min_value, min
  • :max_value, max
  • :cellphone_number
  • :sa_id_number

Multi-step forms

The gem allows the easy set up of multi-step forms within a single controller action. Forms are defined as follows:

form do
  step :first do
  step :second do

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 (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


Mxit-rails has a basic styling engine that functions similarly to CSS classes. Styles are identified by a symbol, and can be declared in any controller with the mxit_style macro. It is recommended to declare them in application controller.

mxit_style :author, 'background-color:#F8F3EA; color:#000000'

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.

<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)
  • :link - The colour of links in the page
  • :link_hover - The colour and background colour of highlighted links.

Check the Style Guide for more tips. There is also a list of Emoticons that can be used on Mxit.


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


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.

To set the root URL of the emulator, add the following line to config/application.rb:

config.mxit_root = 'mxit'

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. Look at Mxit's Documentation 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. "". 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.

Mxit API Wrapper

The Mxit API client can be configured through an initializer, eg.

MxitApi.configure do |config|
  config.mxit_app_name = "app_name"
  config.mxit_api_client_id = "your_client_id"
  config.mxit_api_client_secret = "your_client_secret"
Something went wrong with that request. Please try again.