Maestro - Ionic 3 - WooCommerce Edition

version 1.0.0

Getting Started

Welcome

Maestro - E-Commerce App
This app provides a complete user journey for an e-commerce app- from product listing, offer showcase to login, signup, payment and user profile. Implemented using Wordpress API, WooCommerce REST API on a Customer Server & Card.IO and Stripe plugins.

Prerequisite
Server Side Requirements

To integrate this application with wordpress, install and activate three plugins WooCommerce, JSON API and JSON API USER.
JSON API which is extended by JSON API USER is used to allow RESTful user registration, authentication, password reset. WooCommerce Rest API been used for customer/order creation and update.
Also, please make sure your server is running on PHP 5.6 and Soap Client is enabled; WordPress version 4.6 or above and WooCommerce version 2.6.9 or above.

Client Side Requirements

To use and run this app, your system must have NodeJS, Ionic & Cordova installed. You can follow the link to download latest NodeJS for your system. Once NodeJS is installed on your system, you can install Ionic and Cordova using following commands in your terminal.

      
      $ npm install -g cordova ionic
      
Installation
Wordpress API Setup

It is required that you activate JSON API and JSON API USER plugins. Then visit Settings > JSON API and activate User and Core controllers.


WooCommerce API Setup
1. Enabling the REST API

Once WooCommerce plugins is activated, To enable the REST API within WooCommerce, visit the WooCommerce > Settings > API tab and tick the Enable REST API checkbox.

2. Requirements

It’s required turn on the WordPress permalinks on Settings > Permalinks.

3. Generating API keys

The WooCommerce REST API works on a key system to control access. These keys are linked to WordPress users on your website.
To create or manage keys for a specific WordPress user, go to WooCommerce > Settings > API > Keys/Apps.

To get started, select Add Key:

Select the User you would like to generate a key for in the User field and add a Description. Choose the level of access for this API key, which can be Read access, Write access or Read/Write access. Then select the Generate API Key button and WooCommerce will generate API keys for that user. In the application scenario, we have used an account with admin level access

Now that keys have been generated, you should see two new keys, a QRCode, and a Revoke API Key button. These two keys are your Consumer Key and Consumer Secret.

Place your consumer key and consumer secret in a text file. We will integrate these keys with our server

PHP REST Server Setup

In you downloaded folder, navigate to server folder and change $appId, $appSecret, $site_url, $consumer_key, $consumer_secret variables in _variable.php file. You have got $consumer_key, $consumer_secret generated from Woocommerce API setup. $site_url is where your wordpress site is running and $appId, $appSecret are your own.

Now upload the server folder to remote or local host which would act as your Rest API server.
Ionic App Setup

In you app folder, open src > shared > constants.ts, and change your site url and the credentials you have given in PHP REST Server Setup as below..

Now you are ready to run/preview the app running following commands inside app directory.

      
      //add ios or android platform
      $ ionic cordova platform add ios
      $ ionic cordova platform add android
      
      //To preview app in you browser
      // Please note some of the features like Stripe/Paypal Payment, Card Scan, User profile will not work unless your run it on a device/emulator
      $ ionic serve -l
      
      // To run your app on deveice or emulator follow the command below.
      // You can also use -c -l flags to print in console and livereload 
      $ ionic cordova run ios 
      $ ionic cordova run android

      

Please check Common Issues section is you find any error while running the app

Card.io

This can ONLY be run on devices

Before you build in release mode-
Android
If you enable ProGuard to shrink and obfuscate your code, make sure to adjust your proguard configuration by adding the following to ${sdk.dir}/tools/proguard/proguard-android.txt or your custom specified location.
   
         
    -keep class io.card.** { *; }
    -keep class com.keepe.** { *; }
    -keepclassmembers class io.card.** { *;}
    -dontwarn io.card.payment.CardIOActivity
    (See bug: https://github.com/card-io/card.io-Android-SDK/issues/86)
    
          
iOS
make sure to adjust your configuration by adding the following to info.plist:
   
        
      <key>NSCameraUsageDescription</key>
      <string>To scan credit cards.</string>
    
          
STRIPE
Please note- Stripe Payment will work on devices only.

Genuine card information cannot be used in test mode. Instead, use any of the following test cards to create a successful payment:

Number Brand
4242424242424242 Visa
4012888888881881 Visa
4000056655665556 Visa (debit)
5555555555554444 Mastercard
5200828282828210 Mastercard (debit)
5105105105105100 Mastercard (prepaid)
378282246310005 American Express
371449635398431 American Express
6011111111111117 Discover
6011000990139424 Discover
30569309025904 Diners Club
38520000023237 Diners Club
3530111333300000 JCB
3566002020360505 JCB
Paypal

Please make sure your have a Pro account type for the plugin to work. You can upgrade your sandbox account to Pro as below-

  • 1. Login to your account in https://developer.paypal.com/.
  • 2. In Dashboard, under sandbox, click on accounts.
  • 3. Click on sandbox account which you want to upgrade.
  • 4. Click on Profile
  • 5. Under account type, click on Upgrade to Pro link.
  • 6. Click Enable.
Features
  • Onboarding/ Walkthrough slider
  • Full login flow including sign in, signup, password reset
  • Side Menu Navigation, that is hidden and only comes when you need it
  • Category page with filtering and multiple layout selector
  • Product page with slider, multiple colour and size selectors
  • Shopping Cart
  • Full payment flow including Personal details, Card details and sucess page
  • Wishlist/ Favourites with edit option
  • Search page with working example
  • Settings - with password change and profile edit
License

This original work with exclusive rights to Pinro and Envato for distribution. By purchasing the item, you acquire the right to use that item; not to re-destribute the item.


Customization

Folder Structure

All stylings and customization has been done in scss files. All common styles are in 'app.scss' file inside 'src/app' directory. Page specific component, templates and styles are in respective directories by their names inside src/pages directory. Once you have download the package you will see the following folder structure.

SASS

Sass is a CSS pre-processor, meaning that it extends the CSS language, adding features that allow variables, mixins, functions. Maestro supports Sass and is pure built on top of Sass

All common elements have common styles specific the element. i.e. Product List has a class name product-list. All customisation specific to the common class has been done inside .product-list in src/app/app.scss.

          
      /*****************************
            Product List
      *****************************/
        .product-list {
          &.list-view {
            .list-item {
                width: calc(100% - 30px);
                margin: 15px;
                position: relative;
                .product-image {
                    height: 250px;
                }
                .price {
                    font-size: 13px;
                }
            }
          }
            //truncated for preview
        }
      

Following are the color variables used, available inside src/theme/variable.scss.

          
      //colors variables
        $colors: (
          primary:    #387ef5,
          secondary:  #33cd5f,
          danger:     #ef473a,
          light:      #fff,
          dark:       #222,
          light-grey: #ebebeb,
          warm-grey: #878787,
          grapefruit: #ff5252,
          lighter: #ebebeb
        );
          
Javascript
  • App the configured in src/app/app.module.ts and src/app/app.component.ts is the main app component.
  • Page specific component, template and styles are inside the specific page directory in src/pages directory.
Animation

Animation has been implemented using Animate.css classes 'animated animationName', i.e. 'animated fadeInLeft', in template files specific to the view/pages. You can find out more about animate.css here.

You can change logo in the app.
1. Replace p-i-n-r-o.svg file inside src > assets > img with your logo file.
2. Place you logo file in src >assets > img directory and change Logo url in img src of src > app > app.html.


Category, Products and Offers

Editorial

To show Products in Editorial view, categorize them in a Category with editorial slug.

Update editorialCategoryId in app constants in src/shared/constants.ts with this editorial category ID

Top level full width products are featured products in Editorial category.

Offers

Offer image in Editorial and Profile shown from featured images in Posts. Offer image in Editorial view is shown from Editorial Post category with editorial slug. And offer images in Profile view is shown from Offers Post category with offers slug.


Support

Common Issues

In some cases you might get XMLHttpRequest CORS error that says Origin http://example.com is not allowed by Access-Control-Allow-Origin. In this case, update your Appearance > Editor > function.php file in Wordpress Admin Panel as below.

            
            header('Access-Control-Allow-Origin: *');
            header('Access-Control-Allow-Methods: GET, POST');
            header('Access-Control-Allow-Headers: Content-Type');            
            

Alternatively, you can enable CORS from .htaccess or php.ini file if you prefer.

Also, if your wordpress is running on PHP 7 you might get a 500 Internal Server Error on WooCommerce API call for Categories or Products data. In this case, please enable PHP 5.6 (native) to get over this issue.

Contact

In order to modify the app you need to have knowledge in web technologies such as javascript, html5 and css3. You also need to be able to install Ionic and its dependencies on your machine.

We recommend you to use the Ionic official installation guide and ask on the Ionic forum for support. We then will be happy to answer all the app related questions/issues via email ( support@pinrotech.com ) or themeforest comments.

You can build this app with phonegap build, however, we don’t provide support on how to build the app using phonegap build.

Credits

UI is heavily inspired by Mono iOS UI kit