Developing External Plugins

You can build customizations on the Extension Point Framework using External Plugins.

For more information about the differences between external plugins and embedded extensions, see the options for extending the platform documentation.

Creating a New Plugin

1. Open a terminal window in the folder where you keep your Git projects.

   note

   The mvn archetype command in an upcoming step will create a new subfolder automatically.

2. Initialize the plugin using the Extension Point Plugin archetype by executing the following command:

   mvn archetype:generate -DarchetypeGroupId=com.elasticpath.xpf -DarchetypeArtifactId=ep-xpf-archetype -DarchetypeVersion=1.0.2.e1acf7d9a6 -DarchetypeCatalog=local
   

3. Specify the following values in Maven:

   • groupId: The plugin group ID, in lower case letters and dots with no spaces. For example, com.elasticpath.plugin.

   • artifactId: The plugin artifact ID, in lower case letters and dashes with no spaces. For example, vip-only-product-sku-validator.

   • version: The plugin version. For example, 1.0-SNAPSHOT.

   • package: Unused value. Ensure that you accept the default value.

   • extensionClassName: A class name for your extension, with only letters and numbers but no spaces. For example, VipOnlyProductSkuValidator.

   • pluginId: The plugin identifier, in lower case letters with no spaces. Usually this is the same as the extensionClassName but in all lowercase. For example, viponlyproductskuvalidator.

   • pluginName: A human-readable representation the plugin name. For example, VIP-Only Product Sku Validator.

   • vendorId: Your company identifier, in lower case letters with no spaces. For example, elasticpath.

   • vendorName: A human-readable representation of your company name. For example, Elastic Path.

     note

     Maven creates a basic plugin module in a subfolder named after the artifactId. You can rename this folder if you wish.

4. Go to the plugin folder and run the git init command to initialize the Git repository.

5. Open the plugin module in your IDE.

6. Open the extension class.

7. Update the extension class to implement the appropriate Extension Point interface.

8. Update the @XPFAssignment annotation to specify the appropriate Extension Point key.

9. Implement the methods required by the Extension Point interface.

10. Build your plugin module with mvn clean install.

11. Open the ep-commerce repo in your IDE.

12. Open the ext-plugin-config module POM (Project Object Model) file.

13. Add a dependency for the plugin module that you just created.

14. (Optional) Follow the deploy instructions for details on how to specify plugin and extension configuration files, to pass the setting values.

Once the plugin and optional configuration files have been added to the ext-plugin-config module, it will be automatically loaded by all Elastic Path Commerce services that are started locally using mvn tomcat8:run-war or deployed using CloudOps. For more information, see Deploying External Plugins.

Updating and Testing your Plugin

To update and test your plugin, we assume that you already have one or more Elastic Path Commerce services running locally, such as Cortex, with your external plugin deployed. You have made some changes to your plugin and want to deploy them without restarting the Elastic Path Commerce services.

1. Open a terminal window in the folder where your plugin source code is located.

2. Build your plugin using mvn clean install.

3. Unload the old plugin by using the unload.sh <service> <version> command, where <service> is the name of the EPC service you are testing on, such as cortex, and <version>is the current version number of your plugin.

4. Re-load the new plugin using the load.sh <service> <version> command, where <service> with the name of the EPC service you are testing on, such as cortex, and <version> is the current version number of your plugin.

5. Test your changes normally.