Parallels H-Sphere Documentation Developer Guide

 

Adding Custom Promotion Validators and Calculators

 
 

Related Docs:   Promotions (Admin Guide)

Last modified: 28 Dec 2007

 

WARNING: This documentation covers Parallels H-Sphere versions up to 3.1. For the latest up-to-date Parallels H-Sphere documentation, please proceed to the official Parallels site.

H-Sphere allows to define custom promotions - flexible discount systems - and assign them for individual plans.

Usually, a customer enters a certain promotion code on signup, the system verifies the entered code if it proves to be valid and corresponds to the chosen plan, that user signs up with that discount. This is called a codeable promotion. There are also codeless promotions that don't require a code. Discount depends on a particular promotion and the way the discount is calculated.

This document explains how to add and configure custom promotion validators and calculators.

Creating a Custom Promotion Validator

To add a custom promotion validator, use the the psoft.hsphere.promotion.PromoValidator Java class interface. The class can also extend the AbstractPromoDataStorage class to store the validator's data in the H-Sphere database.

Creating a Custom Promotion Calculator

To add a custom promotion validator, use the psoft.hsphere.promotion.calc.PromoCalculator Java class interface. The class can also extend the AbstractPromoDataStorage class to store the calculator's data in the H-Sphere database.

Example:

            package psoft.hsphere.promotion.calc;

            import psoft.hsphere.promotion.AbstractPromoDataStorage;
            import psoft.hsphere.Session;
            import psoft.hsphere.Account;
            import psoft.util.USFormat;

            import java.util.Hashtable;

            public class PercentDiscountCalc
                    extends AbstractPromoDataStorage implements PromoCalculator {
            private double discountPercent;

                public PercentDiscountCalc(long promoId) throws Exception {
                    super(promoId);
                    discountPercent =
                        USFormat.parseDouble((String) data.get("discount_percent"));
                }

                public PercentDiscountCalc(long promoId, Hashtable data) throws Exception {
                    super(promoId, data);
                    discountPercent =
                        USFormat.parseDouble((String) data.get("discount_percent"));
                }

                public int getDataType() {
                    return 2;
                }

                public double getPromoDiscount(Account a, double sum) {
                    return sum*discountPercent/100;
                }

                public void updateData(long promoId, Hashtable data) throws Exception {
                    super.updateData(promoId, data);
                    Session.getLog().debug("Updating discount percent");
                    discountPercent =
                        USFormat.parseDouble((String) data.get("discount_percent"));
                }
                }
        

Configuration of Custom Promotion Validators and Calculators

All promotion validators and calculators should be added to and configured in the promotions.xml file. Its default location is ~cpanel/shiva/psoft/hsphere/promotion/xml/. The file location can be altered with the PROMO_CONFIG and CUSTOM_PROMO_CONFIG properties in hsphere.properties.

PROMO_CONFIG=/hsphere/local/home/cpanel/shiva/psoft/hsphere/promotion/xml/promotions.xml
CUSTOM_PROMO_CONFIG=/hsphere/local/home/cpanel/shiva/custom/xml/promotions.xml

promotions.xml can be customized according to XML customization rules outlined in Customization Guide.

DTD structure | Example

Elements and attributes:

  • <promotions> - contains all defined promotion validators.

  • <promo> - configuration of a particular promotion validator.

    Attributes:

    • id - a unique promotion identifier: 1,2,...
    • description - a short description of the validator. It shows up in the dropdown list of promotions in Control Panel.
    • class - a name of a Java class for this validator.
    • itype - a type of the validator's interface. If it is set to "AUTO", interface for adding the validator parameter will be built automatically, depending on parameters defined for the validator or calculator; otherwise, values of the add_template and edit_template attributes will be used as template names for adding/editing set of data which is required for the given promo validator.
    • add_template - a name of a template for adding the validator data; the value of this attribute will take effect only in case if itype is not set to "AUTO".
    • edit_template - a name of a template for editing the validator data; the value of this attribute will take effect only in case if itype is not set to "AUTO".
  • <calculators> - contains all defined promotion calculators.

  • <calc> - configuration of a particular promotion calculator. Attributes have the same meaning as for promotion validators.

  • <params> - contains all parameters used by promotion validators or calculators.

  • <param> - configuration of a particular parameter.

    Attributes:

    • label - a name of a label in ~cpanel/psoft/hsphere/lang/hsphere_lang.properties with the message that appears on the page where users enters a promo code.
    • name - the parameter's name. The AbstractPromoDataStorage object stores validators' or calculators' data from HttpRequest using this name with the prefix 'pv_' for a validator and 'pc_' for a calculator. I.e., if name="percent", AbstractPromoDataStorage expects the 'pv_percent' variable for the validator and the 'pc_percent' variable for the calculator to be present in HttpRequest.

Related Docs:   Promotions (Admin Guide)



© Copyright 2017. Parallels Holdings. All rights reserved.