Elastic Path Commerce Development

Extending Helix Resources

Extending Helix Resources

You can extend a Helix resource by:

  • Adding related resources to existing resources. This method requires adding links to existing resources.
  • Overriding the functionality of an existing resource to include additional fields in an entity, remove a resource and its link, or change the functionality of a resource as required.

For more information about extending Helix resources, see the Elastic Path Tutorials page.

Adding New Resources

This section explains adding a new resource with an example extending carts resource. The default alias defined for a customer cart is defaultcart, however you can add a new custom alias, such as awesomecart, for the custom cart.

Note: In Cortex, you must define all XML files that contain API definitions for one resource family one API bundle.
  1. To implement awesomecart, create a new resource bundle and a new family name.

For the family name ext-carts, with name of the API bundle, ext-carts-api, and the name of the prototype bundle, ext-carts, the new definition is as in the following example:

<family>
     <name>ext-carts</name>

     <resource>
          <name>awesome-cart</name>
          <description><![CDATA[Alias to the awesome cart for the current shopper.]]></description>
          <uri>{base.family}/{base.scope}/awesome</uri>
          <alias>carts.cart</alias>
     </resource>
</family>

The newly defines wiring extends the AbstractHelixModule as in the following example:

@Named
public class ExtCartWiring extends AbstractHelixModule {

     @Override
     protected String resourceName() {
          return AwesomeCartResource.FAMILY; //Note the family name is “ext-carts”
     }

}

You may define links to and from an existing carts resource or any other resources to the new resource. After performing this step, the system creates the following:

  • Bundles
    • carts-api
    • ext-carts-api
  • Prototype bundles
    • carts
    • ext-carts

Overriding Existing Resources

After adding the new alias, awesomecart, delete the default alias, defaultcart, by implementing a new resource bundle ext-carts. This section provides step-by-step instructions with an example.

  1. To remove the defaultcart alias, create a new prototype bundle, such as, override-carts.
  2. Override appropriate prototypes by using @PrototypeExtension.
    Following is an example to implement RootToDefaultCartRelationship.LinkTo:
    @PrototypeExtension
    public class RemoveDefaultCartImpl implements RootToDefaultCartRelationship.LinkTo {
    
         @Override
         public Observable<DefaultCartIdentifier> onLinkTo() {
              return Observable.empty();
         }
    
    }
  3. Implement DefaultCartResource.Read with an error to display when accessing the resource directly.
    @PrototypeExtension
    public class DisableReadDefaultCartPrototype implements DefaultCartResource.Read {
         @Override
         public Single<CartIdentifier> onRead() {
              return Single.error(“defaultcart has been removed, use awesomecart instead”);
         }
    }
  4. Add the resource wiring module as in the following example:
    @Named
    public class OverrideCartWiring extends CartWiring {
         //the inherited resourceName() will return the family name "carts"
    }  

    You can configure the family name in the wiring module.

After performing this step, the system consists of the following:

  • Bundles
    • carts-api
    • ext-carts-api
  • Prototype bundles
    • carts
    • ext-carts
    • override-carts

For extending an entity, see the Extend Helix Resource Tutorial the provides instructions to extend the profiles resource and add a property to the profile entity.