Documentation 2017-06-22T16:18:58+00:00

Introduction

Thank you for taking interest in MobileFront!

MobileFront eCommerce App is professionally made cross-platform Ionic template that integrates with the most popular eCommerce platforms with the help of plugins. It is built with AngularJS, Ionic and Cordova, works on both iOS and Android and requires minimal effort to produce a ready to deploy app.

Read more about available eCommerce platforms integration here.

Bundle contents

After purchasing MobileFront you will receive the bundle.zip file. Unzip it anywhere on your development machine. Here are the contents of the bundle:

bundle_contents

After the installation is complete, the end result is a new folder containing your app source code, ready to be customized, built and deployed.

bundle_contents_2

Please see this section to learn more about mobile application project structure.

System requirements and dependencies

Before running the installation procedure please go through the checklist below and make sure that you have the following items ready:

  1. Computer with one of the following operating systems: Windows 7/8/10, OS X 10.9+, Ubuntu 14.04
  2. If you are using Mac, make sure you have xCode installed on it.

The following software packages are going to be installed during the setup procedure. You do not have to install these manually:

All platforms

  • NodeJS and NPM
  • Git
  • Cordova
  • Gulp 4.0
  • Bower
  • Ionic 1.7.16

    MobileFront requires Ionic version 1.7.16. If you already have newer Ionic version installed it will be automatically downgraded to 1.7.16 during installation.

Windows

  • Chocolatey

OS X

  • Wget
  • Homebrew
  • ios-sim
  • ios-deploy

Ubuntu

  • build-essential g++

In order to build Android applications you will need to install Android SDK. See Android SDK installation instructions below.

In order to build iOS applications you will need to use Mac computer with xCode installed on it.

All app installation aspects are covered in Installation section below.

Available eCommerce Integrations

Shopify (included)

MobileFront provides out-of-the-box integration with Shopify. The bundle includes Shopify Bridge NodeJS application which securely and reliably plugs into your existing Shopify web store. We support core Shopify features such as product lists and product details, categories, navigation and checkout process.

app-bridge-backend-scheme

Static data (Included)

Plugin with fake products and categories that allows testing the app without connecting it to real shop. App doesn’t make external calls and uses data stored locally. Choose “Static data” during installation to quickly see what MobileFront is capable of without going through the full installation process. You can always switch to real eCommerce by installing the necessary plugin later.

WooCommerce (Available separately)

Turn MobileFront eCommerce Template into WooCommerce mobile app with this plugin. It supports all WooCommerce basic features and can be installed in just a few minutes.

Installation

Installation steps depends on which integration plugin is chosen.

Running the app

The following section will show you how to run and test the app in a desktop browser, on Android and iOS platforms.

All the commands below assume that you have terminal or command line open at your project folder – a folder that gets created during the installation and has the name you’ve chosen.

Running in browser

For testing, debugging and developing purposes we recommend using Chrome browser. Safari and Firefox will also work fine.

To test the app in a desktop browser type the following command:
gulp

gulp command builds the project and launches the app in the default browser. It also watches for modifications of JS, HTML and SCSS files and reloads the page when the source code changes.

Running on devices

Before building the app for physical devices and emulator there are a few commands that should be executed before. Move to project folder by using the cd commands in terminal/command line and type the following commands in the order specified:

  1. gulp -b
    this command will build the project into www folder, minifying and concatenating JavaScript files.
  2. ionic state restore
    this will create iOS and Android projects in /platforms directory.

Running in iOS simulator

Running the app in iOS simulator requires Mac computer with xCode installed.

Run the following commands in terminal:

gulp -b

ionic run ios

iOS simulator will be launched with the app running in it.

If after running ionic run ios the simulator does not appear, run the command again. This happens sometimes when running the app for the first time.

Running on Android

If you are going to build the app for Android you’ll need to install the Android SDK and its dependency – Java SE Development Kit (JDK). You can find instruction on how to install them here and here respectively.

To build the app for Android follow the steps below:

  1. Plug in your Android device to your computer via USB cable. Make sure your device is recognized by the computer.
  2. Turn on the USB debugging mode on the device. See this short video for instructions.
  3. Run the following commands:
    gulp -b
    ionic run android

The app will be built and uploaded to the connected device.

Using Crosswalk

If you are aiming for older Android devices (< Android 5.0), it makes sense to use Crosswalk plugin for binary builds. Crosswalk plugin will embed its own webview built on Chromium directly into your app, which will guarantee that most of the modern HTML5 and CSS3 features are supported even on old devices. Performance will be significantly improved as well. However, because of the embedded webview your app bundle size will be increased by ~20 mb.

Learn more about Crosswalk here.

Building with Crosswalk

MobileFront doesn’t recommend using Crosswalk if you are are not targeting old Android devices (older than 5.0), but feel free to try both variants and choose which one is better for you.

Here is how to build the Android binary with Crosswalk:

  1. Go to your app folder via terminal and execute the following command to install Crosswalk Cordova plugin:
    cordova plugin add cordova-plugin-crosswalk-webview
  2. Then you need to cleanup the old builds by executing the following command:
    cordova clean android
  3. Now you can build for android with Crosswalk:
    gulp -b
    ionic run android
Removing Crosswalk
  1. If you want to remove Crosswalk, execute the following command:
    ionic browser remove crosswalk
  2. Before building without Crosswalk, cleanup the old builds, by executing the following command:
    cordova clean android

Features and customization

The section below explain mobile application structure, features and customization options.

Mobile application project

The main project folder has the following structure.

project_structure

Configuration files

MobileFront eCommerce app provides a set of configuration options. Because various eCommerce platforms provide different features, configuration options are separated into two files:

  • Settings.yml – controls configuration options that are common for all eCommerce platforms. It’s located in config folder.
  • .yml – controls integration-specific features that may vary across different eCommerce platforms. It’s located in plugin subfolder of config folder. Its name depends on what integration plugin is used:
    • WooCommerce – woocommerce.yml
    • Shopify – shopify.yml
    • Static data – staticdata.yml

Settings.yml

Here’s the list of common configuration parameters:

  • plugin – the name of the plugin which is currently used to connect to eCommerce backend.
  • theme – UI theme name. Read more about themes here.
  • home_blocks – defines the home page layout. Read more about home page configuration here.
  • phone, email, website, address– values of these parameters will be display on About Us page. About Us page description is here.
  • display_vendor – whether the vendor name should be displayed for the items on the Products page.
  • cart_badge – calculate amount of items in shopping cart based on distinct item quantity or based on total items quantity. Possible values: distinct_item_count, total_item_count.
  • stripe_key – stripe publishable key. Currently used only for WooCommerce integration.

Plugin.yml

As mentioned above, configuration options varies across different eCommerce platforms:

  • Shopify – read more about Shopify-specific configuration options of shopify.yml file here.
  • WooCommerce – read more about WooCommerce-specific configuration options of woocommerce.yml file here.
  • Static data:
    • name – plugin name. Used for installation purposes. Don’t change this field.
    • data_path – path to JSON files with data.
    • sorting_options – used for displaying sorting options in the app. Don’t change this field.

Themes

MobileFront provides a few built-in color themes for the app. Current theme can be configured via theme parameter of settings.yml file. Possible values for this parameters are:

  • evening
  • rainbow
  • blossom

Creating themes of your own is very easy:

  1. Go to app/styles/themes folder, duplicate any of existing theme and give it any name. For instance – mytheme.
  2. Edit the your new theme in a way you want.
  3. Now open settings.yml file and type mytheme as value for theme parameter.
  4. In terminal, execute gulp command. It will rebuild the app with modified settings and launch it in the browser.

Home page

Home page is what users see first after opening MobileFront app. Home page can contain up to 3 promotional blocks and any number of products categories.

Promotional blocks

Promotional blocks can be flexibly configured via settings.yml file. A block can represent a group of products that you’d like to promote on the home page, e.g. “Items on sale”, “New fashion for men” and so on. Each block can have it’s own image, title, subtitle and action button. Clicking a block will take the user to the product list page for a collection associated with the block. All block parameters are described below:

  • title – title of the block. Leave empty value for no title.
  • subtitle – subtitle displayed right below the title. Leave empty value for no subtitle.
  • action – text of the action button displayed below subtitle. Leave empty value for no action button.
  • highlightContent – displays a semi-transparent strip behind title, subtitle and action button. If the image has bright background, it can improve text visibility.
  • storeCategoryId – id of the category associated to this block. Clicking the block will take the user to the product list page for that collection.
    • Read here how to find the collection id in Shopify.
  • image – defines background images of the promotional block. There are two ways to set background images for the block:
    1. Add image to the app by placing it in app/images/homepage and use this path as a value of the image parameter. This option results in faster block loading time but is less flexible, because in order to change the image you will have to rebuild the app.
    2. Use the collection image from your eCommerce platform – if the value of image parameter is empty, MobileFront will attempt to load category image from the backend based on storeCategoryId parameter value. This way you can dynamically set the images for your promotional blocks without the needs to re-publish the app to the app stores.
  • halign – horizontal alignment of the block content. Possible values are:
    • left
    • right
    • center
  • valign – vertical alignment of the block content. Possible values are:
    • top
    • bottom
    • middle

Navigation

There are also navigation buttons which are located under home page blocks. Those buttons are linked together with categories from your store.

home_page_navigation

Read how to configure home page navigation for Shopify here.

Side menu

The MobileFront eCommerce app has side menu for quick access to main app pages. There is a default avatar image on top of the menu items. For example, you can change it to your shop logo:

  1. Go to app/images/side_menu.
  2. Replace the default_avatar.png with your image.
  3. Recommended image size is about 257x257 pixels.

Product list

product_list_1

The product list page displays a group of products belonging to the same category.

Tab bar

When the current category has child categories these are displayed in tab bar. Users can refine the product list by these categories by tapping tab bar items. Note: child category will only display in the tab bar if they don’t have child category of their own.

product_list_2

Infinite scroll

When the user reaches the bottom of the product list the application starts loading the next portion of products if there are any available.

Display options

Products can be displayed in two ways: grid view and list view. To switch between the two the user can use the button in the bottom right corner of the page.

product_list_4

Sorting

The users can sort the products using the selector located in the left bottom corner of the page.

product_list_3

Hiding bars

When the user starts scrolling through the list of products tab bar and footer slide away in order to have more space for products. To show the bars again the user should scroll up a little bit.

Hiding vendor

In order to hide the vendor of the product item, go to the setting.yml and set display_vendor to false.

Product details

Product details page serves to display everything about selected product. There is an image slider on the top of the page with all product images. Below the slider, there is a product title, its price and expandable description.

product_details

Selecting variant

In the very bottom of the page, there is product variants selector. It can be used for choosing different product variants – for example, t-shirt sizes or colors. If the image was associated with certain variant on the eCommerce side, image slider will be automatically swiped to this image when choosing this variant.

If the chosen variant is not available (for example, sold out), adding to cart and changing quantity will be replaced by SOLD OUT title.

sold_out

Adding product to cart

ADD TO CART button will add the currently viewing product to the shopping cart. To change the quantity of adding product, click plus or minus buttons.

add_to_cart

Adding to wishlist

Any product can be added to a wishlist by clicking heart icon in the bottom right corner of the image slider. Wishlist can be accessed from the side menu.

Shopping cart

Shopping cart allows to review and manage products before checking out.

cart

Changing quantity

It’s possible to increase or decrease the chosen quantity of each product by clicking plus or minus buttons accordingly.

cart_1

Removing product from cart

Removing product from the cart can be done by clicking delete button. Product will be also removed from the cart, if its quantity equals to 1 and minus button is clicked.

cart_2

Checking out

Total amount of money to pay is displayed in the left bottom corner of the page. When clicking Checkout > button, checkout process will be started.

About us

About us page serves to display information about you or your company and can be reached via side menu. There are few things you can customize on About us page:

  1. Logo – go to app/images and change logo_about.png to yours.
  2. About Us text:
    1. go to resources/languages/en_US folder and open translation.json.
    2. Find about section and change aboutText value to yours.

      For more about translations see Language resources section.

  3. Contact information – go to config/settings.yml, and change phone, email, address and website to your own.

Language resources

MobileFront was build with localization in mind. All of the labels and messages seen in the app are stored in a localization file located at /resources/languages/en_US/translation.json. Values found in this file can be modified to meet your needs. For example, in order to change Whishlist item label to Favorites:

  1. Find the menu object in translation.json.
    "menu": {
    "home": "Home",
    "myCart": "My Cart",
    "wishlist": "Wishlist",
    "about": "About"
    }
  2. Change Wishlist property value to Favorites.
    "menu": {
    "home": "Home",
    "myCart": "My Cart",
    "wishlist": "Favorites",
    "about": "About"
    }
  3. run gulp command and observe the change in the browser.

Other texts can be changed in a similar fashion.

Under the hood MobileFront uses angular-translate to map values from translation.json to UI. You can read more about angular-translate and how it helps you localize your app here.

Miscellaneous

Changing icons and splash screens

Changing icons and splash screens is a really common task and can be done easily within MobileFront template. There are two ways to replace those assets:

  1. Automatically generate icons and splash screens. Ionic allows to automatically generate all the necessary icons and splash screens based on a single base image. However, this may not work for you, if you want to use different icons for IOS and Android or precisely control the look of the splashscreens in different dimensions.

    Read here for more about Ionic image generation.

  2. Manually replace icons and splash screens. This approach allows you to have absolute of control how splashscreen look in different dimensions.

Changing assets manually

  1. Go to your mobile application project folder (see Bundle contents if you don’t know where it is).
  2. Find resources folder and open it. You will see android and ios folders. Each of them contains platform-specific icons and splash screens.
  3. Replace them with your images (keeping the names and dimensions the same).
  4. Once you are done changing icons and splash screens, open command line, navigate to your app folder and run the following command:
    gulp -b
  5. Now you can check your new icons and splash screens on the device. See here how to run the app on the device.

Generating assets automatically

  1. Go to your mobile application project folder (see Bundle contents if you don’t know where it is).
  2. Find resources folder and open it.
  3. You will see icon.png and splash.png files. Those files will be used to generate multiple assets with different sizes. Replace them with your own images keeping the names and dimensions the same.
  4. Open command line and navigate to your app folder. Type the following command to generate icons and splash screens:
    ionic resources
  5. If you want to generate only icons, execute the following command:
    ionic resources --icon
  6. If you want to generate only splash screens, execute the following command:
    ionic resources --splash
  7. Now run the following command to build the app with new assets:
    gulp -b
  8. You can check your new icons and splash screens on the device. See here how to run the app on the device.

Missing assets on the device issue

Sometimes your new assets can’t deployed to the device. This is a known Cordova issue and it can be easily fixed:

  1. Once you’re done replacing icons and splash screens, go to your app folder > platforms > android (or platforms > ios) and simply delete the build folder.
  2. Now open command line, navigate to your app folder and run the following command:
    ionic clean
  3. Then you can build the app by executing gulp -b and deploy the app to the device after it.

Installing Java SDK

Android SDK requires Java SDK to be installed. follow the steps below on how install it:

  1. Go to Java SE Development Kit 8 Downloads page, accept the license and choose the bundle for your OS. For example, for 64-bit Windows it could be jdk-8u101-windows-x64.exe.
  2. Download the bundle, launch it and proceed with installation.

Once installation is done, you can install the Android SDK.

Installing Android SDK

Sections below will guide you through Android SDK installation steps for your OS.

Before installing Android SDK, make sure you have installed Java SDK as described here.

Windows

  1. Go to Android Studio page and scroll down to the bottom of the page.
  2. In table column SDK tools package download the bundle for Windows with installer, launch and install it.
  3. Once the install is complete, leave Start SDK Manager checkbox checked and click Finish. Android SDK Manager will be launched.
  4. Check Tools folder. Expand the following folders and check SDK Platform in all of them:
    • Android 7.0 (API 24)
    • Android 6.0 (API 23)
    • Android 5.1.1 (API 22)
  5. Click Install packages.
  6. In the next window, accept the license and click Install.

It will take some time to download and install everything. Once it’s done you can build your eCommerce mobile for Android! See here for details.

Mac

  1. Go to Android Studio page and scroll down to the bottom of the page.
  2. In table column SDK tools package download the bundle for Mac.
  3. Extract the downloaded bundle and move it contents to ~/Library. So path to your Android SDK will look like ~/Library/android-sdk-macosx.
  4. Open android-sdk-macosx > tools folder, find android file there and open it via terminal: right mouse click > Open With > Terminal. Android SDK Manager will be opened.
  5. Check Tools folder. Expand the following folders and check SDK Platform in all of them:
    • Android 7.0 (API 24)
    • Android 6.0 (API 23)
    • Android 5.1.1 (API 22)
  6. Click Install packages.
  7. In the next window, accept the license and click Install.
  8. While SDK Manager settings everything up you can add ANDROID_HOME to your environment variables:
    1. Open Terminal and execute the following command:
      touch ~/.bash_profile; open ~/.bash_profile
    2. Add to the opened file the following line:
      export ANDROID_HOME=/Library/android-sdk-macosx
    3. Save file.

It will take some time to download and install everything. Once it’s done you can build your eCommerce mobile for Android! See here for details.

Changing bundle id

The bundle identifier is the unique string that identifies your application. Bundle ID is defined during app creation steps on Google Play or Apple App Store and should be the same in your app descriptor. You should change bundle id to yours before publishing the app. Here is where to find it:

  1. Navigate to your mobile application project folder.
  2. Find config.xml file in the root of this folder. This file is your app descriptor.
  3. On the second line you will see something like that:
    widget id="io.mobilefront.ecommerce" version="1.0.0" xmlns="http://www.w3.org/ns/widgets" xmlns:cdv="http://cordova.apache.org/ns/1.0"
  4. This id is your bundle id. Change it to yours. It should has the following format:
    com|org|io.your_company_name.your_product_name

config.xml has much more options to change. Learn more about it here.

Contact us

MobileFront says thank you for purchasing our product. We are always open for questions and suggestions so don’t hesitate to contact us at support@mobilefront.io. You can also leave your feedback in comments section of our product on CodeCanyon.