ExperSHOP Actions

Home Contents

Please email any bug reports, comments or suggestions to ExperLog's Online Support

What are Actions ?

Actions are java classes that can be called by ExperShop to perform some tasks.

ExperSHOP comes with predefined actions: for example, the com.expershop.actions.ESAddToCart action adds an item to the shopping cart.

Actions may be invoked:

  • Directly from an ExperShop DynHtml template, using the $Action statement.
    Server-side actions can only be used this way.
  • By ExperSHOP when invoking an ExperSHOP servlet, before displaying anything:
    the Action must be passed to ExperSHOP servlets via the "Action" HTTP parameter: invoking an ExperSHOP servlet with Action=com.expershop.actions.ESAddToCart in its parameters list will add the specified item to the shopping cart before displaying anything.
    Server-side actions can't be used this way, for security reasons.

Actions may receive parameters (also passed as HTTP parameters to the servlet), and may also return parameters that will be visible to the servlet.
For example, the ESAddToCart action receives a "ProdId" parameter, that tells which product to add to the shopping cart.

Actions may succeed or fail; you can associate a template to an action failure, to pretty print the error: the "ActionFailed" HTTP parameter specifies which page to display if an action fails.

ExperSHOP predefined actions

The following actions are predefined:

General-purpose actions:

Administrative actions:

  • Administrative actions are accessible only to the shop administrator; see the Administrative actions pages for more info.

Other actions:

  • Secure Payment: most ExperShop secure payment interfaces are based on or include specific Actions; see the secure payment pages for more info.
Now we'll detail each action, with its input/output parameters.

com.expershop.actions.ESAddToCart

Add an item to the shopping cart.

Input parameters:

  • ProdId (MANDATORY) - The product reference, to be added to the shopping cart
  • Qty (OPTIONAL) - The quantity, defaults to 1.
  • Superior (OPTIONAL) - An ItemId, so the new item is a sub-item of the item specified by this parameter.
  • Options (OPTIONAL) - A string to describe product options.
  • OptionNames (OPTIONAL) - For products with multiple options: this parameter contains option names, which are themselves parameter names. The names are separated with commas; for example, "Color,Size".
  • UINFO_[name] (OPTIONAL) - To store user information in the cart. User information is a name/value pair, that lives as long as the cart is not emptied. To retrieve the information later, use $ShoppingCart:UInfo.[name], [name] being the name of the info.
  • AllowDups (OPTIONAL) - If present (eg. set to 1), allows duplicates to be inserted in the shopping cart.

Output parameters:

  • ItemId: unique identifier of the newly added item in the cart.

com.expershop.actions.ESUpdateCart

Update the cart content.

Input parameters:

  • TaxZone (OPTIONAL) - The zone name for value added tax calculation.
  • ShippingZone (OPTIONAL) - The zone name for shipping cost calculation.
  • DiscountCode (OPTIONAL) - The discount code to apply discounts.
  • AddItems (OPTIONAL) - If present (for example, equal to "Y"), the specified items will be added to the cart.
  • Superior (OPTIONAL) - To be combined with AddItems; An ItemId, so the new items are sub-items of the item specified by this parameter. If the superior is not present in the cart, it will be considered a ProdId and added.
  • UINFO_[name] (OPTIONAL) - To store user information in the cart. User information is a name/value pair, that lives as long as the cart is not emptied. To retrieve the information later, use $ShoppingCart:UInfo.[name], [name] being the name of the info.
  • AllowDups (OPTIONAL) - If present (eg. set to 1), allows duplicates to be inserted in the shopping cart.
And FOR EACH ITEM concerned:
  • QTY_[ItemId] - the quantity of a given item, [ItemId] is the item reference in the cart (example: QTY_$ItemId$ in a loop). A value of 0 removes the item and its sub-items.
    If AddItems is present, ItemId will be considered a ProdId and added.
  • Options_[ItemId] (OPTIONAL) - A string to describe product options.
  • OptionNames_[ItemId] (OPTIONAL) - For items with multiple options: this parameter contains option names, which are themselves parameter names. The names are separated with commas; for example, "Color,Size".
  • DEL_[ItemId] (OPTIONAL) - Remove the specified item: if this parameter is set to "y" or "Y", the corresponding item is removed, as well as its sub-items if any.

com.expershop.actions.ESConfigureCart

Configure the shopping cart - mainly to change the product database table.
This action is reserved for advanced shopping cart functionalities.
Server-side action.

Input parameters:

Any parameter that starts with CONFIG_ .
No parameter means reset to default values.
To change the product database table for the shopping cart:

  • CONFIG_Table: the new database table (default: EProduct)
  • CONFIG_ProdId: the new ProdId field name (product reference; default: ProdId)
  • CONFIG_Name: the new Name field name (product name; default: Name)
  • CONFIG_Price: the new Price field name (product price; default: Price)

Output parameters: none.

com.expershop.actions.ESEmptyCart

Empty the shopping cart.
This action can be used when interfacing ExperSHOP with a secure payment system that provides shop back-office functionalities: if so, the merchant may not want to use ExperSHOP's back-office, then just empty the cart when a customer order is confirmed.

com.expershop.actions.ESSaveCart

Save the shopping cart content.

Input parameters: none.

Output parameters:

  • CartId - The expershop-generated cart ID, necessary to restore the cart.

com.expershop.actions.ESRestoreCart

Restore a previously saved shopping cart: the shopping cart content becomes equal to the previously saved content.

Input parameters:

  • CartId - An application defined cart ID, necessary to restore the cart; if this ID has already been used, the corresponding records in the database will be overwritten.

Output parameters:

  • CartId - The expershop-generated (or application defined) cart ID, necessary to restore the cart.

com.expershop.actions.ESCustomerLogin

Log in an existing customer.

Input parameters:

  • Login (MANDATORY) - The customer ID
  • Password (MANDATORY if passwords are enabled) - The customer's password
Output parameters:
  • Upon success, the customer is logged in (the Customer ID will be passed to all ExperSHOP servlets in the cookie).
  • The Customer ID is available as $Cookie:CustId$ (for example, the success of this action can be tested using $IfPresent Cookie:CustId).

com.expershop.actions.ESNewCustomer

Create a new customer in database.

Input parameters:

  • Mandatory (OPTIONAL): The list of all mandatory fields, comma-separated.
    Example: Mandatory=FirstName,LastName,Address
    Default value: FirstName,LastName,Address,City,ZipCode,Country
  • Login (OPTIONAL): true or false, default true; tells if the newly created customer must be logged in right now, or not.
  • CustId (OPTIONAL): If present, lets the customer choose his own ID (for example, his name); If the ID already exists in the customer base, a number will be appended to it (starting at 1, then 2, etc...) so it becomes unique.
  • Other parameters: those specified in the "Mandatory" parameter value are mandatory, other fields are optional.
Output parameters:
  • MissingField: Returned only if a mandatory parameter lacks, equal to the name of the missing parameter.
  • If the Login input parameter was true, the customer is now logged in (the Customer ID will be passed to all ExperSHOP servlets in the cookie).

com.expershop.actions.ESUpdateCustomer

Update a customer in database.

Input parameters:

  • CustId (MANDATORY, except if the customer is already logged in).
  • Mandatory (OPTIONAL): The list of all mandatory fields, comma-separated.
    Example: Mandatory=FirstName,LastName,Address
    Default value: No mandatory field.
  • Login (OPTIONAL): true or false, default true; tells if the modified customer must be logged in right now (if not yet), or not.
  • Other parameters: those specified in the "Mandatory" parameter value are mandatory, other fields are optional.
Output parameters:
  • MissingField: Returned only if a mandatory parameter lacks, equal to the name of the missing parameter.
  • If the Login input parameter was true, the customer is now logged in (the Customer ID will be passed to all ExperSHOP servlets in the cookie)

com.expershop.actions.ESOrderAct

Place Order: a new order is created, the shopping cart is emptied.
This action is dedicated for check or fax payment: the status of the new order will be set to "WAITING" (stands for "waiting for payment").

Note ESOrderAct creates an entry in the ECustOrder database table: you can affect column values by specifying HTTP parameters in your HTML forms with the same names as the table column values.
For example, to gather the Credit Card number and expiration date, use HTML INPUT tags called CcNum and CcExpDate (corresponds to CcNum & CcExpDate in the ECustOrder table).
You can also add columns of your own to the ECustOrder table, then update them the same way.

Input parameters:

  • None if a customer is logged in (see the "Login" parameter in the ESNewCustomer and ESUpdateCustomer actions, and the ESCustomerLogin action).
    If not, two parameters are mandatory: ShipName and ShipAddress, to make possible the delivery of goods.
Output parameters:
  • OrdId: The ExperSHOP-generated Order ID

com.expershop.actions.ESNewDiscount

Create a new discount code in database.

Input parameters:

  • Dcode: Discount code
  • Rate: Discount rate
  • Dtype (OPTIONAL): Discount type (default FLAT; other possible values: PRICE, FREESHIPPING, GIFT)
  • Maxuse (OPTIONAL): Maximum number of uses for this code (default 1)
  • Datemin (OPTIONAL): Start date (default none)
  • Datemax (OPTIONAL): End date (default 30 days validity)
  • Minamount (OPTIONAL): Minimal order amount to make this discount applicable (default Rate for FLAT type, or 0)
  • Minqty (OPTIONAL): Minimal number of items to make this discount applicable (default 0)
  • Descrip (OPTIONAL): Text description when discount is applicable (default "Discount")
  • Notapplicable (OPTIONAL): Text description when discount is not applicable (default "Not applicable")
  • Dcond (OPTIONAL): SQL condition to make this discount applicable - combined with a SQL "and" on the EProduct table (default no condition; not applicable to GIFT and FREESHIPPING types)
Output parameters UPON SUCCESS:
  • Dcode2: The generated discount code (should be equal to "Dcode" input parameter).
Output parameters UPON ERROR:
  • MissingField: Returned only if a mandatory parameter lacks, equal to the name of the missing parameter.

com.expershop.actions.ESCheckParams

Enforce mandatory parameters: for example, when an entry form is submitted.

Input parameters:

  • Mandatory - Comma-separated list of mandatory parameters.
  • ErrorTemplate - (OPTIONAL) An error message template, to build an error message whenever a mandatory parameter is missing; The template may contain dynamic information, like for example the name of the missing parameter (example: "The following information is missing: $MissingField$.")
  • All - (OPTIONAL) If equal to "true", the action will return a comma-separated list of all missing parameters, otherwise only the first missing parameter will be returned.
Output parameters UPON ERROR:
  • MissingField - Name of the first missing parameter, or comma-separated list of all missing parameters if the "All" parameter is set to "true".
  • Message - Error message, according to the value of the ErrorTemplate input parameter (default value: "Parameter [name-of-missing-param] should have a value.")
Output parameters UPON SUCCESS: None.

com.expershop.actions.ESSendMail

Send an e-mail.

Configuration parameters:

  • email.MailHost - The mail server IP address (OPTIONAL, default local host).
Input parameters:
  • From - an e-mail address (OPTIONAL if email.From is defined in the shop's configuration file)
  • To - an e-mail address (OPTIONAL if email.ManagerEmail is defined in the shop's configuration file), to use multiple e-mail addresses, separate them with a comma.
  • Subject - the subject (OPTIONAL, default "(No Subject)")
  • Content_type - the Content-type & charset (OPTIONAL)
    Sample value for french language: "text/plain\; charset=fr-ascii\n";
  • Template - (MANDATORY) An e-mail template file path, relative to the shop's root dir (file syntax: DynHtml).
Output parameters: None.

com.expershop.actions.ESSendMailMP

Send an e-mail with attachments.

Input parameters:

  • From - an e-mail address (OPTIONAL if email.From is defined in the shop's configuration file)
  • To - an e-mail address (OPTIONAL if email.ManagerEmail is defined in the shop's configuration file). To use multiple e-mail addresses, separate them with commas.
  • Cc - an e-mail address (OPTIONAL). To use multiple e-mail addresses, separate them with commas.
  • Bcc - an e-mail address (OPTIONAL). To use multiple e-mail addresses, separate them with commas.
  • ReturnReceiptTo - Email address for mail server return receipt (OPTIONAL)
  • ConfirmReadingTo - Email address for user return receipt (OPTIONAL)
  • Subject - the subject (OPTIONAL, default "(No Subject)")
  • Content_type - the Content-type & charset (OPTIONAL)
    Sample value for french language: "text/plain\; charset=fr-ascii\n";
  • Template - (MANDATORY) An e-mail template file path, relative to the shop's root dir (file syntax: DynHtml).
  • Attachment - (OPTIONAL) a list of attachments (files), relative to the app.UploadDir configuration property (can be absolute or relative to the webapp).
  • remove - All attached files will be removed from the server when the mail will be sent. This option is useful when the ESSendMailMP action is used with the ESUploaderServlet servlet. (OPTIONAL)
    Values: 1: files will be removed, else 0 (default value)
Output parameters: None.
Be careful: mail.jar and activation.jar packages are needed for this action (You can find them in the Tomcat common libs).

Example to send in attachment a list of files which come from the ESUploaderSerlvet. The files names are stored in parameters 'uploadfile[n]' (n>=1). remove=1, files are removed from the server. 

$Assign Template ESTemplates/Mail/custom.tmpl
$Assign To his_name@his_company.com
$Assign From my_name@my_company.com
$Assign Subject a new version
$Assign remove 1
$Assign Attachment ""
$DefVar nf 1->$nbfiles$
$LoopOnEnum nf bf
 $Append Attachment " "
 $Defvar pname uploadfile$bf:value$
 $Append Attachment $(Eval)pname$
$EndLoop
$Action com.expershop.actions.ESSendMailMP

com.expershop.actions.ESWriteFile

Write a file to the server's disk, by expanding a DynHtml template.
Server-side Action, for security reasons: can be invoked using $Action only.
Example (Unix):
$Assign Template ESTemplates/xml/toxml.tmpl
$Assign File /usr/tmp/resultat.xml
$Action com.expershop.actions.ESWriteFile

Input parameters:

  • Template (MANDATORY) - The DynHtml template's name: Relative to the application's root directory (RootDir).
  • File (MANDATORY) - The name of the file to be written; relative to the application's root directory (RootDir), or absolute path.
    Note that the file will be written by the application: in terms of security and user rights, the user running the web server will be used.
Output parameters: None.