User Guide

Introduction

GoCart 3 is an open source ecommerce platform built on top of CodeIgniter. Our goal is not to build an enormous system, but rather to build an easy to use, easy to customize shopping cart that can be custom tailored to satisfy most ecommerce needs.

Requirements

It's important that before attempting to install GoCart your ensure your server fits the requirements to run the application.

The following features are required in order to properly run GoCart:

  • PHP 5.4 or greater
  • PHP_INTL library read more
  • URL re-writing (to remove index.php from the URL)
    • By default, GoCart 3 supports MOD_REWRITE on Apache
  • MySQL

Installation

Thanks for giving GoCart a spin. This guide will walk you through the basics of installing GoCart. If you haven't already, please review the section before this one titled Requirements to ensure that your server can actuall run GoCart.

Download GoCart
Start by heading over the to the GoCart website to download GoCart 3. If you have command line access to your server, you might find it more convenient to download GoCart directly to your server using cURL or wget.

cURL
curl -O https://gocartdv.com/downloads/gocart3.zip
Wget
wget https://gocartdv.com/downloads/gocart3.zip

Upload GoCart to your server
If you do not have command line access or you chose to download the GoCart 3 to your computer first, you'll need to unzip GoCart and upload the files to your servers public folder. If you do have command line access you should be able to unzip them directly on the server using the following:

Unzip
unzip gocart3.zip

The Installer
Now that you have the files for GoCart 3 uploaded to your servers public directory, go ahead and pull up your website in a browser. From here GoCart should detect that there are some configuration files missing and redirect you to the /install directory. If GoCart does NOT automatically direct you, try typing install into the URL directly ex. http://yourdomain.com/install

Once the installer loads you should have one or more notices displayed as well as a form for entering your database credentials. If you see any red alerts you will not be able to successfully install GoCart until those problems are dealt with. GoCart DOES require write access to the /application/config directory as well as the /uploads directory.

If you have not yet created a database for GoCart, do that now. Proceed to fill in the form with your database credentials. It's recommended that you use a database prefix in case your database is connected to multiple applications. Once the form is filled out, click the install button. If the system is able to connect to your database, the installer will generate the required configuration files and attempt to redirect you to the admin panel login page. The default username and password for the GoCart admin panel is admin/admin.

If your server is not configured for URL rewriting you will likely run into a 404 error on this redirect. If that is the case you will need to rectify this problem before using GoCart.

Configuration

GoCart supports the ability to configure some elements of the platform from the admin panel. It's a good idea to configure your GoCart installation before launching your site in order to have the system properly reflect your organization.

The GoCart configuration form is located in the Administrative submenu. Configuration is broken into some primary sections most of which are fairly self explanatory.

Shop Details
Shop details are where we set the most basic details of the shop. Here we're going to enter the Name of our store, GoCart Theme, Homepage, Products per Category Page, Default Meta Keywords & Default Meta Description.

Homepage is selectable and can point to any pages you have in your page list. It's important to note that themes developers have the ability to overwrite this feature by simply including a homepage.php file.

Default Meta Keywords & Default Meta Description are used on any portions of the system that are not a Category, Product, or Page.

Email Settings
This is one of the more important sections of the Configuration page. You will need to configure your shop's email. The Email To Address is the email address that orders are sent to when they are placed. The Email From Address the the email address that all correspondence from GoCart comes from.

GoCart uses the SwiftMailer PHP Class for sending email and supports 3 different methods that can be adjusted for your server. Most people will probably use Mail which simply uses PHP's internal Mail method. Other options include SMTP & Sendmail which will require additional settings.

Ship From Address
The Ship From Address is only required if you are utilizing a real time rates shipping method that requires a point of origin.

Locale & Currency
This section dictates how currency formatting that is used throughout the site is displayed. Some payment methods will also utilize the Currency field.

Security
There are 3 fields that require some explanation in the Security settings. DEV Username & DEV Password Are used for setting basic HTTP Authentication on your site. This is really useful for restricting access to a GoCart installation while building in order to easily mitigate any indexing by search engines or accidental orders from people who might happen to find the site before it's ready for prime time.

If Use SSL is checked in then the entire site will switch over to HTTPS. It's important to use SSL on a live ecommerce site. But only check this in once you have an SSL certificate installed for your site, otherwise you will get an error when you try to pull it up.

Package Details
These settings are utilized by some real time shipping rates modules.

Orders & Inventory
In GoCart 3, orders can have custom statuses typed in directly BUT there is also a droplist of default statuses available. This section of the Configuration details allows you to add or delete the default statuses available in the drop list. Enable Inventory Tracking turns inventory tracking on for your whole shop. Individual products can also have inventory turned on or off but if Enable Inventory Tracking is not checked in then none of the product level adjustments will have an effect. Allow customers to buy items that are out of stock will do exactly what it says. This will allow you to oversell an item while still maintaining a count of inventory in the database.

Tax Settings
Tax settings allows us to choose whether to apply taxes according to the customers billing or shipping address and whether or not to apply taxes to shipping charges. Setting actual tax rates for a geographic location is done in the Taxes & Localization section of the admin panel.

Shipping Methods

Shipping methods are specialized addons that extend GoCart's ability to provide additional shipping rates during checkout. By default GoCart only comes with the flat rate shipping module. Additional shipping modules can be found on our website. Installing a shipping module addon is not difficult but is likely best done by whoever installed the shopping cart.

Installing a Shipping Module
The first think you need to do is obtain the shipping module you want to install from the GoCart website. From here, unzip the contents and upload the folder to the addons directory of your GoCart installation.

Now you'll need to delete the manifest file in located at /application/config/manifest.php. The next time you load a page of your site, GoCart will automatically regenerate this file thus recognizing that you have a new module installed.

Now that your new module is uploaded to your GoCart installation we'll need to configure the shipping module. First login to your admin panel and click "Shipping Modules" found in the Administrative submenu. You should see your new shipping module listed in the table.

Click the green check mark button all the way to the right. This action will tell GoCart that you intend to use the shipping module and will enable you to configure it appropriately. If all goes well the checkmark button should be replaced by two buttons. Clicking the gear icon will bring you to a configuration form. Each shipping module is different and the required fields are specific to the service which they tap into or provide and thus should contain their own instructions for configuration.

Removing a Shipping Module
Clicking the red x button will tell GoCart that you no longer intend to offer the selected shipping method and GoCart will remove all settings related to it from the database.

You can completely remove a shipping method by deleting the related shipping method folder from the addons directory and then deleting the /application/config/manifest.php file. The next page load will once again regenerate the manifest.php file.

Payment Methods

Payment methods are specialized addons that extend GoCart's ability to accept payments during checkout. By default GoCart only comes with the COD (charge on delivery) payment module. Additional payment modules can be found on our website. Installing a payment module addon is not difficult but is likely best done by whoever installed the shopping cart.

Installing a Payment Module
The first think you need to do is obtain the payment module you want to install from the GoCart website. From here, unzip the contents and upload the folder to the addons directory of your GoCart installation.

Now you'll need to delete the manifest file in located at /application/config/manifest.php. The next time you load a page of your site, GoCart will automatically regenerate this file thus recognizing that you have a new module installed.

Now that your new module is uploaded to your GoCart installation we'll need to configure the payment module. First login to your admin panel and click "Payment Modules" found in the Administrative submenu. You should see your new payment module listed in the table.

Click the green check mark button all the way to the right. This action will tell GoCart that you intend to use the payment module and will enable you to configure it appropriately. If all goes well the checkmark button should be replaced by two buttons. Clicking the gear icon will bring you to a configuration form. Each payment module is different and the required fields are specific to the service which they tap into or provide and thus should contain their own instructions for configuration.

Removing a Payment Module
Clicking the red x button will tell GoCart that you no longer intend to offer the selected payment method and GoCart will remove all settings related to it from the database.

You can completely remove a payment method by deleting the related payment method folder from the addons directory and then deleting the /application/config/manifest.php file. The next page load will once again regenerate the manifest.php file.

Taxes & Localization

These settings are accessible in the submenu of Administrative under "Locations". GoCart uses the Locations to prepopulate the dropdowns for Country & State select menus within the customer address form. GoCart also enables users to set percentage based tax rates at the country, state/province (referred to as "Zones") and zip or postal code level (referred to as Zone Areas).

Countries
Countries edited, deleted, and sorted from the main list page. If there are countries you do not want to support you have two choices.
  1. Delete the country by clicking the red x button.
  2. Disable the country by clicking the edit button and unchecking "enabled" at the bottom of the form.
Countries can also support a national sales tax rate.

Zones
Zones are essentially states or provinces. To edit view the zones a country has, click the map marker button. This will bring you to a list of zones sorted alphabetically. If there is a zone you do not want to support you can handle them the same way as you handle countries.
  1. Delete the zone by clicking the red x button.
  2. Disable the zone by clicking the edit button and unchecking "enabled" at the bottom of the form.
A percentage based zone sales tax can also be set from the zone form.

Zone Areas
A Zone Area is essentially a zip or postal code. GoCart does not come pre-loaded with any Zone Areas and Zone Areas will not populate a dropdown based on a selected Zone. The only purpose of a Zone Area in GoCart is to provide a tax rate at the Zone Area level. This feature is useful for a businesses that needs to collect county or city/town sales taxes.

Administrators

The administrator list is accessible in the Administrative submenu and is where you go to add admin users to your GoCart Installation. GoCart supports two users types, Admins & Order users. An admin has access to every part of the administration panel. Order users only have access to the order management portion of the system.

Customers

Customers are accessible via the Sales submenu. From here customers can be added, edited, and deleted from GoCart. If you're using the Customer Groups feature, the group a customer belongs to can be changed by editing their account. Customer addresses are accessible by clicking the envelope icon on the desired row.

Customer Groups

Customer groups are accessible via the Sales submenu under "groups". By default GoCart comes with only one group titled "Retail". The name of this group can be changed but it cannot be deleted since it's requried for GoCart to have at least one customer group. Additional customer groups can be added by clicking the "Add New Group" button. For every group thats added there will be new fields related to that group created for products and categories.

Products will get an additional price, sale price, and enabled fields. Categories will get an additional enabled field. This allows us to price products differently for one customer group from another as well as show or hide a category or product all together from specific groups.

Categories

Categories are accessible via the Catalog submenu. The primary list page will display every category in your GoCart installation according to it's heirachy. Categories can be Hidden, Top Level, or a child of another category. Hidden categories will not be displayed in the navigation bar on the front end but are accessible via the URL.

To create a new category click the "Add New Category" button in the top right of the Category list page. To edit an existing category click the pencil icon to the right of the category you want to edit.

If you're utilizing the customer groups feature you will be able to enable or disable categories based on the type of customer logged in on the front end. You can also select whether a category is hidden, top level or a child category from the "Parent" select menu located on the right side of the form.

The Name and Description fields will generally be displayed at the top of the category page on the front end of your website.

The Slug field is what is displayed in the URL of your shop to reference the category https://yourdomain.com/category/slug-goes-here. It is not a required field. If you leave it blank, GoCart will generate a slug based on the title of the product.

The Sequence field will enable you to decide which order this category will show up in according to it's parent.

The SEO Title is the name that will be inserted in the pages "title" tag in the header of your cart.

The Meta Data field is where you can enter any special meta data you want for this category. Keep in mind when editing the meta data field you need to use well formed HTML otherwise you could break the view and function of the category on the front end.

Not every theme will utilize the excerpt or the image fields, but they are there for convenience in the event that they are required by a theme developer.

Using the Category Short Code
Categories can be displayed on a page using a shortcode. The shortcode formatting for a category looks something like this:

{{ category('slug', quantity) }}

In this case you would replace slug with the slug of the category you are wanting to display. Quantity should be replaced with the number of products you want to display. This is really useful for listing a small selection of products on a page outside the flow of the normal system.

Products

Products are accessible in the Catalog submenu. This is probably the most complicated admin panel in GoCart and there is a lot of functionality here. GoCart paginates the products list at 100 products per page. Products are searchable and can be filtered out by which categories they are in. GoCart supports two product types.

  1. Gift Cards
  2. Normal Products
Gift Cards are special products. When a gift card is sold a new gift card is added to gocart and an email is sent to the recipient. Gift Card products do not have as many editable fields standard products.

Products that have inventory tracking turned on, can be bulk edited from the list page by simply updating their available quantities and clicking the "Bulk Save" button in the top right of the list page.

The Product Form
To add a new product click the "New Product" button in the top right.

Inventory Fields include track stock, fixed quantity, and available quantity. Track Stock just tells GoCart that you want the system to decrement the available quantity each time it's purchased. Fixed quantity will restrict the number of items a customer can purchase to one.

SEO Information allows you to manipulate fields that are not generally visible to customers but are frequently used by search engines to designate the contents of a page. The URL Keyword is how the name of the product is represented in the URI ex. https://yourdomain.com/product/url-keyword Meta Tags allow you to enter your own meta tags in to the header. It's important to use well formed HTML in this field in order to avoid breaking the view and experience that a customer will be provided.

The Shippable field lets GoCart know if this product can be shipped and is utilized by shipping addons as a flag to incorporate this products information in to the algorithm for calculating shipping costs.

The Taxable field lets GoCart know if the cost of this product should be taken into account when calculating the taxes for a particular order.

The Weight field is utilized by some shipping addons to calculate the price of shipping.

Pricing in GoCart is based on Customer Groups. Each group will have 3 fields: Enabled, Price, and Sale Price.

Digital Products Tab
You may or may not see the Digital Products tab. This tab will only show up if you have digital products added to the system. To associate a digital product with this item, simply check in the checkbox to the right of the filename.

Products Categories Tab
The Categories tab will list out every category in your GoCart installation according to it's heirarchy. Each category has a checkbox and a radio button. The checkbox will ensure that the product is displayed in that category when accessed from the front end. The radio button represents the main, or primary category for a product. This is that category that is used to generate the breadcrumb that is displayed on the product page.

For convenience each customer group is represented along side the catgory names with a checkmark indicating whether or not the category is enabled for that particular group.

Product Options Tab
GoCart products support five different option types. To add a new option, select the option type you want to add from the select menu and click the add option button. This will create a new row in the options list. To edit details of the option Click the blue title of the newly added option. From here you can provide an option name and decide whether or not it's a required option by clicking the checkbox beside "Required".

A Checklist, Radiolist, and Droplist all support Option Items. Thes are simply the values that are selectable on the front end. Each Option Item supports a Name, Value, Weight, and Price. Weight and price will be added to the base weight and price of the Product the option belongs to.

Text fields and Text Areas can be provided default values as well as additional weight and pricing, but do not support multiple option values.

Options are drag and drop sortable by grabbing the blue button to the left of the option name and Option Items are sortable within the option they belong to by the same means.

Related Products Tab
To add related items to a product, search for the name of the related item you want to add in the text field on the left. Items that have similar names will show up in multi-select box below. Simply click the product you want to add and then click the "Add Related Product" button. The product will then move from the multi-select box to a table on the right. To remove a related product all you need to do is click the red X button beside the product name on the table.

Images Tab
To add an image or images to the product click the "Chose File" input under the Images tab. Once you have your image selected, click the upload button on the right. GoCart will then upload the image and add a new row to the images table. Images are drag and drop sortable by grabbing the image thumbnail and dragging it up or down. Images also support alt attributes and a caption though not every theme will make use of these fields. To choose a particular image as the main product image, click in the radio button beside Main Image.

Gift Card Products
To add a gift card product, click the "New Gift Card" button. Adding or editinga giftcard product is very similar to adding and editing a regular product. The gift card form however is much simpler. The one addition they have is the Predefined Values tab. Predefined Values are simply the suggested giftcard values provided to a shopper. To add a new Predefined Value click the "add" button on the tab and fill in the value. These Predefined values will be sorted numerically once the product is saved.

Digital Products

Digital Products are files that can be attached to one or more products. When one of those products is purchased the Digital Product is made available as a download to the shopper. Digital Products can be added on the Digital Products page found in the Catalog submenu. To add a new digital product, click the "Add File" button in the top right. Once on the digital products form, select the file you want to upload using the file input. Give your digital download a title and set the maximum number of times a customer can download the file once purchased. Setting Max Downloads to 0 will result in no limit set to the number of times a customer can download the file.

To attach a digital product to an item follow the instructions found under the Digital Products tab in the Product Form section of the User Guide.

Orders

The most recent orders are always visible on the dashboard of the GoCart admin panel but for a more detailed view you can access the Orders via the Sales submenu. Orders are sorted by the order number by default with the most recent orders displayed first.

Orders can be sorted by Order Number, Status, and Total. Orders can also be searched and limited by date. Orders can be downloaded in JSON format by clicking the download button to the right of the search form. Downloading orders will only export those orders displayed on the page.

An order's status can be edited from the order list page by either typing in a custom status and clicking the green check button, or by clicking the attached down arrow button and selecting a predefined status from the list and then clicking the green check button.

To get the full details of an order, click the order number of the order you're interested in looking at. This will being up the order detail page. The Order Detail page will allow you to change the status of an order or add additional notes. You can also click the packing slip button in the top left to get a printer friendly representation of the order with a focus on items and quantities.

You can delete an order from the order detail page by clicking the red delete button in the top right of the page. It's not generally recommended to delete an order since there is no way to recover it once it's deleted.

Reports

Sales Reports are accessible via the Sales submenu. Best Sellers can be displayed based on From and to Dates. Monthly Sales figures are available based on year.

Pages & Links

Pages and links are accessible in the Content submenu. To create a new page, click the "Add New Page" button in the top right corner. Hierarchically pages and links can be hidden from navigation, top level or under a different page or link. Also by manipulating the sequence field we can change the order in which a link or a page is displayed.

The Title is displayed at the top of a Page and is used for the Menu Title, SEO Title and Slug if they are not provided.

The Menu Title is an alternate title that is used in navigation.

The SEO Title is used in the title tag for the page.

The Slug is used to represent the page in the URL http://yourdomain.com/page/page-slug-here.

Some themes will allow you to use shortcodes in your content. The default theme has this ability and ties into the Banner tool. A short code will generally be encased in curly brackets and contain information pertinent to whatever content you're referencing. Check out the Banner section to see how to utilize the Banner shortcode on your pages.

Banners

Banners are groups of images organized into collections that can be displayed on pages using shortcodes. To access the banner system click banners in the content submenu. Before adding banners to GoCart you'll need to create a banner collection. You can add a banner collection by clicking the "Add New Banner Collection" button in the top right. The only field for a banner collection is the name. Enter the name of the collection and click save. Now, you can click the image button beside the collection you want to add banners to. New banners can be added by clicking the Add new Banner button.

The Banner Form
The Name field is for organizational purposes. This field allows you to provide a description for the image associated with the banner.

The Enable and Disable dates allow you to set an active range for the banner to be displayed. The dates can be used together or individually.

The Link field will provide a location to send the user if they click the banner. If you want the link to open in a new window, simply check in the new window checkbox.

Using the Banner Short Code
The Banner shortcode looks something like this {{ banner('collection_id', 'quantity', 'template') }}. In this case you would replace collection_id with the numerical ID of the banner collection you are wanting to reference. Quantity should be replaced with the number of banners you want to display and template should be replaced with the name of the view file used to render the banners.

Coupons

Coupon management is accessible in the Sales submenu. To create a new coupon, click the "Add New Coupon" button in the top right. Coupons can be for all products or just select products. If you want only select products, search for the products you want using the search field on the right. when the product shows up in the select box below click it and then click the "Add Product" button.

Coupons use can be limited by several factors.

  • Max Uses refers to the number of times the coupon can be used all together. This includes times used on a particular order.
  • Limit Per Order will restrict a coupons use in a single order.
  • Enable on and Disable on dates will restrict the time frame in which a coupon is valid.
None of the restrictions are required for having a functional coupon.

Reduction amount can be either a whole dollar amount or a percentage amount. First select the type of discount you want to offer and then set the value in the text field to the right. For dollar amounts do not include dollar signs or commas ex. $1,000.00 would be 1000.00. For percentage rates use whole numbers to represent the percentage. ex. %10 would be 10.

Gift Cards

Gift Cards are accessible in the Sales submenu. When someone orders a gift card through the shop and GoCart generates it, it will end up in this list. Gift cards can be deleted by clicking the red X button to the right of the gift card. If you want to add a new gift card, simply click the "Add Gift Card" button in the top right corner of the page.

Canned Messages

Canned Messages are used by GoCart for various purposes when corresponding with customers. By default the canned messages each use the variables that are available to them. Canned Messages utilize the Twig Templating language and can be edited but not deleted. You can visit the Twig website for more information about twig.

The variables available to each stock Canned Message are as follows:

  • Gift Card Email Notification
    • {{from}} represends the name of the sender.
    • {{site_name}} uses the name of the site as dictated by the GoCart Configuration page.
    • {{code}} is the unique gift card code that is generated by GoCart.
    • {{amount}} is the value of the gift card.
    • {{url}} is the URL to your website.
    • {{personal_message}} is the message submitted by the purchaser of the gift card.
  • Reset Customer Password
    • {{site_name}} uses the name of the site as dictated by the GoCart Configuration page.
    • {{password}} is the new password randomly generated by GoCart
  • Order Shipped Notification
    • {{customer_name}} is the name of the customer on the order.
    • {{site_name}} uses the name of the site as dictated by the GoCart Configuration page.
    • {{order_number}} doesn't really need an explanation.
  • Registration Confirmation
    • {{customer_name}} is the full name of the customer on the account.
    • {{site_name}} uses the name of the site as dictated by the GoCart Configuration page.
  • Order Submitted Confirmation
    • {{customer_name}} is the name of the customer on the order.
    • {{site_name}} uses the name of the site as dictated by the GoCart Configuration page.
    • {{order_summary | raw}} is a special variable. This one pulls in the view template for the order summary. the "| raw" tells GoCart that we have special data going here that shuold not be filtered.

Developer Guide

Introduction

GoCart 3 represents a shift in the development framework. With the exception of a few extended or replaced libraries GoCart has always been built on a relatively vanilla install of CodeIgniter. With GoCart 3, we decided to make some major changes.

While GoCart is still based on CodeIgniter (version 3), we decided to replace some fundamental pieces in order to more fully realize our goals and set the foundation for the future of our platform.

The Core

GoCart 3 begins by utilizing a feature in CodeIgniter to bypass the routing system and set a default controller and method. We're using this to direct CodeIgniter to the bootstrap controllers init method. This method is now the heart of GoCart.

The bootstrap controller has a big job.

  1. Initiate the session
  2. Load the manifest configuration file.
    • If there is no manifest file, we generate one based on the modules we find.
  3. Autoload some essential libraries, helpers, and models.
  4. Set GoCart configuration from the database into the Config class.
  5. Initialize any HTTP Authentication as designated by the GoCart configuration.
  6. Load AltoRouter, parse the URI route and load the appropriate controller/method combination.

What Happened to CodeIgniter?

CodeIgniter is still the framework that underpins GoCart but because of the organization we were going for, we had to make adjustments. CodeIgniter has really poor support for modules out of the box and the popular HMVC extension didn't quite do what we wanted either. CodeIgniter also has poor support for namespaces.

Our adjustments overcome this by accessing CodeIgniter through a static class and mapping routes manually through AltoRouter. Rather than a controller inheriting the CodeIgniter super object, a Controller accesses CodeIgniter through the static facade.

CodeIgniter Super Object
The static facade stores the CodeIgniter object in a private variable and references it through the __callStatic magic method. This enables us to access CodeIgniter from anywhere in GoCart with ease.

Because the modules support namespacing we want to prepend the CodeIgniter static class with a backslash to reference the root namespace. Rather than accessing a CodeIgniter library or model like this:

$this->library->method();

We access it like this:

\CI::Library()->method();

Sessions
The CodeIgniter session class has always cause a few problems for GoCart. Because of this GoCart has been using it's own session class for several releases now. GoCart 3 continues this trend. The session class in GoCart 3 is very similar to the Session library from CodeIgniter 2.* with the exception that it utilizes native sessions.

Views
GoCart 3 no longer utilizes the CodeIgniter view class. Rather we have a custom built view class that operates better within the new module based organization.

The new View class has two methods view which displays the contents of a view file and get which returns the contents as a string. The Front & Admin Core controller classes expand the functionality of the View class by allowing a controller to automatically include a header and footer. Controllers can access a view without the header and footer by referencing the partial method.

These two additional methods are accessible within any controller that extends Front or Admin via $this->.

What Are Modules

Modules are compartmentalized components. This is an organizational method that enables modules to be aware of themselves and replaced without having a major impact on the rest of the system.

It's important to note that GoCart 3 has two folders where modules can be stored.

  1. /application/modules
  2. /addons
The modules located in the application/modules folder are core components. While they are compartmentalized there are places where they are more tightly coupled with other modules than you would find in an addon module. Each module should contain the files for it's own controllers, views, models, language files and manifest.

The Manifest File

GoCart has many manifest files. Each module whether an addon or core module requires a manifest file. The manifest file contains the routes for a particular module as well as any additional information the module needs to provide GoCart. In the case of addons such as payment or shipping methods, the manifest file will add the module to GoCarts list of available shipping and payment methods.

When GoCart initiates if there is no master manifest file found in the application/config folder, GoCart will loop through every addon and collect the manifest file. From here GoCart will make a single master manifest file that includes the routes, shipping methods, payment methods, and a classmap (for autoloading).

When adding new modules to GoCart or manipulating classnames or routes etc. within a module, the master manifest file must be deleted so GoCart can properly refresh the information contained within.

The formatting for a route, shipping module, and payment module within the manifest file is as follows.

Routes

$routes[] = ['HTTP VERB', 'uri/route/to/map/to', 'Namespace\Classname#method'];

For more information about supported HTTP Verbs, URI routes check out the AltoRouter section

Shipping Method
$shippingModules[] = ['name'=>'Shipping Method Name', 'key'=>'Database Key', 'class'=>'Class Name'];

Payment Method
$paymentModules[] = ['name'=>'Payment Method Name', 'key'=>'Database Key', 'class'=>'Class Name'];

GoCart comes with a basic shipping (flat rate) and payment (COD) module that are there as a starting place for developing your own shipping and payment methods. These built in modules have all the required methods stubbed out to make integrations easier.

Themes

GoCart themes are located in the base folder under the themes directory.

By default, GoCart views are coupled with the module they are associated with. Themes allow developers to override module level views. To override a module view simply create a view in your theme with the same filename as the view you want to override. The new GoCart 3 view class will automatically pick the view file from your theme instead of the one located in the module.

Shortcodes

GoCart 3 is laying the foundation for front end shortcode support. By default, GoCart comes with shortcodes for categories and banners. Creating additional shortcodes requires adding a new line to your module's manifest file.

The line below is a sample manifest entry for a new shortcode. This example is taken from the Category module.

$themeShortcodes[] = ['shortcode'=>'category', 'method'=>['GoCart\Controller\Category', 'shortcode']];

A shortcode manifest entry requires a key called "shortcode" and a key called "method". Creating a shortcode will result in a Twig_SimpleFunction being available for use in your content. The shortcode key will be the function name. The Method key can either be an array with the first value being a classname and the second value being a method name within that class, or a string that directs to a global function.

Remember to delete the master manifest file in the application/config directory so it can regenerate before trying out your new shortcode.

AltoRouter

GoCart 3 uses AltoRouter for mapping controllers and methods to URLs. AltoRouter was chosen because it's lightweight and flexible and was easily implemented.

Rather than offering an exhaustive explaination of how AltoRouter works, we will simply explain some simple URI formatting examples here. For more in depth information on AltoRouter you can read it's documentation at altorouter.com.

AltoRouter supports several HTTP verbs. The modules in GoCart thus far only utilize two, GET and POST though there is nothing stopping someone from using the others. The supported verbs are:

  • GET
  • POST
  • PATCH
  • PUT
  • DELETE
To use multiple HTTP verbs on a single request separate them with a pipe ex. GET|POST.

AltoRouter can accept a URI segment as a specific variable type. A URI variable is encased in square brackets and optionally prefixed with a requirement for what sort of variable should be accepted.

GoCart generally uses the blank prefix and the "i" prefix for most needs. ex. [:varname] or [i:intName]. You can follow the square brackets with a "?" for an optional variable.

To learn more about AltoRouter check out it's website at altorouter.com.