Cart Boxx – Developer’s Quick Start Guide

INTRODUCTION
THANK YOU FOR CHOOSING CART BOXX

Cart Boxx is sort of my… pet project after years of working with OSCommerce, Magento, WooCommerce, and more. With the rise of AJAX, mobile applications, and the need for third-party integrations, I just thought that a shopping cart with an API end-point makes absolute sense. So here it is, a shopping cart with an API end-point.

As someone who has gone through countless hours of reading development tutorials, I totally understand the pain… So I am going to do things a little differently with Cart Boxx. I have kept it as structural and minimal as possible, so development should be a breeze.

In this guide, I will go through creating a custom theme, API, and library function for Cart Boxx – as straightforward as possible. Hopefully, this quick start guide is all that is required. All right, no more BS, let’s get started.

 

 

NAVIGATION
TABLE OF CONTENTS

Section A
Folders

Section B
Themes

Section C
Libraries

Section D
API

Closing
That’s it!

 

 

SECTION A
FOLDERS

All the libraries, API, and critical files are kept in the core folder, protected by a “deny all .htaccess” file.

cart-boxx/
  core/ -- The critical core files
    admin/ -- The admin panel
    api/ -- The API processes
    elfinder/ -- Third-Party open source file manager
    hook/ -- Hooks and checks used in libraries and API
    lib/ -- Library files
  public/ -- All that is open to the public
  themes/ -- Develop you front-end shop themes here
  uploads/ -- The user uploads are kept here

 

SECTION B
THEMES

Building Your Theme – The First Step

  • Create a new “my-theme” folder in the themes folder. I.E. themes/my-theme/ (You can name it whatever you wish, I will just use “my-theme” as an example here)
  • Update SITE_THEME in the database config table and set it to “my-theme”.
  • Create a new “index.php” in your “my-theme” folder.
themes/my-theme/index.php
<!DOCTYPE html>
<html>
<body>
  Hello World!
</body>
</html>

That’s it! Visit your website and you have just created a theme for Cart Boxx.

 

Building Your Theme – Recommendation

It will be very tedious to copy the HTML layout over and over again for the entire website. So I will recommend creating a template folder, for example, splitting the HTML into a header and footer section:

themes/my-theme/template/header.php
<!DOCTYPE html>
<html>
  <head>
    <title><?=$_PAGE['title']?></title>
    <meta name="description" content="<?=$_PAGE['description']?>">
    <script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
  </head>
  <body>
    <nav>Main Navigation</nav>
    <main>

Now for the other half.

themes/my-theme/template/footer.php
   </main>
    <footer>Footer</footer>
  </body>
</html>

Now to use them on your homepage.

themes/my-theme/index.php
<?php
$_PAGE = [
  "title" => "My Awesome Site",
  "description" => "Page description goes here"
];

include PATH_THEME . "template/header.php"; ?>
Hello World!
<?php include PATH_THEME . "template/footer.php"; ?>

PATH_THEME is generated by Cart Boxx, and it points to your theme folder. Click here for the complete list of definitions and session variables.

 

 

Building Your Theme – The Pages

Cart Boxx adopts a very simple system. If you access http://your-site.com/page, it will attempt to look for page.php in the theme folder. So if you want to create an about page at http://your-site.com/about, just create an about.php in your theme folder.

themes/my-theme/about.php
<?php
$_PAGE = [
  "title" => "About Us",
  "description" => "Page description goes here"
];

include PATH_THEME . "template/header.php"; ?>
We are awesome. We will take over the world some day.
<?php include PATH_THEME . "template/footer.php"; ?>

 

Building Your Theme – 404

Cart Boxx will throw a 404 when it cannot find the requested file. By default, the 404 page will use “core/admin/PAGE-404.php”. But you can build your own custom “404 – file not found” page.

themes/my-theme/404.php
<?php
$_PAGE = [
  "title" => "404 - File Not Found",
  "description" => "Abducted by aliens"
];

include PATH_THEME . "template/header.php"; ?>
Sorry, we cannot find your requested page. We think it has been abducted by aliens.
<?php include PATH_THEME . "template/footer.php"; ?>

 

Building Your Theme – Activate

What is activate? By default, new users will receive an email on registration and need to click on a link to activate/confirm their email account. The activate page is used for this very purpose, and on top of that, forgotten passwords will also redirect to here. As with 404, if you do not create an activate page, it will default to core/admin/PAGE-activate.php.

themes/my-theme/activate.php
<?php
$_PAGE = [
  "title" => "Account activation",
  "description" => "Account activation"
];
$status = json_decode($_CB->sysmsg, 1);
include PATH_THEME . "template/header.php"; ?>
<h2><?= $status['cb-status'] ? "Success" : "Opps. An error has occured" ?></h2>
<p><?= $status['cb-msg'] ?></p>
<?php include PATH_THEME . "template/footer.php"; ?>
  • The activation/forgot password is already processed by Cart Boxx, the activate page is only used to show the result.
  • $_CB->sysmsg is a JSON string that contains the process result and message.
  • cb-status – True for pass, false for failure.
  • cb-msg – Contains the success/error message.

 

Building Your Theme – URL Depth

Cart Boxx collapses the URL folders into $_CB->url. For example, http://your-site.com/shop/toys –

  • $_CB->url[0] = “shop”
  • $_CB->url[1] = “toys”

By default, it will throw a 404 error for anything more than 1 level. For example, the user will get a 404 error while accessing http://your-site.com/shop/toys. Some people may think that it does not make any sense, but this is to prevent “infinite” URLs – I.E. http://your-site.com/shop/toys/1/2/3/4/5/6/7/8/9 will still show shop.php, which is very confusing to search engines. However, you can control the URL depth, which we will go through next.

 

Building Your Theme – Pre-Pages

Let’s say you want to create a new page to show all the categories at http://your-site.com/shop, and http://your-site.com/shop/CATEGORY will show all the products within the selected category. Start by creating a new PRE-shop.php in your theme folder.

themes/my-theme/PRE-shop.php
<?php
// ALLOW URL DEPTH OF 2
$_CB->udepth = 2;

// GET PRODUCTS IF CATEGORY IS PROVIDED
$_CB->extend("Catalog");
if ($_CB->url[1]) {
  // GET THE CATEGORY FIRST
  $cat = $_CB->Catalog->getCatSlug($_CB->url[1]);

  // INVALID CATEGORY SLUG
  if (!is_array($cat)) {
    header("HTTP/1.0 404 Not Found");
    require PATH_THEME . "404.php";
    exit();
  }

  // GET PRODUCTS IN CATEGORY
  $pdt = $_CB->Catalog->getPdtCat($cat['category_id']);

  // SET THE PAGE META
  $_PAGE = [
    "title" => $cat["category_name"],
    "description" => $cat["category_description"]
  ];
}
// GET ALL CATEGORIES OTHERWISE
else {
  $cat = $_CB->Catalog->getAllCat();

  // SET THE PAGE META
  $_PAGE = [
    "title" => "My Shop",
    "description" => "All good stuff."
  ];
}
?>
  • PRE-pages are loaded before the actual pages. I.E. PRE-shop.php will be included before shop.php.
  • You can use these PRE-pages to do processing – Keep your HTML files clean.
  • Remember that Cart Boxx only allows 1 folder by default? You can override it by setting $_CB->udepth;
  • The $_CB->extend should be pretty self-explanatory, it simply tells the Cart Boxx engine to extend the Catalog library.
  • If you want, you can read all the catalog functions here.

Now you can build the shop.php.

themes/my-theme/shop.php
include PATH_THEME . "template/header.php";
if ($_CB->url[1]) {
  // SHOW PRODUCTS IF CATEGORY SELECTED
  print_r($pdt);
} else {
  // SHOW ALL CATEGORIES OTHERWISE
  print_r($cat);
}
include PATH_THEME . "template/footer.php";

 

SECTION C
LIBRARIES

The Basics 

The Cart Boxx engine is pretty much self-contained in the index.php file. On startup, a $_CB = new CartBoxx object will be created, and that is very much where we need to build on. The core concept with the Cart Boxx engine is extension – We create objects and “stack” them on top of the existing $_CB object. For example:

$_CB->extend("User");
// The extend function will require "core/lib/LIB_User.php" file.
// Then extend itself with $_CB->User = new User();

 

 

Building Your Own Library

So yep, creating your own library and building on top of Cart Boxx is as simple as:

  • Create a new PHP file in the core/lib folder.
  • Let’s say you want to create a new coupon library, we will name it LIB_Coupon.php
  • Next, simply declare Class Coupon in LIB_Coupon.php
  • That’s it. When you call $_CB->extend(“Coupon”), Cart Boxx will automatically initiate $_CB->Coupon = new Coupon().

Do take note that there is on small “hack” in the extend function and Cart Boxx base object – The extend function will “link” the newly initiated object back to the “root” Cart Boxx object.

$this->$branch->CB =& $this;

This means that you can use pretty much any other branches in your own library. For example, you want to create a function to fetch coupons from the database in your new coupons class:

core/lib/LIB_Coupon.php
Class Coupon{
  function get($code=""){
    $coupons = $this->CB->DB->select("SELECT * FROM `coupons` WHERE `coupon_code`=?", [$code]);
    // Of course, you can also access other modules if you want.
    // $this->CB->Users->get();
    return $coupons;
  }
}

 

SECTION D
API

API Basics

By default, the API is deployed at:

  • https://your-site.com/api/ for the non-sensitive user requests.
  • https://your-site.com/api/admin/ for the sensitive administrator requests.

They are separated by modules. Let’s say that if you want to sign a user in, you should post a “req: login”, along with the user email and password to https://your-site.com/api/user. Administrator requests work the same, but they require a valid administrator to be signed in first. For the complete API reference, please check out the rest of the Cart Boxx documentation.

 

Building your own API

The concept of Cart Boxx API works very much like the extensions. When someone accesses https://your-site.com/api/coupon, Cart Boxx will look for core/api/API_coupon.php. So if you want to create your own coupon API:

  • Create an API_coupon.php file in core/api/ folder.
  • You should also create an API_ADMIN_coupon.php file for the administrative functions (add, edit, delete coupons).

 

 

API – Example & Maintaining the standards

core/api/API_coupon.php
<?php
$_CB->extend("Coupon");
switch ($_POST['req']) {
  /* [INVALID REQUEST] */
  default:
  $_CB->verbose(0,"COUPON","Invalid request","",1);
  break;

  /* [GET COUPON] */
  case "get":
    // BEST DO CHECKS HERE FIRST
    $code = $_POST['code'];
    if ($code=="") {
      $_CB->verbose(0,"COUPON","Invalid input","",1);
    }
    $_CB->verbose(1,"COUPON","OK",$_CB->Coupon->get($_POST['code']),1);    
    break;
}
?>
  • $_CB is already initiated in the API file, and you can readily use it.
  • Do take extra care in checking and sanitizing the data that users send.
  • You can quickly build a “standard” Cart Boxx system response message with $_CB->verbose.
  • The first parameter of verbose is the process status – True for pass, false for fail.
  • Second parameter is the API module code. Used for your own debugging uses, so you know which module went wrong.
  • Third parameter is the system message.
  • Fourth parameter is the “more” field, use this to reply all the requested data.
  • The last parameter is a “stop” field. If set to true, it will output the message in a JSON and halt all other processes.

 

THE END
THAT’S IT

That is Cart Boxx in a nutshell and good luck!

Leave a Comment

Your email address will not be published. Required fields are marked *