Perlshop 4 - Plugin Documentation

Contents

• Overview
  • Example Use

• Plugin Types
  • External Plugins
  • Internal Plugins
  • File Plugins
  • Text Plugins

• The Plugins Registration Table

• External Plugins
  • Defining External Plugins
  • Calling External Plugins from Catalog Web Pages
    • External Plugin Parameters
    • Calling an External Plugin Using a Hyperlink
    • Calling an External Plugin Using a Form
  • Creating External Plugins to be Called from Catalog Pages
  • Creating Event Driven External Plugins
  • The Calendar Sample Plugin

• Internal Plugins
  • Defining Internal Plugins
  • Creating your own Internal Plugins

• File Plugins
  • Defining File Plugins

• Text Plugins
  • Defining Text Plugins

• The Perlshop 4 Event Driven Plugin Model
  • General Content Insertion Events
  • Events Associated with Catalog Page Loading
  • Events Associated with the Perlshop Add Action
  • Events Associated with the Perlshop Check Out Action
  • Events Associated with the Perlshop Enter Action
  • Events Associated with the Perlshop Place Order Action
  • Events Associated with the Perlshop Restart Action
  • Events Associated with the Perlshop Shipping Rates Action
  • Events Associated with the Perlshop Submit Action
  • Events Associated with the Perlshop View Cart Action
  • Events Associated with Invoice Email
  • General Data Processing Events

• Using the Provided Plugin Files
  • Using the "After Shipping" Order Page Plugin
  • Using the Shipping Weight Display Plugin

• Defining Your Own Plugin Events
  • A Simple Example: Inserting Text
  • A Complex Example: Displaying a Shopping Cart Total

Overview

An Example of a Custom Plugin

This is where a custom Perlshop Plugin comes into play.

The home page of the store provides a search interface that allows customers to look for items that interest them. This interface calls a Plugin that searches through the database file, finds all items that meet the search criteria, and generates Perlshop catalog page html as a response. This html is read in by Perlshop 4, which then treats it as if it had come from a static html file on disk. The customer simply sees a catalog page that looks like any other.

By mixing static html pages with pages generated by Perlshop Plugins, an ecommerce web site can be given dynamic content without sacrificing any existing capabilities.

Plugin Types

External Plugins

Internal Plugins

File Plugins

Text Plugins

The Plugins Registration Table

Each entry in this table is defines one plugin. Each entry has a unique name, and one or more information attributes.

The following example defined an external plugin whose name is calendar, and whose executable file name is ps_plugin_gencal.pl.

%plugins =
(
	# Calendar example plugin
	'calendar'  => 
	{
		'program'	=> 'ps_plugin_gencal.pl'
	}
);

The information fields required for each plugin type are explained in detail later on in this document.

There is no limit on the number of plugins that may be registered with Perlshop 4.

External Plugins

Defining an External Plugin

Attribute	Required	Default Value	Description
program	Yes	None	This is the name of the executable file for the plugin. This file is expected to be located in the same directory as the perlshop.cgi file.
background	No	'no'	This optional field is available on Unix systems only, and is used to indicate that the plugin is intended for use in background mode. Legal values for this attribute are 'yes' and 'no'. This field is applied to event driven plugin calls only.
display	No	'yes'	This optional field is used to determine whether or not the output of the plugin is to be added to the html of the web page when the plugin is executed. Legal values for this attribute are 'yes' and 'no'. This field is applied to event driven plugin calls only.
event	No	One or more event names	This optional field specifies the event(s) that will activate this plugin.
condition	No	None	This optional field specifies the logical conditions that are required to activate this plugin. The condition must be expressed as a Perl language statement. This statement will be executed via Perl eval() function call at the time that the plugin is called. If the statement evaluates to true, the plugin is allowed to execute. If the statement evaluates to false, no further actions are taken. This field is applied to event driven plugin calls only.

An Example:
This example defines an external plugin named calendar. This external program file for this plugin is ps_plugin_gencal.pl. This program will not run in background mode. The output from this program will be included in the web page display. No events are associated with this plugin.

%plugins =
(
	# Calendar example plugin
	'calendar'  => 
	{
            'program'    => 'ps_plugin_gencal.pl',
            'background' => 'no',
            'display'    => 'yes'
	}
);

Calling External Plugins from Catalog Web Pages

When used this way, an external plugin can be thought of as a Perlshop built-in command, like the View Cart command or the Check Out command. The customer clicks on a hyperlink or a form button, and Perlshop is called to generate and present a new page. Instead of retrieving the content of the new page from a disk file, Perlshop calls upon the plugin program to dynamically generate the HTML for the new web page.

The plugin program then generates an HTML text stream, which Perlshop receives and processes in exactly the same way as it would the HTML from a static web page file:

• All Perlshop substitution variables, such as !MYURL! and !MYWWW!, are replaced with real values.
• All Perlshop ITEM tags are processed.
• If needed, the ITEM_CODE tag is generated.

External Plugin Parameters

• Action
  The value of the action parameter must be set to 'plugin'.

• Plugin
  This parameter is used to name the plugin being called.
  The plugin named must be present in the plugins table of the ps.cfg file.

• Plugin_ParamX
  Plugins may have up to 10 parameters passed to them.
  These parameters must have names such as plugin_param1, plugin_param2, etc.
  The values of these parameters may be any numerical or text value.

• ORDERID
  Just as with any other Perlshop action, the ORDERID parameter must be passed as a part of the plugin call.

Calling an External Plugin Using a Hyperlink

<a href="!MYURL!?action=plugin&plugin=searchplug&plugin_param1=keyword&order_id=!ORDERID!>
Click Me</a>

Calling an External Plugin Using a Form

<form name="searchForm" method="post" action="!MYURL!">

<input type=hidden name="order_id" value="!ORDERID!>
<input type=hidden name="action" value="plugin">
<input type=hidden name="plugin" value="searchplug">
Enter a thing to search for : 
<input type=text   name="plugin_param1">
<input type=submit value="Search Me">

</form>

Creating External Plugins to be Called from Catalog Pages

• The Plugin program must expect all parameters to be passed to it via the command line.
• Command line parameters must be expected in the order given by the plugin_paramx values, i.e. plugin_param1, followed by plugin_param2, etc.
• The Plugin must emit html by sending it to standard output (STDOUT).
• The Plugin program file must be located in the same directory as the Perlshop program file.
• Any external data files required by the plugin program should be located under the plugins subdirectory.

Creating Event Driven External Plugins

• The Plugin program must expect all parameters to be passed to it via the command line.
• The Plugin must emit html by sending it to standard output (STDOUT).
• The Plugin program file must be located in the same directory as the Perlshop program file.
• Any external data files required by the plugin program should be located under the plugins subdirectory.

Event driven external plugins must accept the following three command line parameters:

1. The name of the event that triggered the plugin, passed as a string value.
2. The order ID number associated with the shopping cart, passed as a string value.
3. The name of the catalog page file being loaded, passed as a string.
   This parameter is only used with the before_page_load and after_page_load events.

The Calendar Sample Plugin

An Example:

• Command Perlshop to generate a web page using the Calendar Plugin:

  Month:	Year:
  January February March April May June July August September October November December Entire Year

• View the source code for the Calendar Plugin.

Internal Plugins

Defining an Internal Plugin

Attribute	Required	Default Value	Description
module	Yes	None	This is the name of the Perl module used for the plugin. The module file is expected to be located in the same directory as the perlshop.cgi file.
display	No	'yes'	This optional field is used to determine whether or not the output of the plugin is to be added to the html of the web page when the plugin is executed. Legal values for this attribute are 'yes' and 'no'.
event	No	One or more event names	This optional field specifies the event(s) that will activate this plugin.
condition	No	None	This optional field specifies the logical conditions that are required to activate this plugin. The condition must be expressed as a Perl language statement. This statement will be executed via Perl eval() function call at the time that the plugin is called. If the statement evaluates to true, the plugin is allowed to execute. If the statement evaluates to false, no further actions are taken. This field is applied to event driven plugin calls only.

An Example:
This example defines an internal plugin named addver. The external Perl module file used for this plugin is called PS_AddVer.pm. The output from this plugin will be included in the web page display. This plugin will be triggered by the before_checkout_cart_contents event.

%plugins =
(
	# Address Verification Display plugin
	'addver' =>
	{
		'module'  => 'PS_AddVer.pm',
		'display' => 'yes',
		'event'   => 'before_checkout_cart_contents'
	}
}

Creating your own Internal Plugins

1. The name of the event that triggered the plugin, passed as a string value.
2. The order ID number associated with the shopping cart, passed as a string value.
3. The name of the catalog page file being loaded, passed as a string.
   This parameter is only used with the before_page_load and after_page_load events.

Internal plugins must also follow these rules:

• The Plugin Dispatch method return value must be used to return content to Perlshop.
• The Plugin module file must be located in the same directory as the Perlshop program file.
• Any external data files required by the plugin program should be located under the plugins subdirectory.

See the source code of the free Address Verification plugin for coding standards and examples.

File Plugins

Defining a File Plugin

Attribute	Required	Default Value	Description
file	Yes	None	This is the name of the file that contains the text to be used. The file is expected to be located in the plugins/files subdirectory.
display	No	'yes'	This optional field is used to determine whether or not the output of the plugin is to be added to the html of the web page when the plugin is executed. Legal values for this attribute are 'yes' and 'no'.
event	No	One or more event names	This optional field specifies the event(s) that will activate this plugin.
condition	No	None	This optional field specifies the logical conditions that are required to activate this plugin. The condition must be expressed as a Perl language statement. This statement will be executed via Perl eval() function call at the time that the plugin is called. If the statement evaluates to true, the plugin is allowed to execute. If the statement evaluates to false, no further actions are taken. This field is applied to event driven plugin calls only.

An Example:
This example defines a file plugin named order_form_as. The plugin uses text from file plugins/files/aftershipping.inc, and will be triggered by the order_form_after_shipping_address event..

This has the effect of inserting the contents of the given file into the Order Form page, just after the Shipping Address section.

%plugins =
(
	'order_form_as'	=>
	{
		'file'    => 'plugins/files/aftershipping.inc',
		'display' => 'yes',
		'event'   => 'order_form_after_shipping_address'
	}
);

Text Plugins

Defining a Text Plugin

Attribute	Required	Default Value	Description
text	Yes	None	This attribute contains the text to be inserted into the web page.
display	No	'yes'	This optional field is used to determine whether or not the output of the plugin is to be added to the html of the web page when the plugin is executed. Legal values for this attribute are 'yes' and 'no'.
event	No	One or more event names	This optional field specifies the event(s) that will activate this plugin.
condition	No	None	This optional field specifies the logical conditions that are required to activate this plugin. The condition must be expressed as a Perl language statement. This statement will be executed via Perl eval() function call at the time that the plugin is called. If the statement evaluates to true, the plugin is allowed to execute. If the statement evaluates to false, no further actions are taken. This field is applied to event driven plugin calls only.

An Example:
This example defines a text plugin named shipping_footer. The text <b>This the footer of the shipping page!</b><br> will be included in the web page display. This plugin will be triggered by the before_page_footer event, and will execute only if the condition

q($action eq 'SHIPPING RATES')

This has the effect of inserting the text of this plugin above the page footer of the Shipping Rates page.

%plugins =
(
	'shipping_footer'	=>
	{
		'text'      => '<b>This the footer of the shipping page!</b><br>',
		'display'   => 'yes',
		'event'     => 'before_page_footer',
		'condition' => q($action eq 'SHIPPING RATES')
	}
);

The Perlshop 4 Event Driven Plugin Model

The following tables list the internal Perlshop events that may be used to trigger plugins.

Events described as Data Processing are useful for internal and external plugins only, and are not intended for page content insertion.

General Content Insertion Events:

Event Name	Category	Description
above_page_footer	Content Insertion	This event is invoked for every page generated by Perlshop, and is used to insert content just above the page footer.
below_page_footer	Content Insertion	This event is invoked for every page generated by Perlshop, and is used to insert content just below the page footer. Plugins that want to insert page content in response to this event should leave their display attributes set to 'no', as Perlshop will handle their inclusion automatically.
header_above_banner	Content Insertion	This event is invoked for every page generated by Perlshop, and is used to insert content just above the Perlshop page banner. Plugins that want to insert page content in response to this event should leave their display attributes set to 'no', as Perlshop will handle their inclusion automatically.
header_below_banner	Content Insertion	This event is invoked for every page generated by Perlshop, and is used to insert content just below the Perlshop page banner. Plugins that want to insert page content in response to this event should leave their display attributes set to 'no', as Perlshop will handle their inclusion automatically.

Events Associated with Catalog Page Loading:

Event Name	Category	Description
after_page_load	Data Processing	This event is invoked when any catalog page is loaded by Perlshop, and after any internal Perlshop logic has executed.
before_page_load	Data Processing	This event is invoked when any catalog page is loaded by Perlshop, and before any internal Perlshop logic has executed.

Events Associated with the Perlshop Add Action:

Event Name	Category	Description
addaction	Data Processing	This event is invoked when the Add action is executed by Perlshop. If any plugins are defined to use this event, those plugins will be called in place of the standard internal Perlshop logic for processing the Add action.
after_add_item	Data Processing	This event is invoked when the Add action is executed by Perlshop, and after any internal Perlshop logic has executed.
before_add_item	Data Processing	This event is invoked when the Add action is executed by Perlshop, and before any internal Perlshop logic has executed.
cart_remove_item	Data Processing	This event is invoked once for each item removed from the shopping cart. Available in version 4.5.02 and later.

Events Associated with the Perlshop Check Out Action:

Event Name	Category	Description
before_check_out	Data Processing	This event is invoked when the Check Out action is executed by Perlshop. Available in version 4.3.03 and later.
before_display_order_form order_form_before_billing_address order_form_after_billing_address order_form_before_shipping_address order_form_after_shipping_address order_form_before_payment_data order_form_after_payment_data order_form_before_shipping_data order_form_after_shipping_data order_form_before_comments order_form_after_comments after_display_order_form	Content Insertion	These events are associated with the Order Form page, and are intended for use for content insertion. The names of the events indicate the locations on the order form where the content insertions will take place.

Events Associated with the Perlshop Enter Action:

Event Name	Category	Description
after_enter_shop	Data Processing	This event is invoked when the Enter action is executed by Perlshop, and after any internal Perlshop logic has executed.
orderid	Data Processing	This event is invoked when the Enter action is executed by Perlshop, and is used to call a plugin that will override the standard Perlshop 4 Order ID generation algorithm. Available in version 4.4.02 and later.

Events Associated with the Perlshop Place Order Action:

Event Name	Category	Description
after_compute_invoice	Data Processing	This event is invoked in response to the Place Order command, after all shipping and handling fees have been calculated.
after_place_order	Data Processing	This event is invoked when the Place Order action is executed by Perlshop, and after all internal Perlshop logic has executed.
before_place_order	Data Processing	This event is invoked when the Place Order action is executed by Perlshop, and before any internal Perlshop logic has executed.
invoice_page_above_print	Content Insertion	This event is invoked when the Place Order action is executed by Perlshop, and is processed while the invoice text is being generated. The text produced by this plugin will be inserted above the Print This Invoice button. Available in version 4.3.02 and later.
invoice_page_above_continue	Content Insertion	This event is invoked when the Place Order action is executed by Perlshop, and is processed while the invoice text is being generated. The text produced by this plugin will be inserted above the Return to Home Page button. Available in version 4.3.02 and later.
invoice_page_footer	Content Insertion	This event is invoked when the Place Order action is executed by Perlshop, and is processed while the invoice text is being generated. The text produced by this plugin will be inserted at the top of the invoice display page. Available in version 4.3.02 and later.
invoice_page_header	Content Insertion	This event is invoked when the Place Order action is executed by Perlshop, and is processed while the invoice text is being generated. The text produced by this plugin will be inserted at the bottom of the invoice display page. Available in version 4.3.02 and later.
item_note	Content Insertion	This event is invoked once for each item displayed in the shopping cart contents table. It is used to insert customized content into the description column for a given item in the cart. This event is intended for use by web sites that implement their own custom content plugins. Available in version 4.5.00 and later.

Events Associated with the Perlshop Restart Action:

Event Name	Category	Description
restart	Data Processing	This event is invoked in response to the Restart command. Available in version 4.5.02 and later.

Events Associated with the Perlshop Shipping Rates Action:

Event Name	Category	Description
after_shipping_table before_shipping_table	Content Insertion	These events are associated with the Shipping Rates Display page, and are intended for use for content insertion. The names of the events indicate the locations on the order form where the content insertions will take place. Note: These events are supported as of Perlshop v4.3.01.

Events Associated with the Perlshop Submit Action:

Event Name	Category	Description
after_submit_customer	Data Processing	This event is invoked when the Submit action is executed by Perlshop, and after any internal Perlshop logic has executed.
before_submit_customer	Data Processing	This event is invoked when the Submit action is executed by Perlshop, and before any internal Perlshop logic has executed.

Events Associated with the Perlshop View Cart Action:

Event Name	Category	Description
after_compute_cart	Data Processing	This event is invoked in response to the View Cart command, after all shipping and handling fees have been calculated.
before_checkout_cart_contents	Data Processing/Content Insertion	This event is invoked when the final checkout View Cart action is executed by Perlshop, just above the table used to display the shopping cart contents. Plugins that want to insert page content in response to this event must have their display attributes set to 'yes'.
before_simple_cart_contents	Data Processing/Content Insertion	This event is invoked when the normal View Cart action is executed by Perlshop, just above the table used to display the shopping cart contents. Plugins that want to insert page content in response to this event must have their display attributes set to 'yes'.
before_view_checkout_cart	Data Processing	This event is invoked when the final checkout View Cart action is executed by Perlshop, and before any internal Perlshop logic has executed.
before_view_simple_cart	Data Processing	This event is invoked when the normal View Cart action is executed by Perlshop, and before any internal Perlshop logic has executed.
item_note	Content Insertion	This event is invoked once for each item displayed in the shopping cart contents table. It is used to insert customized content into the description column for a given item in the cart. This event is intended for use by web sites that implement their own custom content plugins. Available in version 4.5.00 and later.

Events Associated with Invoice Email:

Event Name	Category	Description
add_to_company_email	Content Insertion	This event is used to insert information into the company data section of the store copy of the invoice email. Available in version 4.4.00 and later.
invoice_email_header_html	Content Insertion	This event is used to insert content at the top of the text generated for invoice email. This event is used with html mode email only. Available in version 4.3.02 and later.
invoice_email_footer_html	Content Insertion	This event is used to insert content at the bottom of the text generated for invoice email. This event is used with html mode email only. Available in version 4.3.02 and later.
invoice_email_header_plain	Content Insertion	This event is used to insert content at the top of the text generated for invoice email. This event is used with plain-text mode email only. Available in version 4.3.02 and later.
invoice_email_footer_plain	Content Insertion	This event is used to insert content at the bottom of the text generated for invoice email. This event is used with plain-text mode email only. Available in version 4.3.02 and later.

General Data Processing Events:

Event Name	Category	Description
before_execute_action	Data Processing	This event is invoked in response to any Perlshop action at all except for Enter, and before any action specific internal Perlshop logic has executed.
compute_discount	Data Processing	This event is invoked whenever Perlshop needs to perform the discount calculation on the contents of the shopping cart. This event is intended for use by web sites that implement their own discount computation plugins. This plugin interface is simple to use: Set your $discount_type setting to 'plugin'. Add your custom discount plugin to the plugins definition table. Set it to trigger on the 'compute_discount' event. The discount value for the shopping cart will be set to the value returned by the plugin. Available in version 4.5.00 and later.

Using the Provided Plugin Files

Using the "After Shipping" Order Page Plugin

The order_form_after_shipping_address event is used to add custom content into the Order Form page. This event will insert custom content just below the shipping address fields on the order form.

The order_form_as file plugin uses this event to insert the contents of the aftershipping.inc file into the order form page. In order to use this plugin, the following text would be added to the plugin registration table in the ps.cfg file:

%plugins = ( 
	'order_form_as'   =>
	{
		'file'      =>	'plugins/files/aftershipping.inc',
		'event'     =>	'order_form_after_shipping_address',
		'display'   =>	'yes'
	},
);

Using the Shipping Weight Display Plugin

The before_shipping_table event is used to add custom content into the Shipping Rates page. This event will insert the custom content just above the table that displays the various shipping rates.

This example shows how the before_shipping_table content insertion event can be used to display the total weight of the current shopping cart on the Shipping Rates page. The following text would be added to the plugin registration table in the ps.cfg file:

%plugins = ( 
	'before_shipping'	=>
	{
		'file'      => 'plugins/files/shippingweight.inc',
		'event'     => 'before_shipping_table',
		'display'   => 'yes',
		'eval'      => 1,
		'condition' => 'LoadOrders(1)'
	}
);

The file plugin used in this example is included in the Perlshop 4 zip file.

Defining Custom Plugin Events

• You pick a name for a new plugin trigger event. You can name it anything you like.
• You create a plugin to work with this new event. This plugin can be of any type, and is registered just like any other plugin.
• You call your new plugin anywhere you like inside any of your catalog pages. You do this using the <--#plugin event --> tag.

Step 1: Naming Your Custom Event

Step 2: Adding Your Plugin

Step 3: Using Your Plugin

For example, if you new event is named fred, your tag would look like this:
<--#plugin fred -->

A Simple Example: Inserting Text

For this example, we've defined a new event named display_howdy, and have registered a plugin named howdy to work with it. The display setting for this plugin is turned off because the <--#plugin event --> tag performs the content insertion automatically.

The plugin will be actived anywhere on any catalog web page where the following tag is found:
<!--#plugin display_howdy -->

%plugins = 
( 
	'howdy'	=>
	{
		'text'      => 'Howdy!',
		'event'     => 'display_howdy',
		'display'   => 'no'
	}
);

A Complex Example: Displaying a Shopping Cart Total

This example demonstrates a complex plugin that inserts information describing the current shopping cart contents into a catalog page. The result will be text in this form:

Items in Cart : 3
Subtotal : $73.45

For this example, we've defined a new event named display_cart_contents, and have registered a plugin named cart_contents to work with it.

Please note the following:

• The text setting is left blank because the content isn't known ahead of time.
• The display setting for this plugin is turned off because the <--#plugin --> tag performs the content insertion automatically.
• The condition value is used to preprocess the current shopping cart data and then place the desired content into the $cart_data variable. In this example, the condition value contains raw Perl code that is used to generate the HTML data that will be inserted into the web page.

The plugin will be actived anywhere on any catalog web page where the following tag is found:
<!--#plugin display_cart_contents -->

%plugins = 
( 
	'cart_contents'	=>
	{
		'text'      => '',
		'event'     => 'display_cart_contents',
		'display'   => 'no',
		'condition' =>	
q(
LoadOrders(1);
$plugins{'cart_contents'}->{'text'} = 
    "Items in Cart : $total_quantity<br>\nSubtotal : \$" . 
    sprintf('%1.2f', $total_price) . "<br>\n";
)
	}
);