Implementing External Data Provider

October 8, 2024

This section describes the main components of the StoreDataSource class.

Path navigation

The StoreDataSource class in the org.jahia.modules.commerce.io.edp.datasource package is responsible for providing external data. As with all external providers in Jahia, the getItemByPath method resolves external data for an item, given its path.

This section provides more detail about the method. For the / ciont:categoryRoot node is returned after which there two major top level paths: ones that start with /p (paths for products) and ones that start without /p (paths for categories).

There are several cases to consider for the product path.

If the path:

  • Ends with a product SKU then external data for that product is returned.
  • Ends with /variants then the ciont:variantsList node is returned.
  • Contains /variants/ then the ciont:variantFeatures node is returned or ciont:variantOption depending on whether the path contains features.
  • Contains /medias then the ciont:medias node is returned.
  • Ends with /vanityUrlMapping then the jnt:vanityUrls node is returned.
  • Contains /vanityUrlMapping then the jnt:vanityUrl node is returned.

In all other cases of path with /p a jnt:contentFolder is returned.

The category part is a lot simpler.

If the path:

  • Ends with  /vanityUrlMapping then jnt:vanityUrls node is returned.
  • Path contains /vanityUrlMapping then jnt:vanityUrl node is returned.

Otherwise the category ciont:category node is returned.

In all other cases PathNotFoundException is returned.

Children

The getChildren method is also a standard method in External Data Provider, which returns a list of child paths for a given path.

As with the getItemByPath method, there are two major cases for paths: those that contain /p and those that do not.

The category path case is very simple.

  • If the path is a category path and it ends with /vanityUrlMapping, a list of vanity URLs spanning every available language is returned.
  • Otherwise, a list of child paths for that category is returned.

The product path case is a bit more complex as we need to take into account medias and variants.

  • If it is a pure product path (ending with an SKU), then child paths for media and variants are returned.
  • If the path ends with /medias then a list for every available media child is returned.
  • If the path ends with /vanityUrlMapping similarly to category path a list of vanity URLs spanning every available language is returned.
  • If it ends with /variants a list of available child variant paths is returned.

In the case when none of the conditions match an empty list is returned.

Search

The search method in the class applies when the product is searched for in Edit mode in Jahia or when a user is trying to access page with a vanity URL. The method returns a list of available paths which are then fed into getItemByPath method.  

The first check determines whether the search is for a product. If the search is for a product, then the mounted path for that product is returned. The mounted path is the path you see in JCR which has the following structure: /p/td/re/vf/<SKU>.

Another check catches two types of vanity URLs:

  • one case for product 
  • one case for category 

In each case a mounted path for that product or category is returned.