Add

int
CSaleBasket::Add(
  array arFields
);

The method Add adds a product item to the basket unless it is already added, or updates the product properties (increases its quantity) is this product has already been added to the basket.

The array arFields should contain all the product properties required by the e-Store module because this module is independent of the other modules in the system.

You can add products to basket from any page, static or dynamic, from any place in the code (e.g. from the Commercial Catalog). Some modules provide wrapper functions which helps to add products to basket. For example, the Commercial Catalog module exports function Add2Basket($PRICE_ID, $QUANTITY).

Parameters

Parameter

Description

arFields

Associated array containing new parameters of basket item. The following keys are possible: PRODUCT_ID - the product ID unique within the module; PRODUCT_PRICE_ID - the product auxiliary ID; PRICE - price of a single product item; CURRENCY - currency of the PRICE; WEIGHT - weight of a single product item ; QUANTITY - number of product items. If QUANTITY is null, the product is removed from the basket; LID - the site from which purchase originates; DELAY - flag "save for later purchase" (Y/N); CAN_BUY - flag "can be purchased" (Y/N) - can be set automatically if the actualization callback function is provided; NAME - product name (required); CALLBACK_FUNC - name of the callback function used to maintain the basket actuals (see CSaleBasket::Add for details); MODULE - the module adding the product; NOTES - other special notes; ORDER_CALLBACK_FUNC - name of the ordering process callback function (see CSaleBasket::Add for details); DETAIL_PAGE_URL - URL of the page with the product details; PROPS - array of properties of the product in the basket. Each element of this array is its turn an array of the following format: array("NAME" => "Property name", "CODE" => "Property identifier", "VALUE" => "Property value", "SORT" => "Sort weight")

Returned values

Returns the ID of the new basket item.

Example

<?
if (CModule::IncludeModule("sale"))
{
  $arFields = array(
    "PRODUCT_ID" => 51,
    "PRODUCT_PRICE_ID" => 0,
    "PRICE" => 138.54,
    "CURRENCY" => "USD",
    "WEIGHT" => 530,
    "QUANTITY" => 1,
    "LID" => LANG,
    "DELAY" => "N",
    "CAN_BUY" => "Y",
    "NAME" => "Lather suitcase",
    "CALLBACK_FUNC" => "MyBasketCallback",
    "MODULE" => "my_module",
    "NOTES" => "",
    "ORDER_CALLBACK_FUNC" => "MyBasketOrderCallback",
    "DETAIL_PAGE_URL" => "/".LANG."/detail.php?ID=51"
  );

  $arProps = array();

  $arProps[] = array(
    "NAME" => "Colour",
    "CODE" => "color",
    "VALUE" => "Black"
  );

  $arProps[] = array(
    "NAME" => "Size",
    "VALUE" => "1.5 x 2.5"
  );

  $arFields["PROPS"] = $arProps;

  CSaleBasket::Add($arFields);
}
?>

Basket actualization callback function

If the basket actualization callback function is specified, it is called every time the basket is being queried. This allows to properly and fully update parameters of products in the basket. For example, is the product price or availability becomes changed after adding it to the basket, the callback function can properly update parameters of the basket items. The CALLBACK_FUNC field contains only the name of the callback function. Some modules provide the preset callback functions. For example the Commercial Catalog module provides function CatalogBasketCallback($PRODUCT_ID, $QUANTITY = 0).

array
CALLBACK_FUNC(
 int PRODUCT_ID [, 
 int QUANTITY]
);

Return Values

The callback function must return an array of the same format as the function CSaleBasket::Add takes on input. If the callback function returns an empty array, the product is considered unavailable.

Parameters

PRODUCT_ID

The ID of the product currently in the basket.

QUANTITY

Number of the product items.

Example

<?
function MyBasketCallback($PRODUCT_ID, $QUANTITY = 0)
{
  $arResult = array();

  $iProductQuantity = GetProductQuantity($PRODUCT_ID);
  if ($iProductQuantity<=0)
    // not in stack, return empty array
    return $arResult;

  $arResult = array(
    "PRODUCT_PRICE_ID" => 0,
    "PRICE" => 125.2,
    "CURRENCY" => "USD",
    "WEIGHT" => 530,
    "NAME" => "Leather suitcase",
    "CAN_BUY" => "Y"
  );

  if (IntVal($QUANTITY)>0 && 
      ($iProductQuantity-$QUANTITY)<0)
  {
    // number of products in stock is less 
    // than the basket specifies, so 
    // decrease the quantity
    $arResult["QUANTITY"] = $iProductQuantity;
  }

  return $arResult;
}
?>

Ordering callback function

If the ordering callback function is specified, it is called when a product in the basket is being ordered. For example, the callback function can track quantity of the currently in-stock product items and decrease the number of product items in the basket accordingly. The ORDER_CALLBACK_FUNC field contains only the name of the callback function. Some modules provide the preset callback functions. For example the Commercial Catalog module provides function CatalogBasketOrderCallback($PRODUCT_ID, $QUANTITY).

void
ORDER_CALLBACK_FUNC(
 int PRODUCT_ID, 
 int QUANTITY
);

Returned values

No return values.

Parameters

PRODUCT_ID

The ID of the product currently in the basket.

QUANTITY

Number of the product items.

Example

<?
function MyBasketOrderCallback($PRODUCT_ID, $QUANTITY)
{
   UpdateProductQuantity($PRODUCT_ID, $QUANTITY);
}
?>