Get Familiar With LiteCart's Components

Coding with LiteCart is fun. But setting yourself into learning a new platform can be hard work if you don't know where to look. On this page we have gathered some notable information that will help you find and understand the platform just a little better.

Folder Referencing

LiteCart uses two ways for referencing the application root folder:

  • FS_DIR_APP – File system (server side) path
  • WS_DIR_APP – Web system (client side) path

File System Paths (FS_DIR_APP)

FS_DIR_APP is the absolute path to the application root. It is used on the server side and is translated to something like /var/www/litecart/ or C:/xampp/htdocs/litecart/ depending on machine and installation.

Example below:

include FS_DIR_APP . 'includes/app_footer.inc.php';

Web System Paths (WS_DIR_APP)

WS_DIR_APP is the web path to the application root on the client side (the URL path). It is translated to something like /.

Example below:

<script src="<?php echo WS_DIR_APP . 'assets/script.js'; ?>"></script>

Folder Structure

In the early era of LiteCart, we adapted a directory layout that was reminiscent of osCommerce. We specifically targeted osCommerce users for migrating to LiteCart and they needed a folder structure they could recognize. That is no longer the case and LiteCart 3.0 comes with a fresh, new directory structure.

This is the current folder structure as of LiteCart 2.3+:

/                   – Root
├── admin/          – Backend
│   ├── *.app/      – Admin apps
│   └── *.widget/   – Dashboard widgets
├── cache/          – Cache Directory
├── data/           – Data Storage
├── ext/            – Extensions/Extras/External/Vendors/Assets
│   ├── jquery/
│   └── ...
├── images/         – Graphics
├── includes/
│   ├── abstracts/  – Class templates
│   ├── boxes/      – Partials
│   ├── entities/   – Entity Objects
│   ├── functions/  – Defined functions called via lib_func.inc.php using functions::name()
│   ├── library/    – System nodes and events
│   ├── modules/    – Modules
│   ├── references/ – Read-only factory model reference objects
│   ├── routes/     – Route mapping
│   ├── templates/  – HTML and Output
│   └── wrappers/   – Wrappers, Service Layers, and Clients
├── install/        – Installation wizard
├── logs/           – Application logs
├── pages/          – Documents
└── vmods/          – Modifcations
    └── .cache/

Please note the folder structure is subject to change in LiteCart 3.0.0.

System Nodes / Library

The very core of LiteCart contains of a set of system nodes that are the arms of the platform. Think of it as an octopus where each limb is a system node. Each node is specialized on a specific thing (e.g. language, currency, database, etc.). The main purpose of a system node is to hold and process information, and it can respond to certain stated events.

LiteCart's on-demand designed framework makes the platform super fast! Once you are accessing a node, LiteCart will automatically load only the necessary php files into the system.

The system nodes are static classes. They are accessed by simply typing nodename::method() or nodename::$variable.

The following command will load the language component ~/includes/library/lib_language.inc.php, initiate it, detect the language to be used, set up some application events, and collect a result from the database and return it. All from the command:

echo language::translate('title_hello_world', 'Hello World');
$formatted_price = currency::format_html(199.99, 'USD');
$tax = tax::get_tax($price, $tax_class_id, $region);

Database Connections

A connection to the default database is opened automatically when needed by a query.

To make a MySQL query request and fetching the results, the standard procedure is the following:

$query = database::query(
  "select * from ". DB_TABLE_PREFIX ."mytable
  order by id;"
);

while ($row = database::fetch($query)) {
  ...
}

Note that all LiteCart tables are preceeded by a table prefix defined as DB_TABLE_PREFIX located in includes/config.inc.php.

Helper Functions

No need to keep track of included function files. Functions are dynamically loaded when needed through the system node found in lib_functions.inc.php.

All helper functions are stored in ~/includes/functions/. The filenames are preceeded by the preifx "func_". The name of the functions must begin with the collection name. Example: func_form.inc.php would host all helper functions named form_something().

To load ~/includes/functions/form.inc.php (if not previously loaded) and call form_draw_textarea():

functions::form_draw_textarea()

Entity Objects

Entity objects are class objects that control object data and their mappings to the database. They are similar to Object Relational Mappings. By initiating an entity, PHP will autoload the required file for you and retrieve it's structure and data from the database.

To create a new product and give it an English name:

$product = new ent_product();
$product->data['name']['en'] = 'Test product';
$product->save();

To update the email address for customer id 34:

$customer = new ent_customer(34);
$customer->data['email'] = 'user@domain.com';
$customer->save();

Reference Objects

Reference objects are a factory designed read-only class model that can return partial parts of entity data without wasting unnecessary resources. This means only the queries necessary will be made to the database.

Access the database and output the English product name for a product:

$product = new ref_product($id);
echo $product->name;

Or

echo reference::product($id)->name;

Not all entity objects are available as reference objects. When they are not, LiteCart will fallback to extracting the data from the entity object by the same name. Here we access the an order through the reference node although there is no file ref_order.inc.php:

reference::order($id)->customer['company'];

Links

There are 3 types of links that can be output by LiteCart. ilink(), link(), and rlink().

These variants also have a href_*() method to automatically escape html characters when used as a html node parameter. Escaping is equal to htmlspecialchars(document::link(...)).

Internal Links

Internal links are for logical pages of the platform e.g. products, categories, customer service, etc.

This is an example how to redirect to the product page (meaning pages/product.inc.php) for product id 123:

header('Location: ' . document::ilink('product', ['product_id' => 123])); // ilink() will rewrite this URL
exit;

External Links

External resources do not need the ilink resolver as they are not virtually routed links.

$link = document::link('https://wwwsite.com/resource', ['foo' => 'bar']);
$link = document::link(WS_DIR_APP . 'images/myimage.png');

When special characters are not allowed, i.e. inside HTML element parameters use document::href_link():

<a href="<?php echo document::href_link(WS_DIR_APP . 'search.php')); ?>">My link</a>

Resource Links

LiteCart 2.3+ has support for links to external resources e.g. js, css, etc. A resource link will be appended with a unique timestamp to the URL (example ?_=1628729661) for when it was last updated. The timestamp prevents the browser from loading a cached resource when it has been updated. Note that the folder path is the file system path, not the web path like in link().

The following code will include a stylesheet on a page:

<link rel="stylesheet" href="<?php echo document::href_rlink(FS_DIR_APP . 'assets/styles/mystyle.css'); ?>">

Sessions

Session handling in LiteCart is very simple. To get or set a session variable, just access it through the system node, e.g. session::$data['foo']. LiteCart will automatically load the system node on demand, initiate the session, and access the session variables. Security is built in, so all you need to think of is what to get or set.

session::$data['foo'] = 'bar';

Translations

For your best convenience we are storing translations in the database. While fetching a translation you can insert a default translation if not previously stored. This is done by providing the first default translation straight in the code. English is always the framework language and default translation. If translations are missing for any other languages, an English translation will be returned.

To output a translation for title_hello_world and inject an English translation to the database (if not previously injected):

echo language::translate('title_hello_world', 'Hello World');

Template Layouts

The document system node collects snippets of content that are output to placeholders in a layout or view file.

To store a global snippet named foo_bar:

document::$snippets['foo_bar'] = '<h1>Foo bar!</h1>';

To insert a placeholder for the snippet content in a page layout file:

{snippet:foo_bar}

Then, to change layout file for the output to ~/includes/templates/my_template.catalog/layouts/my_layout.inc.php:

document::$layout = 'my_layout';

Note: Any placeholders that do not have snippet content will be removed before output to browser.

Template Views

LiteCart tries to separate logic from the design by the use of views.

Gather some data (called snippets) and pass them to a view for stitching together:

$my_content = new ent_view();
$my_content->snippets['greeting'] = 'Hello World';
echo $my_content->stitch('views/myview');

The template view file includes/yourtemplate/views/myview.inc.php supports the following syntax:

<h1>{snippet:greeting}<h1>
<h1><?php echo $greeting; ?><h1>

Virtual Modifications

LiteCart has a built-in virtual modification system called vMod. Developed exclusively for LiteCart.

Wrap all included php scripts with vmod::check(). It will check if there is a virtual modification, apply it to the source code, then return the modified script for inclusion.

include vmod::check(FS_DIR_APP . 'includes/directory/file.inc.php');

Note: Due to the nature of virtual modifications it is not safe to rely on the FILE and DIR constants in PHP for returning the path or directory to self. Instead use FS_DIR_APP .'path/file.txt'.

Client Wrappers

Client wrappers are objects that wrap functionality together like an API client.

This is an example how to use the HTTP client for posting data to an external machine:

  $client = new wrap_http();
  $response = $client->call('POST', 'https://www.domain.com/destination', $post_data);

Revisions

Top Editors
Recently Edited Articles