ExperSHOP Lite 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
  • 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.

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.
  • 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.
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)
  • 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.

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 - The expershop-generated 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).

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.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)
  • 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.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.

Other ExperSHOP servlets

To upload a file: com.expershop.lite.ESUploaderServlet

The com.expershop.lite.ESUploaderServlet servlet allows to upload text or binairy files. You need to specify the source file which has to be uploaded, the destination directory, and the redirection url which will be used when the upload process will be finished. The obligatory parameters are the following:

  • urles - redirection url.
  • overwrite - on or off. If on, the file will be overwritten, else off.
  • uploadfile - file name to upload.
  • uploaddirectory - destination directory, this directory is a relative path. It is computed from the path described in the application configuration file (app.UploadDir):

    [value of app.UploadDir]/[value of uploaddirectory]

Example:

<form enctype="multipart/form-data" method="POST" action="com.expershop.lite.ESUploaderServlet">
  <input type="hidden" size="20" name="urles" value="/servlet/com.expershop.lite.ExperSHOP?$Cookie$&Page=MyPage.tmpl"><p>
  <input type="hidden" size="20" name="overwrite" value="on">

  file to upload :        <input type="file" size="20" name="uploadfile" value=""><p>
  destination directory : <input type="text" size="20" name="uploaddirectory" value="/tmp"><p>
  <input type="submit" name="UPLOADSERVLET" value="UPLOAD">
</form>