DOCSEARCHbyAlgolia
Submit Docs

Mall for OctoberCMS

repository·develop·Indexed 41 days ago

https://github.com/offline-gmbh/oc-mall-plugin

A fully featured, all-inclusive e-commerce solution for OctoberCMS. It provides product and variant management, complex checkout flows, shipping and tax calculations, and multi-currency support. Includes built-in integrations for Stripe, PayPal, and PostFinance, as well as support for custom payment providers via the PaymentProvider class.

Tokens
26.9K
Snippets
94
Records
158
Agent score
51%

What's inside Mall

  1. Overview of Mall e-commerce features

    develop

    Mall is a comprehensive e-commerce solution for OctoberCMS providing the following core capabilities:

    • Product Management: Handles Products, Variants, Virtual products (downloads), and Product services (e.g., warranties).
    • Inventory & Pricing: Stock management, multi-currency support, and specific pricing for different customer groups (including unlimited additional price fields like reseller or retail).
    • Customer Experience: Wishlists, reviews, ratings, and multi-language support (via RainLab.Translate).
    • Checkout & Logistics: Out-of-the-box support for Stripe, PayPal, and PostFinance, with support for custom payment providers. Includes shipping and tax management.
    • Order Management: Custom order states and flexible e-mail notifications.
    • Integrations: Integrated with RainLab.User and supports Google Tag Manager and Google Merchant Center.

  2. Understand the relationship between Products and Variants

    develop

    In oc-mall, a Product is the central entity containing properties like price, description, and stock.

    • Simple Products: Used for goods that do not have complex options (e.g., a CD or a Vinyl record). These can be bought directly and have their own independent stock.
    • Variants: Used for goods with complex properties (e.g., a T-shirt available in different sizes). Variants belong to a parent Product and inherit all its properties except those explicitly changed (like size or color).

    Key Rules:

    1. If a Product has Variants, the parent Product itself cannot be purchased; only the individual Variants can be bought.
    2. Stock Calculation: Each Variant has its own stock value. The total stock value of the parent Product is the sum of all its Variants' stock values.

  4. Define product schemas using Property groups in Categories

    develop

    You can define the "Schema" of products within a specific category by adding Property groups to that Category.

    When a Property group is added to a Category, every Product assigned to that Category (or its subcategories) will automatically have all properties from that group available.

    Example Workflow:

    1. Create a Category named Shirts.
    2. Add the Size Property group to the Shirts category.
    3. Add the Color Property group to the Shirts category.
    4. Any Product placed in the Shirts category will now have Size and Color properties available for configuration.

  5. How pricing information works in Mall

    develop

    Pricing information is managed through a central Price model. Most core models in the Mall plugin have a price() relationship that returns this data.

    Key behaviors:

    • Models with pricing: Product, Variant, ShippingMethod, ShippingMethodRate, PaymentMethod, CustomField, CustomFieldOption, and CustomerGroup.
    • Model Types: While most models return a base Price model, Product and Variant return a specialized ProductPrice model which extends the base Price model.
    • Currency Context: The price() relationship accepts an optional Currency attribute (ID, code, or Currency model instance). If omitted, the currently active currency is used.
    • Special Price Fields: Some models include specific price relationships for conditional logic, such as availableBelowTotal() on ShippingMethod or totalToReach() on Discounts. These return the standard Price model.
    // Accessing standard price
$product->price(); // Returns OFFLINE\Mall\Models\ProductPrice

// Accessing special price fields
$shippingMethod->availableBelowTotal(); // Returns OFFLINE\Mall\Models\Price
$discount->totalToReach(); // Returns OFFLINE\Mall\Models\Price

// Specifying currency by code
$product->price('EUR');

// Specifying currency by ID
$product->price(2);

// Specifying currency by model instance
$currency = \OFFLINE\Mall\Models\Currency::find(2);
$product->price($currency);

  6. Understand the Variant model relationship to Products

    develop
    In the Mall plugin, a Variant model is a child of a Product model. Variants inherit most data from their parent Product, meaning most attributes and methods available on a Product are also available on a Variant. Use the Variant model when you need to represent specific versions of a product that differ by properties like size or color.

  7. Understand the purpose of Properties

    develop

    Properties are used to describe Products or Variants in your store. They serve two primary functions:

    1. Product Description & Filtering: Properties allow users to find products by filtering on specific attributes (e.g., filtering by 'Color' or 'Material').
    2. Variant Definition: Different combinations of property values can be used to define specific Variants of a product (e.g., a shirt available in 'Size: M' and 'Color: Blue').

  8. How virtual products work

    develop

    Virtual products are non-physical items (like e-books or digital downloads) offered to customers as files.

    Key behaviors:

    • Delivery: After payment is processed, the customer receives an email containing personal download links.
    • Checkout: If an order consists exclusively of virtual products, the shipping step is automatically skipped during the checkout process.
    • File Management: Each virtual product can have one file attached by the admin. Users always download the latest version of the file uploaded by the admin, provided their download grant is still valid.
    • Customization: You can extend the system to generate unique, customer-specific files (like personalized gift cards) by listening to specific events.

  9. Understand product file grants

    develop

    When a customer pays for a virtual product, the system creates a ProductFileGrant. This grant controls the access rights to the digital file.

    Properties of a grant:

    • Duration: Specifies how many days the customer can download the file.
    • Usage Limit: Specifies how many times the file can be downloaded.
    • Access Control: You can configure whether a user must be logged in to use the download link. If this is not enabled, anyone with the link can download the file.

  10. Restrict taxes to specific countries

    develop

    When configuring a tax, you can optionally define country restrictions.

    • Restricted: If you select specific countries, the tax will only be applied if the order's shipping destination matches one of the selected countries. If the destination is not in the list, the tax is ignored.
    • Worldwide: If no country restrictions are defined, the tax will be applied to all orders worldwide.

  12. Handle payment outcomes with PaymentResult

    develop

    The process method in a PaymentProvider receives an instance of PaymentResult. You must call one of its three methods to finalize the transaction. Calling these methods automatically logs the payment attempt and updates the associated order.

    • $result->success($data, $response): Marks the payment as successful. You can pass payment data and the raw response object.
    • $result->fail($data, $response): Marks the payment as failed. Use this for declined cards or connection errors.
    • $result->redirect($url): Used when the payment requires a redirect to an external gateway.