WooCommerce 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.

Bundle contents

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

  • mobilefront.zip ——————————- Main installation bundle.
  • mobilefront-wordpress-plugin.zip —- WordPress plugin.
  • MobileFront-Documentation.pdf ——— This documentation.

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
  • Bower
  • Ionic

Windows

  • Chocolatey

OS X

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

Ubuntu

  • build-essential g++

Requirements

All app installation aspects are covered in Installation section below.

Installation

1. Installing MobileFront WooCommerce REST API plugin

The MobileFront WooCommerce REST API plugin can be found in bundle/mobilefront-wordpress-plugin.zip. To install it please follow these steps:

  1. Go to your WordPress site with installed WooCommerce plugin.
  2. Open admin panel.
  3. Go to Plugins > Add new.
  4. Click Upload Plugin > Browse and choose mobilefront-wordpress-plugin.zip that is located in unzipped bundle folder.
  5. Click Install Now.
  6. Once the installation is finished click Activate Plugin.

2. Installing JWT Authentication for WP REST API plugin

Customer sign in/sign out functionality requires JWT Authentication plugin to be installed on your WordPress.

Minimum PHP version: 5.6.0.

Follow these steps to install JWT Authentication plugin:

  1. Go to your WordPress site with installed WooCommerce plugin.
  2. Open admin panel.
  3. Go to Plugins > Add new.
  4. Search for jwt.
  5. Install JWT Authentication for WP REST API (author Enrique Chavez) by clicking Install now.
  6. Click Activate once the installation is finished.

Enabling PHP HTTP Authorization Header

Shared Hosts

Most of the shared hosts have disabled the HTTP Authorization Header by default. To enable this option you’ll need to edit your .htaccess file by adding the following:

RewriteEngine on
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule ^(.*) - [E=HTTP_AUTHORIZATION:%1]

So your .htaccess file may look as following:

# BEGIN WordPress

RewriteEngine On
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule ^(.*) - [E=HTTP_AUTHORIZATION:%1]
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]

# END WordPress

WPEngine

To enable this option for WPEngine hosting you’ll need to edit your .htaccess file by adding the following (see https://github.com/Tmeister/wp-api-jwt-auth/issues/1):

SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1

Setting the secret key

The JWT needs a secret key to sign the token. This key must be unique and never revealed. To add the secret key, edit your wp-config.php file and add a new constant called JWT_AUTH_SECRET_KEY:

define('JWT_AUTH_SECRET_KEY', 'your-top-secrect-key');

You can use any string from here.

3. Starting installation

Find and unzip mobilefront.zip file located in the bundle you’ve received after the purchase.

Windows

Find install-windows.bat file inside the unzipped mobilefront.zip, right click it and from the context menu choose Run As Administrator. Alternatively, click Start, find Command Prompt application in programs and run it as administrator. By using the cd command, navigate to the extracted bundle directory and execute the following command:

install-windows.bat

OS X

  1. Open the terminal and cd to the extracted mobilefront.zip directory
  2. Execute the following command:
    . ./install-osx.sh

The script might ask you to enter your password in the process

Ubuntu

  1. Open the terminal and cd to the extracted mobilefront.zip directory
  2. Execute the following command:
    ./install-ubuntu.sh

Now grab some coffee and sit back. The installation script is downloading all the necessary software packages and setting up your development environment.

4. Installation questions

Once all of the dependencies are downloaded, the installation script will ask you a few questions:

  1. Name your app – pick a display name for your app displayed next to the application icon on the devices.
  2. What is your name – enter your name or the name of your organization.
  3. What is your email address – enter your or your organization’s email address.
  4. Select ecommerce plugin to install – choose woocommerce by using up and down arrow keys and continue. Installation script will download some more packages within a few minutes. After that you will see the following question:
  5. Enter your WooCommerce store URL, e.g. https://mystore.com – enter your existing WooCommerce store URL. Do not forget to specify the http/https protocol.

5. Finalizing the installation

At this point MobileFront installation script has received all the necessary info to complete the installation. Your app development project will reside in a child directory named after your app – remember you’ve specified the name of your app on step 2? You will work in the project to configure, build and release your mobile app.

In a few moments the installation script finishes its job and launches your default browser with the web version of the mobile app in it.

Congratulations you’ve successfully installed MobileFront WooCommerce mobile app!

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. cordova prepare
    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

cordova run ios

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

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

Android

If you are going to build the app for Android you’ll need to install the Android Studio.

Running on Android emulator

Android emulators maybe slow. See this Stack Overflow thread on possible options for fast Android emulators or try Genymotion instead.

To run the app on Android emulator follow the steps below:

  1. Launch Android Studio and open any existing project or create new one with any options you want.
  2. Select Tools > Android > AVD Manager.
  3. Create any virtual device and run it.
  4. Run the following command:
    gulp -b && cordova emulate android

The app will be built and run on the emulator.

Running on real Android device

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 && cordova 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
    cordova 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 WooCommerce mobile app provides a set of configuration options. Configuration options are separated into two files:

  • Settings.yml – controls common configuration options. It’s located in config folder.
  • Woocommerce.yml – controls WooCommerce-specific features. It’s located in plugin subfolder of config folder. Its name depends on what integration plugin is used:
    • WooCommerce – woocommerce.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.
  • push_enabled – whether the push notifications enabled. Read how to setup push notifications here.
  • ionic_app_id – Ionic app id to which MobileFront app will be linked for sending push notifications.
  • android_sender_id – sender id generated on Google Firebase side for push notifications on Android.

Woocommerce.yml

Here is the list of the options that can be controlled via woocommerce.yml. It is located in plugin subfolder of config folder.

  • name – plugin name. Used for installation purposes should always be woocommerce. Don’t change this field.
  • api_host – URL of your WooCommerce store.
  • root_category – id of the root category for building navigation. Defaults to 0. Read here on how to find category id in WooCommerce.
  • sorting_options – used for displaying sorting options in the app. Don’t change this field.
  • capabilities – system fields that describe app capabilities. Don’t change this field.
  • paymentMethods – the list of payment methods to use during checkout. There are a few methods that are built-in into WooCommerce. You can add/remove items from this list to control what your users will see on the billing page:
    • paypal – PayPal.
    • cod – Cash on delivery.
    • bacs – Direct bank transfer.
    • cheque – Check payments.
    • stripe – Stripe payment gateway

    Payment methods appear in the app in the same order they are defined in woocommerce.yml.

    If you have other payment gateways installed as WooCommerce plugins, you can go to WordPress admin dashboard > WooCommerce > Settings > Checkout, scroll to the payment gateways list, copy the gateway id and add it to the woocommerce.yml file.

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:

  • mint
  • 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. Learn how to find you WooCommerce category id here.
  • 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

MobileFront home page displays links to WooCommerce categories. Newly created WooCommerce stores tries to grab category with id = 0. You can use any existing category to build navigation menu by specifying its id as a value for root_category parameter in configuration file. If your shop doesn’t have any categories yet there will be a No categories message:

links_11

Read here on how to manage categories in WooCommerce.

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.

Push notifications

This section will show you how to configure MobileFront mobile app to send push notifications via free Ionic Push services.

Linking Ionic cloud with MobileFront app

Follow the steps to link Ionic Push service with MobileFront app:

  1. Go to Ionic framework website and create new account. These credentials will be used to link your MobileFront app with Ionic cloud.
  2. Run the terminal inside the mobile app folder. Execute the following command to sign in with Ionic:
    ionic login

    For example:
    ionic login hello@example.com password
  3. Execute the following command and choose app created earlier:
    ionic link
  4. After that, find ionic.config.json file in the root folder of the app, copy app_id and paste it as value for ionic_app_id parameter in settings.yml file that is located in config folder. It may look as following:
    ionic_app_id: 40d6c4d5
  5. Also, change push_enabled flag that is also located in settings.yml to true.

Configuring FCM (Android only)

A Google Firebase Cloud Messaging Sender ID and Server key are needed to send push notifications to Android devices.

  1. Visit the Firebase Console and create a new project.
  2. Enter a name and region for your project, then click Create Project.
  3. Once the project is created, click the gear next to your project’s name in the side menu and then click Project settings.
  4. From the project settings screen, select the Cloud Messaging tab. This will show you your Server key and Sender ID. Write down these credentials, you will need to provide them in next steps.
  5. From the project view, click add Firebase to your Android project. Enter bundle id that can look as following:
    com.myshop. Click Register.
  6. Once the project will be registered click Download google-service.json file. You will need later as well.
  7. Open settings.yml file of your mobile app and paste Sender ID as value for android_sender_id parameter.

Installing push plugins

For proper work of push notification a few plugins should be added to your project.

  1. Open terminal in the app folder and execute the following command:
    cordova plugin add cordova-plugin-device
  2. Next command differs between iOS and Android, so if you are going to build for Android and iOS execute the following:
    cordova plugin add phonegap-plugin-push --variable SENDER_ID=YOUR_FIREBASE_SENDER_ID
    Where SENDER_ID is your Firebase sender id that was obtained earlier.
    If you are going to build for iOS only execute the following commands:
    cordova plugin add phonegap-plugin-push
    and
    sudo gem install cocoapods

Configuring Ionic Cloud

There a few changes should be made on Ionic Cloud to complete the push notifications configuration:

  1. Go to Ionic dashboard, click on your app icon and choose Settings tab.
  2. Click + New Security Profile. Provide any name for profile and click Create.
  3. Click EDIT right to the just created profile.
  4. To configure push notifications for Android:
    1. Switch to Android tab.
    2. Paste your Firebase Server Key that was obtained earlier for FCM Server Key field.
    3. Provide Android Keystore. See how to obtain it here.
  5. To configure push notifications for iOS:
    1. Switch to iOS tab.
    2. Provide APN Certificate and APN Certificate Password. See how to obtain them here.

Building the app

From terminal, execute the following command:

gulp -b && cordova prepare

If you are building for Android, navigate to app folder > platforms > android and paste there google-service.json file.

See Running on device section for further steps to run on the device.

Sending push notification

Once the app is built you can send your push notifications from Ionic dashboard:

  1. From Ionic dashboard click on your app icon and the choose Push tab.
  2. Click Create your first Push. Compose your push notification by following the steps.

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.

Finding category id

Here is how to find the collection id in WooCommerce side:

  1. Go to Products > Categories.
  2. Hover over a category name.
  3. Click it or click Edit when it appears.
  4. Find the page URL. For example: Section tag_ID=66 where 66 is the ID of the category.

category_id

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.