Purpose of this document

The purpose of this document is to explain how to set up and use Mobify Client. Mobify Client is a command-line application for developing mobile adaptations with Mobify.js.

Prerequisites

  • A Mobify Cloud account
  • A basic knowledge of HTML and CSS
  • A firm grasp of the command-line

Setting up your local environment

If you don't have Node.js installed, you must do so before continuing. To install it through a package manager on a UNIX-based system, read these instructions.

Installing the Mobify Client

Download the Mobify Client with the following command:

npm -g install mobify-client

If you are running on Linux or OSX, you may need to prepend this command with sudo.

Create your mobile adaptation

Create a project

Create an initial project scaffold with the following command:

mobify init myproject

This will generate the basic set of files that you need to start a new project.

Build your adaptation

To start working on your mobile adaptation, simply cd into your project directory and start making some changes! The basic project structure is this:

README.md
project.json
src/
    mobify.konf
    style.css
    tmpl/
        base.tmpl
        home.tmpl
        _header.tmpl
        _footer.tmpl

The tmpl files are where you will place all of your HTML and template markup. The mobify.konf file is where all of your JavaScript selections for desktop content take place. For an understanding of how to create adaptations using Mobify Client, please read our Getting Started with Mobify Client Guide.

Push your adaptation to the Mobify Cloud

If you have not yet connected your local Mobify Client with the Mobify Cloud, please read Connecting Mobify Client and Mobify Cloud.

When you are happy with your mobile adaptation, you can use the Mobify Enterprise Client to push a bundle of your current work to Mobify Cloud to preview or publish it.

mobify push --message "<build number>: <commit hash>, <branch name>"

--message: This required flag lets you attach a message along with the bundle. By convention, we like to use the above format internally, but you can customize this to your organization's needs.

Note: On Windows, ensure that your Node is version 0.10.x. The push command will not work for Node version 0.12.x or greater on Windows. You can grab Node version 0.10.38 for Windows here.

Previewing Your Mobile Adaptation

To preview the bundle you have been developing locally, you have two options: the local Mobify Preview server or the preview dashboard on Mobify Cloud.

Running the Preview Server

To start the preview server on your computer, navigate to the root directory of your Mobify Design Suite project. You should be in the same directory as project.json.

cd project_name
mobify preview
Alt text

Two things are happening here:

  1. Preview: Mobify Preview has started at port 8080, which makes your mobile site available on your local computer.

  2. Compass Watch: This service automatically compiles your project's SASS files to CSS whenever changes are made.

As you make changes to your konf and template files, a new mobify.js will be automatically generated whenever you refresh your browser.

Previewing In Your Browser

Now, open preview.mobify.com in Safari, Chrome, or iOS Simulator to preview your mobile experience.

Alt text

Each setting on this page is outlined below:

  • Site URL: Use the URL of the environment you want to test on (usually production or staging). (Note: To ensure that Mobify Preview works properly, choose a URL that does not redirect. i.e. If yourdomain.com redirects to my.yourdomain.com/home.php, Mobify Preview will not activate.)

  • Bundle Location: Points Mobify Preview at the location of the bundle you want to use. Most of the time, this will be your local development copy at http://localhost:8080, but you can test off of instances on other computers or even use the production bundle.

  • Domain (Optional): By default, Mobify Preview sets the cookie on ".yourdomain.com", but you can specify the domain with this field.

  • This Tab/All Tabs: "This Tab" runs Mobify Preview with the specified domain/bundle only in this tab. All other tabs will show the production behaviour. "All Tabs" runs Mobify Preview with the specified domain/bundle in all tabs of your browser.

Once you select the 'Authorize' button, our Mobify Preview service will inject a tag into the page you are adapting, and the page will be adapted with your local project. This means you aren't actually making any changes to the site itself at this point, this is simply a preview of the test environment.

Previewing your adaptation on Mobify Cloud

Another option for previewing your adaptation is to preview it through the Mobify Cloud. When you start thinking about making your adaptation live, you will want to push your project (how?) to our Cloud, and the interface has a dashboard that allows for easy previewing of your adaptations as well.

Login to Cloud and click on the Preview tab in the left panel:

Alt text

You can select between the Mobify Preview server that is running on your local machine, or you can choose to preview a previously pushed bundle:

Alt text

Example Mobile Site: Virgin Wines

When you're happy with the state of your mobile adaptation, all that is left is to publish!

Publishing A Bundle

In your web browser, login to your Mobify Cloud account and go to the Publishing screen for your project.

Alt text

To publish a bundle, select the radio button for the bundle you want, then click Publish Selected at the bottom of the page.

Appendix

Upgrading Mobify Client

Note: On OSX and Linux you will need to preface these commands with sudo, and on Windows you will need to have administrator privileges to install or update Mobify Client.

To upgrade the client, you will need to remove the old version.

First check what version of Mobify Client you have:

mobify --version

If you have a version in the 0.3.x or later series, you can remove it by going:

npm -g remove mobify-client

If you have a version in the 0.2.x series or older, you can remove it by going:

npm -g remove mobify-js-tools

Finally, once it has been removed, you can install the latest version by going:

npm -g install mobify-client

Connecting Mobify Client and Mobify Cloud

Before you can push any bundles to the Mobify Cloud, your account on Cloud must be set up to take advantage of Mobify Client. To convert your account from a regular account to one that you can use with Mobify Client, simply send us an email and we will convert it for you.

After your account is converted, you will have to create a shell project that you will be pushing local bundles into. Create a new project in Mobify Cloud with the URL of the site you are adapting. Once the project is created, you will be able to see your login credentials under the Mobify Client tab:

Alt text

Simply paste these credentials into the command line to connect you to Mobify Cloud:

mobify login --auth email:APIKey

Now that your account is set up, the last thing you will have to do is ensure that your local project matches the name of the project you have created on Mobify Cloud. To do this, find the slug name of your project on Cloud. You will find it in the URL:

https://cloud.mobify.com/projects/slug-name/

Take this slug name and copy it into the project.json file in your project directory:

{
    "name": "slug-name",
    "api": "1.1",
    "plugins": [],
    "exclude": [
        "*.tmpl"
    ]
}

And you're all set up! You can now push bundles to the Mobify Cloud.

Downloading a bundle from Mobify Cloud

To download a bundle from the Mobify Cloud, just type out the following URL:

https://cloud.mobify.com/projects/<project_slug>/bundles/<bundle_id>/download

Mobify Client Project File Structure

The basic project structure looks like this:

config.rb
project.json
src/
    mobify.konf
    stylesheet.css
    i/
    js/
    scss/
        modules/
        pages/
        _defaults.scss
        stylesheet.scss
    tmpl/
        base.tmpl
        home.tmpl
        _header.tmpl
        _footer.tmpl

config.rb: Configuration file for Compass, tells it where to find the Sass files

project.json: Configuration file for Mobify Design Suite

src/mobify.konf: Select which items from the desktop site to include in your Mobify Design Suite site

src/stylesheet.css: The compiled CSS file for your mobile experience

src/tmpl/: Template files, each template corresponds to a different set of selections in mobify.konf

src/scss/: SCSS files, which get compiled down to CSS

src/scss/modules/: Module styles, for things that are used across the site (button styles, form styles, etc)

src/scss/pages/: Page specific styles

src/scss/_defaults.scss: Project defaults

src/scss/stylesheet.scss: Main stylesheet file, include all other files from here

src/i/: Images directory

src/js/: External JS files you want to use, uploaded to the Mobify CDN

Further Documentation and Tutorials

Last Edited