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.
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.
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.
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.
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.
Save the shopping cart content.
Input parameters: none.
Output parameters:
- CartId - The expershop-generated cart ID, necessary to restore
the cart.
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.
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).
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).
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)
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
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.
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.
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:
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>
|