Magento Content API — Technical Overview
Overview
GoogleShopping module provides the API that enables to communicate with Google Merchant Center to upload and edit product data; it replaces depreciated in June 2011 Google Base API. Google Shopping API consists of two parts: Content and Search; Content API allows insert, update, delete and retrieve product's info; Search API allows search by uploaded items which is not part of this implementation.
Mage_GoogleShopping v0.3 implements only Content API functionality. Zend Framework Gdata that is used by Base API module hadn't been updated when development started, so there was a new Varien_Gdata_Gshopping library added; structure Mage_GoogleShopping module is similar to structure Mage_GoogleBase module, re-factored in version 0.3.
This document describes version 0.3 of module. Google's API description can be found in http://code.google.com/intl/ru/apis/shopping/content/getting-started/usingapi-products.html
Varien_Gdata_Gshopping library
The library extends functionality of Zend_Gdata library; it's architecture and functionality is like Zend_Gdata_Gbase module. Main functionality of the module is concentrated in two classes: Varien_Gdata_Gshopping_Content and Varien_Gdata_Gshopping_Entry.
Varien_Gdata_Gshopping_Content
This class is responsible for inserting, updating, deletion and retrieving entries; method performHttpRequest() wraps with to parse error response from Google.
Zend_Gdata_App_HttpException Varien_Gdata_Gshopping_HttpException
Varien_Gdata_Gshopping_Entry
This class extends functionality of Zend_Gdata_Entry with functions for processing (parsing from DOM and generation DOM) content attributes and some special attributes as taxes and destinations.
(<sp:attribute>)
The module uses several children of Zend_Gdata_App_Extension_Element for parsing and building sub-elements of entry it's:
Varien_Gdata_Gshopping_Extension_Attribute is used for processing <sc:attribtue> of an entry;
Varien_Gdata_Gshopping_Extension_Control is used to work with destinations;
Varien_Gdata_Gshopping_Extension_Shipping was designed to work with shipping information, but isn't used by Mage_GoogleShopping module because we're unable to send any appropriate shipping information when we don't know shipping destination;
Varien_Gdata_Gshopping_Extension_Tax is used for processing tax information for united states.
Varien_Gdata_Gshopping_HttpException
This class extends Zend_Gdata_App_HttpException and tries to parse error info from response's body. It overrides constructor to add capability to build class from Zend_Gdata_App_HttpException instance and adds some getters for error info extracted from response body.
Mage_GoogleShopping module
This module adds functionality for manipulation of entries to admin panel. During installation it creates three tables:
and adds menu (with
googleshopping_attributes, googleshopping_items googleshopping_types; Catalog Google Content related pages) and page with configuration options to Sales Google API section.
As written above the module creates such tables:
googleshopping_attributes contains map from products' attributes to Google's attributes;
googleshopping_items contains information about attributes uploaded to Google;
googleshopping_types contains map from types (set of mapped attributes) to attributes' sets.
Blocks
The blocks has structure similar to Mage_GoogleBase blocks; all blocks are children of Mage_Adminhtml_Block classes and used for creating interface in admin panel. Also there are four templates in app/design/adminhtml/default/default/template/googleshopping folder.
Controllers
The module has three controllers:
Mage_GoogleShopping_Adminhtml_Googleshopping_ItemsController serves grid of items;
Mage_GoogleShopping_Adminhtml_Googleshopping_SelectionController handles product selection's grid on items page;
Mage_GoogleShopping_Adminhtml_Googleshopping_TypesController serves types page.
Models
Item
Mage_GoogleShopping_Model_Item class is a Google Content's item and it responsible for insert, update and delete item. All these items are stored in the Magento's database (googleshopping_items table) and contains only main information about item. So, this model has resource model (Mage_GoogleShopping_Model_Mysq4_Item), which is responsible for saving and loading item's data from the database. Also this model has service model (Mage_GoogleShopping_Model_Service_Item), which is responsible for storing and receiving items from Google Content service.
Mage_GoogleShopping_Model_Item
This class works with Mage_GoogleShopping_Model_Service_Item class for working with Google's items Main methods:
insertItem - add (send) product to Google Content
updateItem - updatete current item's data in Google Content
deleteItem - delete item from Google Content
load - load item from Magento's database
save - save item's model to database
delete - delete items from database
getType - get type of item (about types - see below)
getProduct - get/load product model (catalog/product) which is associated with item
Mage_GoogleShopping_Model_Service_Item
This class works with Varien_Gdata library for working with Google's items Main methods:
insert - add item to Google Content
update - update item's data in Google Content
Insert, update and delete product to Google Content
// load product before
$product = Mage::getModel('catalog/product') ->setStoreId($storeId)
->load($productId);
// create item and save it in the DB Mage::getModel('googleshopping/item') ->insertItem($product)
->save();
// update item (if something in the product was changed) Mage::getModel('googleshopping/item') ->loadByProduct($product) ->updateItem() ->save(); //delete item Mage::getModel('googleshopping/item') ->loadByProduct($product) ->deleteItem() ->delete();
Attribute's type.
Each item has a type, which describes how this item should save to Google Content, i.e. how product's attributes should be provided. In user interface, types are named as "mapping". The types data is storing in table googleshopping_types, and type's attributes in the table
. Each type is characterized by the target country and attribute set, so we can set different representations for
googleshopping_attributes
different products from different stores (each store can have own target country) in Google Content base. So, class
responsibles for saving and loading types from Magento's database (using resource model
Mage_GoogleShopping_Model_Type
), and also for set attributes to entry ( ) from product's
Mage_GoogleShopping_Model_Mysql4_Type Varien_Gdata_Gshopping_Entry
model (using mapping data). In order to update product's attribute to entry, we should use method convertProductToEntry.
Mage_GoogleShopping_Model_Type
convertProductToEntry - main method of this class, find all attributes for current product and add/update/delete them in the entry object.
loadByAttributeSetId - load type for some attribute set and target country
Attributes
Each attribute, which will be sent to Google, is represented by class Mage_GoogleShopping_Model_Attribute. The attributes can be exported in Google Content by different ways, and the models Mage_GoogleShopping_Model_Attribute_<name> (where <name> is Google attribute's name) responsible for how they will be exported to Google. So, when we call method
, it calls method for all attribute models. If some
Mage_GoogleShopping_Model_Type->convertProductToEntry convertAttribute
attribute hasn't model (class Mage_GoogleShopping_Model_Attribute_<name> hasn't been found), it will use model
. The list of all attributes, which should be sent to Google, consists of: base attributes
Mage_GoogleShopping_Model_Attribute_Default
(requires attributes which must be sent to Google) and attributes from mapping (attributes which user was added to type in the Catalog -> Google ). The list of base attributes is listed in (the tag ). It is such attributes as , Content -> Manage Attributes config.xml base_attributes id
, , , etc.
Mage_GoogleShopping_Model_Attribute_Default
Default attribute model. All other attribute models should extend this class.
convertAttribute - method which add, update or delete attribute to entry object (Varien_Gdata_Gshopping_Entry).
Grouped attributes
Some attributes may have strong dependence between each other. For instance, attribute tax depends on attribute price, because tax depends on how price is setting/calculating (include or exclude tax), it affects how tax will be send to Google Content. Also Google Content has synonyms for some attribute names (one attribute can have two names). For instance, product's name can be sent as name attribute or as title
attribute, but it is impossible send name and title attributes together, in one entry. In order to solve such problems, the attribute model has a possibility to take access to another attribute. So, price attribute has access to tax attribute and it can use method
for get tax attribute's model. Also attribute responsible for how to add attribute to entry object
$this->getGroupAttributeTax() price tax
(using method convertAttribute}), price model can add or don't add tax attribute. The group attribute dependencies are set in config.xml
(tag attribute_groups).
Mage_GoogleShopping_Model_MassOperations
This model responsible for mass actions with Google Content items. It is used by controller (
) and observer ( ).
Mage_GoogleShopping_Adminhtml_Googleshopping_ItemsController Mage_GoogleShopping_Model_Observer
It contains next operations:
addProducts - add several products to Google Content by their IDs.
synchronizeItems - update items, synchronize their attributes data.
Insert, update and delete several products to Google Content
// add to Google Content products with IDs = 5, 6 and 7 for store with ID = 2 Mage::getModel('googleshopping/massOperations')
->addProducts(array(5, 6, 7), 2);
// update products in the Google Content
$items = Mage::getResourceModel('googleshoping/items_collection') ->addFieldToFilter('product_id', array(5, 6, 7))
->addStoreFilter(2);
Mage::getModel('googleshopping/massOperations') ->synchronizeItems($items);
// delete products in the Google Content
$items = Mage::getResourceModel('googleshoping/items_collection') ->addFieldToFilter('product_id', array(5, 6, 7))
->addStoreFilter(2);
Mage::getModel('googleshopping/massOperations') ->deleteItems($items);
Mage_GoogleShopping_Model_Observer
The observer updates Google after updating and deletion product.
Source models
The module uses several source models:
Mage_GoogleShopping_Model_Source_Accounttype; Mage_GoogleShopping_Model_Source_Authtype; Mage_GoogleShopping_Model_Source_Country;
Mage_GoogleShopping_Model_Source_Destinationstates; Mage_GoogleShopping_Model_Source_Statuses.
Resource models
Due to model uses database there are several resource models:
Mage_GoogleShopping_Model_Mysql4_Type;
Mage_GoogleShopping_Model_Mysql4_Type_Collection; Mage_GoogleShopping_Model_Mysql4_Item;
Mage_GoogleShopping_Model_Mysql4_Item_Collection; Mage_GoogleShopping_Model_Mysql4_Attribute;
Mage_GoogleShopping_Model_Mysql4_Attribute_Collection.
Helpers
The module uses two helpers: Mage_GoogleShopping_Helper_Data and Mage_GoogleShopping_Helper_Price. Data helper it's generic helper and it's used in templates. Price helper it's workaround for problem of getting price as it displayed in catalog; abstract price model doesn't have interface to get minimal price of grouped, bundle, gift card products, but on frontend customer can see this price.
