GiraffyDelivery

Full-featured ecommerce solution documentation version 1.0


Introduction


First of all, Thank you so much for purchasing this template and for being my loyal customer. You are awesome!
You are entitled to get free lifetime updates to this product + exceptional support from the author directly.

This documentation is to help you regarding each step of customization. Please go through the documentation carefully to understand how this template is made and how to edit this properly. Basic HTML and CSS knowledge is required to customize this template. You may learn basics here, here and here.

Requirements

You will need the following sofwares to customize this template.

  1. Code Editing Software (eg: Dreamweaver, Sublime Text or Notepad)
  2. Web Browser for testing (eg: Google Chrome or Mozilla Firefox)
  3. FTP Tool to upload files to Server (eg: FileZilla)

Be careful while editing the starter. If not edited properly, the design layout may break completely.
Paid support at $70/hr is only provided for faulty customization.

Getting Started #back to top

Once downloaded and extracted the archive, you'll have three folders inside - documentation (the same documentation as you're reading now), application which contains the ionic project and backend which contains Laravel project for backoffice.

You'll need the following to setup local build/run environment:

  • MacOS with XCode >= 8 if you want to do local builds for iOS, otherwise Windows/Linux running machine will be enough
  • Ionic Pro account if you want to do cloud builds and/or use JS errors logging
  • NodeJS >= 6.0 and NPM >= 4.0
  • PHP >= 7.0 with Composer
  • MySQL >= 5.6
  • Latest Android SDK

Run the following commands to launch Ionic dev server:

                                    npm install -g cordova ionic
                                    cd ecommerce-app
                                    npm install
                                    ionic serve

                                

Run the following to run the backend (will be accessible at http://localhost:8000):

                                    cd ecommerce-backend
                                    composer install
                                    php artisan serve
                                    cp .env.example .env

                                

Please don't forget to create the database, import included dump.sql file and set DB credentials in .env file.

Project structure #back to top

resources - images which are used for icon and splashscreen creation

src - source files (TypeScript, HTML and SASS) for components and pages

node_modules - libraries (will appear after run npm install command)

www - where your developed app compiled files are located, this folder is actually served and works as root

platforms - platforms-specific native code. Don't modify this folder until you know for sure what you're doing! This is handled by cordova

plugins - Cordova plugins source files. Don't modify contents of this folder!

node_modules, www, platforms and plugins folders are not included in the distribution. This folders will be created by ionic/cordova during the build.

API Base URL #back to top

Once you setup the local/remote backoffice server, you have to tell the app about it.

There is a src/services/api_service.ts file, which has the following code:

                            constructor(private http: Http,
                                private storage: Storage
                            ) {
                                this.rootUrl = 'http://delivery.giraffy.tech/api/'; 
                        

Please modify this path to fit your server's path. For example you've installed the backoffice at 'example.com', than you need to have

                            constructor(private http: Http,
                                private storage: Storage
                            ) {
                                this.rootUrl = 'http://example.com/api/'; 
                        

API Endpoints #back to top

GET /categories - get Categories list
restaurant_id - Optional restaurant ID parameter (For multi-restaurant systems)

GET /restaurants - get Restaurants list
city_id - Optional city ID parameter (For multi-cities systems)

GET /delivery_areas - get Delivery areas list
city_id - Optional city ID parameter (For multi-cities systems)

GET /products - get Products for category
category_id - Required category ID parameter

GET /news - get News list
city_id - Optional city ID parameter (For multi-cities systems)

POST /orders - create Order
name - customer name
address - customer address
phone - customer phone
lat - customer latitude (location)
lng - customer longitude (location)
payment_method - payment method (one of 'cash', 'paypal', 'stripe' for now)
stripe_token - token for Stripe payment
paypal_id - transaction ID for PayPal payment
delivery_area_id - detected delivery area
city_id - city ID (for multi-city systems)
restaurant_id - restaurant ID (for multi-restaurant systems)
promo_code - promo code used
products - an array of products to add, each item has format like { product_id: PRODUCT_ID, count: PRODUCT_COUNT}

POST /promo_codes/validate - validate promo code
code - Promo code to validate products - Products array (See POST /orders method)

GET /settings - get current settings

POST /customers - customer registration
email - customer email
password - customer password
name - customer name
city_id - optional city_id parameter (for multy-cities systems)

POST /login - customer login
email - customer email
password - customer password
Returns authentication token, which must be sent as 'token' header to 'get customer orders history' and 'update customer data' methods (See below)

PUT /customers/1 - update customer data
email - customer email
password - customer password
password_confirmation - customer password confirmation
name - customer name
city_id - optional city_id parameter (for multy-cities systems)

GET /orders - get current customer orders history

API enpoints for the drivers mobile app:

POST /driver_login - driver login
login - driver login
password - driver password
Returns authentication token, which must be sent as 'token' header to all below requests

POST /drivers/1 - update driver profile
login - driver login name - driver name password - driver password

POST /push_token - saves mobile app push token on backend
push_token - push token got from OneSignal

POST /order_status - change order status. It's possible to set only statuses with checkbox 'Can be set by delivery boy' enabled
order_status_id - ID of order status

GET /driver_orders - receive a list of orders assigned to the driver

GET /messages - receive a list of messages sent to the driver

POST /read_message - mark message as read by driver
id - message ID

Users Management #back to top

Admin Panel (Backoffice) Users #back to top

These users have access to backoffice. And this access could be restricted/customized.
To do this:
Enter the Users area, find the required user. Click Edit button. You’ll be able to restrict user access to cities and system areas. For example you select Customers, Orders and City 1. This means user will have access to Customers and Orders related to City 1.


Customers #back to top

You can require customers signup by setting up the ‘Require client signup’ checkbox in settings area. Once you’ll do this, mobile app will ask client to signup or login on welcome screen.
If this is not set, the customers section will be empty.
This section allows you to see the list of your customers.
To view all orders by particular customer: enter the ‘Customers’ area, find the required customer (You can use filter) and click ‘orders history’ button.


Delivery Boys #back to top

You can create the Delivery Boys accounts here and set the password. Delivery boy mobile app can be used to work using this accounts.
You can also customize the system to send them notification messages on order assign.
By default system sends push to Delivery Boy during assign to order.

Messages

You can send a message to any Delivery Boy. Your message will arrive as push message and also appear on the 'messages' page of delivery boys mobile app.

Layouts #back to top

Layouts for categories and products list could be changed via settings section.

Layout change requires full app restart. Not only minimize and open again, but full restart.

You can choose one of two built-in layouts for categories page:

List
Two Columns


There are also three built-in layouts for products list:

List
Picture on Left
Two columns

Catalog #back to top

Catalog consists of multiple parts:

  1. Cities (if multiple cities are enabled)
  2. Restaurants (if multiple restaurants are enabled)
  3. Categories (ierarchical tree)
  4. Products
Each catalog part could be edited via corresponding side menu item.
Filtering is also available for some parts of catalog:
  1. Restaurants - Search is always available, filter by city is available when multiple cities are enabled
  2. Categories - City is available when multiple cities are enabled, Restaurant is available when multiple restaurants are enabled
  3. Products - Search, filters by Tax group and Category are always available, filter by City is available when multiple cities are enabled, Restaurant is available when multiple restaurants are enabled

News feed #back to top

This feature allows you to show users news feed based on their desired location. News could be created without city specified. This news will be available for all users.

Promo codes #back to top

You can create an unlimited amount of promocodes. For each promo code you can restrict amount of times it can be used and validity dates (for example you can use promocode christmas since 20th December 2018 till 30th December 2018).
You can set promo code discount in you primary currency (absolute value) or in percents (for this case please mark checkbox discount in percents).
There is also an option to set minimum order amount and make promocode valid for a single city or restaurant.
You can use the same code for promocodes, however you should care about having multiple valid promocodes with the same conditions at the same time.

Taxes (Tax Groups) #back to top

You can create as much tax groups as you need. There is also an option for ‘default tax’. If you’ll set any tax group as ‘default’, system will apply it to all products, which doesn’t have a tax group set.
If you'll not create any tax groups, zero tax will be automatically applied.

Delivery areas #back to top

Delivery areas allows you to setup service areas. This will restrict user to choose delivery address only inside specified delivery area. Start drawing the delivery area with a single click on map and stop (add last point) with double click. You can add more points and/or modify existing points at any time by dragging them with mouse, so don’t worry if you add point in wrong location.
Delivery areas can be assign to cities (if you enabled the 'multiple cities' option).

Orders #back to top

Orders provides you with full featured control set of orders. You can view a list of orders, search by date and text, filter by city and/or restaurant (if multiple cities and/or restaurants are enabled), open order details page and edit products list.
Order details page is allows you to assign the delivery boy to order.

You can also do basic order processing management. You can create an unlimited set of order statuses which will fit your nees and change status during order edit.

Customers #back to top

You can require customers signup by setting up the ‘Require client signup’ checkbox in settings area. Once you’ll do this, mobile app will ask client to signup or login on welcome screen.
If this is not set, customers auto creation feature will be automatically applied. System will use customer's phone numbers as unique identifier and will automatically create/find customers and assign them orders.

Multiple cities #back to top

You can create any amount of cities. This will work once you have ‘Enable multiple cities’ checkbox set in settings. This will allow to create a dedicated account to access each particular city and create restaurants and all other stuff belonging to that city.

Push Notifications #back to top

Starter is using OneSignal service for sending the push notifications. So you'll need to create the free account
Follow the OneSignal documentation for push messages support setup.
Once it's done, please enter your App ID and Auth Token in settings section.

Settings section #back to top

Please note!!! Most settings change requires app restart, not minimize and open again, but kill and reopen.

Currency format

Enter the settings section and edit ‘currency format’ setting. Place :value where you want to see the money value. For example we have a sum of 250 US Dollarss and $:value setting. In this case we’ll get $250 as output everywhere in app and backend.

Date and time formats

There are corresponding settings for both backoffice and mobile application, please refer to the following docs for date and time formats customization:

Tax is included to price checkbox

If this checkbox is not set, the tax amount (set via tax groups, 0 by default) will be added to all products price

Multiple restaurants

System can handle multiple restaurants. This feature can be enabled with "Enable multiple restaurants" checkbox. The "Restaurants" section will automatically appear in the sidebar once you'll select this. You'll be able to apply restaurant filter on all backoffice sections.

Multiple cities

System can handle multiple restaurants. This feature can be enabled with "Enable multiple cities" checkbox. The "Cities" section will automatically appear in the sidebar once you'll select this. You'll be able to apply city filter on all backoffice sections.

Push messages

This section allows you to setup your OneSignal credentials. Please refer to Push Messages documentation section to know how to get them.

There are two type of OneSignal credentials.

OneSignal App ID and OneSignal Auth Token are used for customer's mobile app.

OneSignal App ID for Drivers App and OneSignal Auth Token for Drivers App are used for dirver's mobile app (purchased separately).

Notifications

Notification Email - this is email to be used to receive "New Order" email notification
New Order Mail Subject - this string will be set as subject for "New Order" email notification
Notification Mail From Address - this string will be set as 'from email' field for "New Order" email notification
Notification Mail From - this string will be set as 'from name' field for "New Order" email notification

Stripe

You can set your publishable and secret keys here if you're using Stripe

PayPal

You can set your PayPal credentials here if you're using PayPal. You can switch between sandbox and production PayPal environments in mobile app by setting the corresponding checkbox.

Translation #back to top

Mobile app uses ngx-translate to do this. Locale files are available under src/assets/i18n/*.js. Each file name should be basically equals to locale code (like `en` for English.
You can change default locale by changing app.component.ts, for example to set default locale to Spanish:

                                this.translate.setDefaultLang('es');
                            

Please note, src/assets/i18n/es.js must be exists in this case.
ngx-translate docs

Backoffice uses standard Laravel mechanism. You have to change files under resources/lang folder.
Please also refer to Laravel localization docs

Special Artisan Tasksare available to convert backoffice locale files to YAML (can be used for translation services like oneskyapp.com):

                                php artisan locale:export
                                php artisan locale:import
                            
The first command will create .yml files in locale files folder, the second one will convert .yml files for .php files supported by Laravel.

How to setup server for backoffice #back to top

There is a good tutorial of setting up Ubuntu server for GiraffyDelivery system

Or you can always Get a paid Installation Service

App themization and customization #back to top

To do the app themization, you'll need the HTML and CSS/SASS technologies.

The main file you have to look at is src/theme/variables.scss in application source folder. This file contains some colors definition which could be changed to fit your needs.

Also some pages/components have their own stylesheets. For example there is src/pages/loading/loading.scss file which has some specific styles for 'loading' screen.

Please feel free to play around with these files, however we offer only paid support for customization and themization.

If you want to customize the app functionality, you have to know TypeScript programming language. Please refer to links section to find out more.

How to publish the mobile app #back to top

This is ionic app, so the publishing process is the same as for any other ionic app. The Ionic team has very good tutorial for this.

What you'll need to publish your app

  • For Android - Google developer account ($25 one time)
  • For iOS - Apple Developer account ($100/year)

What you'll need to make the local builds (except of nodeJS listed above)

  • For Android - Android SDK or Android Studio installed
  • For iOS - Apple Hardware with XCode installed

If you don't want to setup the complete build environment on your local machine, you can use Ionic Pro service. They have very good documentation and it's pretty straightforward, however you'll still need the developer accounts for required stores.