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.
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.
Showoff.io is a great tool for development, allowing you to access localhost from Mxit.
Look at Mxit Apps on the wiki for more information.
To set up a specific controller to use the gem, you need to include the
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
Note that the block must not use a
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:
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 ... end step :second do ... end end
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
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 (
bodyelement in html)
:link- The colour of links in the page
:link_hover- The colour and background colour of highlighted links.
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).
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.mxit_root = 'mxit'
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
:mxit_login- The user's Mxit Login name. From
:nick- The user's current nickname. From
: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
:contact- The Mxit service name, e.g. "firstname.lastname@example.org". From
: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
: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 (
:tariff_plan- a symbol (
:user_input- Any input typed in not matching a link on the page. HTML escaping is undone. From
- Note that spaces are converted to
+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.
- Note that spaces are converted to
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" end