©2003-2010 Whorl Ltd.No part of this documentation may be reproduced without the express written permissionof Whorl Ltd.

2.3.0 Update Manual

Documentation Version: 2.3.0(Revision Date: 04/11/2010)

"This product includes PHP, freely available from http://www.php.net/"

mySQL, Xitami, phpMyAdmin, Linux, Apache, Windows, Quickbooks are copyright their respective owners.InnovaStudio WYSIWYG Editor is ©2007 INNOVA STUDIO. Used under license. The InnovaStudio WYSIWYGEditor may not be used outside of JShop Server without separate licensing from InnovaStudio(http://www.innovastudio.com/)

2.3.0 Update Manual : Contents

© 1997-2010 Whorl Ltd. Reproduction prohibited without permission.

Table of Contents

Part 1 Introduction 3

................................................................................................................................... 31.1 Welcome

................................................................................................................................... 31.2 Update Installation Service

Part 2 Updating To 2.3.0 4

................................................................................................................................... 42.1 What's New in 2.3.0

................................................................................................................................... 42.2 Changes That May Affect You

................................................................................................................................... 42.3 Installing 2.3.0

................................................................................................................................... 62.4 Template Changes

......................................................................................................................................................... 62.4.1 New Templates

......................................................................................................................................................... 62.4.2 Search Suggest

......................................................................................................................................................... 72.4.3 Country Change on cart.html

......................................................................................................................................................... 72.4.4 Offer Code Entry on cart.html

......................................................................................................................................................... 82.4.5 Other Offer Code Changes

......................................................................................................................................................... 92.4.6 Dispatch Information on Order History

......................................................................................................................................................... 92.4.7 Order Status Display

......................................................................................................................................................... 92.4.8 Automatic Discounts

......................................................................................................................................................... 102.4.9 Automatic Browser RSS Links For Articles

......................................................................................................................................................... 102.4.10 Canonical link Tag

......................................................................................................................................................... 102.4.11 Paypal Express

......................................................................................................................................................... 112.4.12 Google Checkout

......................................................................................................................................................... 112.4.13 One Step Checkout

......................................................................................................................................................... 122.4.14 One Step Checkout Changes for checkoutstep4.html

......................................................................................................................................................... 132.4.15 Using Articles For News

Index 15

3Introduction : Welcome

3

1 Introduction

1.1 WelcomeWelcome to the update installation manual for JShop Server. This manual will take you through the process ofupdating your JShop Server installation to a later version. Some basic procedures need to be followed in orderto install JShop Server and the following facilities will be required by the installation process:

An FTP (File Transfer Protocol) client through which you can upload the JShop Server files to your webserver.A file editor in order to edit the config.php file for your JShop Server installation.To use new features you may need to make changes to your templates and these are given (based on thedefault templates) in this document.Updates may require you to make changes to your store in order for it to still operate correctly. Again, theseare highlighted in this document.

You will not require any in-depth PHP knowledge or mySQL administration knowledge in order to perform theupdate installation.

Please note that rectifying an update installation that you have attempted yourself will require the purchase ofour update installation service.

NOTE: We recommend backing up your JShop Server files and database before installing the update andturning your store off in General -> Global Options to make your store unavailable during the upgradeprocedure. Installing this upgrade is done at your own risk. We do not accept any responsibility or liabilityfor any damages, either directly or indirectly caused by installing this upgrade. Installing upgrades shallbe taken as acceptance of this disclaimer.

1.2 Update Installation ServiceWe do offer an update installation service for JShop Server which is available by logging into the RegisteredUsers Area, selecting 'Your Licenses' and then selecting 'Order Extra Services'. This is priced at 30 GBP (plusVAT at the prevailing United Kingdom rate where applicable). This update installation service will provide aprofessional update installation of JShop Server. We will backup your data before installing the update (whichwe will subsequently remove from our systems once the update has been applied correctly) and disable yourstore during this procedure. Installing an update generally takes around an hour and we will pre-arrange asuitable time with you for it to be completed. Once completed your store will be re-enabled.

If you have any questions about the update installation service please feel free to contact us at sales@jshop.co.uk and we'll be happy to help.

Please note that rectifying an update installation that you have attempted yourself will require thepurchase of our update installation service.

4Updating To 2.3.0 : What's New in 2.3.0

4

2 Updating To 2.3.0

2.1 What's New in 2.3.02.3.0 is a major update to JShop Server which add the following main new features:

Built in content management system called ArticlesOffer code and automatic discounts re-written to provide support for discounts linked to products, sectionsand categories and different discount types.Support for Paypal Express and Paypal Website Payments ProSupport for Google CheckoutIntegrated search suggest system for your storeOne Step Checkout optionGreater template flexibility which allows the embedding of template variables, attributes and commands inany field in JShop ServerBuilt in XML sitemap productionSupport for canonical link tags and separate SEO title fields for use in URLs for products, sections andarticles

These are just some of the main highlights in 2.3.0 and a full list of changes can be located on the 'ReleaseNotes' page accessible from the Download page in the Registered Users Area.

It is important that you take notice of the 'Changes That May Affect You' section of this document as there anumber of changes which could potentially break existing sites.

2.2 Changes That May Affect YouThere are a number of changes in version 2.3.0 that may need attention in order to ensure that your sitecontinues to operate as normal. These are as follows:

PHP 5.3.0 depreciates the use of the ereg group of regular expression functions and with PHP 6.0.0 thisfunction will be removed entirely. JShop Server used this group of functions in several areas, mainly to dowith field validation routines. If you have entered any custom regular expressions for field validations in theadministration system you will need to alter these to Perl compatible versions. In most cases this can beachieved by simply adding / characters to the start and end of the regular expression.A new version on the InnovaStudio WYSIWYG editor has been included as of 2.3.0 (Beta 2). This hasrequired changes to the default WYSIWYG config files. If you are using a custom one, please note inparticular the changes required to call the file manager correctly.If you have created a cartOutputExtra.php or emailOutputExtra.php file please note that 2.3.0 includeschanges to the way that $requiredVars is returned by tSys to help for more granular isolation of whatvariables and attributes are used. Please see the Developer Manual for more information on the changesrequired.

2.3 Installing 2.3.0

Step 1

First of all you will need to login to the Registered Users Area, click on the 'Downloads' link and click the 'VisitDownload Page' link for 2.3.0. On the next page you will find all the installation files available for this version ofJShop Server. You should select the update zip file applicable to your current version of JShop Server. You canascertain what version of JShop Server you are currently running by logging into your store's administrationsystem and looking along the top title bar - this will show the current version. If you are running an olderversion that does not have an update zip file available for it, you will first need to install a more up to dateversion by using the updaters available for previous versions.

5Updating To 2.3.0 : Installing 2.3.0

5

Step 2

Turn your shop off using the option in General -> Global Settings in your JShop Server administration system.Once you have obtained the correct update zip file, unzip this locally and upload these files to your server. Thefiles will automatically be in the correct directories so just ensure that you upload the files to your main JShopServer root directory on your server. The only exception to this may be the admin directory which, is you havechanged the name of on the server for security reasons, you should also rename before uploading.

Step 3

Add the following lines to the bottom of your config.php file to support the new tables required by this version:

$tableOfferCodesProducts = "jss_offer_codes_products";$tableDiscountsProducts = "jss_discounts_products";$tableArticles = "jss_articles";$tableArticlesExtraFields = "jss_articles_extrafields";

Step 4

Use a web browser and visit your site to open the update installation script. This will be located in a sub-directory called update. So, if your store is installed in http://www.yourdomain.com/, then you would visitthe following URL in your web browser: http://www.yourdomain.com/update/update.php

Step 5

Follow the on-screen instructions to update your JShop Server database. You will need to accept the currentend user license in order to proceed.

Step 6

Login to your JShop Server admin system and, if you are using compiled templates, remove all the compiledtemplates for your store using the facility in Templates. This is required, otherwise your store will not showcorrectly.

Step 7

Once complete you should remove the update directory, and the files within it, from your web server as it is nolonger required. You can now turn on your store again.

Step 8

A new shopimages directory called shopimages/articles will need permissions changing in order to be able toupload any images to extra article fields via the admin system – please refer to the standard installationdocumentation for more information on directory permissions.

Optional Changes to config.php

6Updating To 2.3.0 : Installing 2.3.0

6

A new option is available in the config.php file to force a character set for the admin system to use. To use thisnew feature simply add the following line to your config.php file:

$jssCharset = "ISO-8859-1";

You may change the ISO-8859-1 to any default you wish to use. Setting this will, particularly in IE, ensure thatspecial characters entered are displayed correctly. However please note that this may cause problems withpreviously entered special characters, and they may need to be re-entered.

2.4 Template Changes

2.4.1 New Templates

The following new templates are included in 2.3.0:

article.html - Basic article layoutarticle_newslist.html - Article template used for displaying news in new installationsarticle_news.html - Article template used for individual news itemsdiscount.html - Used to display a list of qualifying products and sections for automatic discountscheckout1step.html - The new 1-step checkout templateincludes/discount_paging.html - Paging for products on discount.html template

2.4.2 Search Suggest

Include the following lines in your css file:

/* HELP: The search suggest drop down. Do not remove position, left or z-index! */#search_suggest {

position: absolute; background-color: #FFFFFF; text-align: left; border: 1px solid #000000;visibility: hidden;width: 150px;top: 0px;left: 0px;z-index: 200;

}

/* HELP: Styling for link div in the search suggest box */.suggest_link {

background-color: #FFFFFF;padding: 2px 6px 2px 6px;font-weight: normal;

}

/* HELP: Styling for text highlights in search suggest box */.suggest_link_highlight {

background-color: #FFCC33;font-weight: bold;

}

/* HELP: Styling for link div with mouse over in search suggest box */.suggest_link_over {

background-color: #3366CC;padding: 2px 6px 2px 6px;cursor: pointer;

}

7Updating To 2.3.0 : Template Changes

7

In the template where you output the main search form in Jshop Server, the following is the new defaulttemplate code for the search text field:

<input type="text" id="{search.form.string}" name="{search.form.string}" value="{search.query}" class="search-box" <#if:options.searchSuggestOn:eq:Y#>onkeyup="jss_searchSuggest(this,{options.searchSuggestTrigger},this.form,event);" onblur="jss_searchSuggestDelayBlur();"<#/if#> autocomplete="off"/>

If you have your own custom search text file just ensure that you include the section above between the ifstatement (including the if statement). In addition, after the search text box add the following:

<div id="search_suggest"></div>

2.4.3 Country Change on cart.html

In your cart.html you can now add the following to provide offer the customer with the ability to change thedelivery country on the cart for shipping informational purposes. During checkout the correct shipping will showonce a full delivery address has been provided:

<#if:options.allowShippingAddress:eq:1#><h2>{labels.cart.changeDeliveryCountry}</h2><div class="general-table-div"><!-- output of shopping cart --><form name="changeCountry" method="post" action="{cart.countrychange.form.action}"><table class="general-table" cellspacing="1">

<caption>&nbsp;</caption><tr>

<th>{labels.general.country}</th><th>&nbsp;</th>

</tr><tr>

<td><select name="country"><#loop:countries#>

<option value="{countries.countryID}" <#if:cart.deliveryCountry:eq:countries.countryID#>selected="selected"<#/if#>>{countries.name}</option>

<#/loop#></select>

</td><td><input type="submit" name="cssubmit" value="{labels.cart.

changeDeliveryCountry}" class="button"/></td></tr>

</table></form></div>

<#/if#>

2.4.4 Offer Code Entry on cart.html

In your cart.html you can now add the following to provide offer code entry on the cart page:

<#if:options.offerCodesEnabled:eq:1#><#if:cart.offerCode:eq:blank#>

<h2>{labels.ordering.offerCodeHeading}</h2><div class="general-table-div">

<#if:cart.offerCodeError:eq:INVALID#><br/><span class="error-text">{labels.ordering.

8Updating To 2.3.0 : Template Changes

8

offerCodeErrorInvalid}</span><#/if#><#if:cart.offerCodeError:eq:EXPIRED#>

<br/><span class="error-text">{labels.ordering.offerCodeErrorExpired}</span>

<#/if#><#if:cart.offerCodeError:eq:CURRENCY#>

<br/><span class="error-text">{labels.ordering.offerCodeErrorCurrency}</span>

<#/if#><#if:cart.offerCodeError:eq:USED#>

<br/><span class="error-text">{labels.ordering.offerCodeErrorUsed}</span>

<#/if#><#if:cart.offerCodeError:eq:BELOWVALUE#>

<br/><span class="error-text">{labels.ordering.offerCodeErrorBelowValue}</span>

<#/if#><#if:cart.offerCodeError:eq:PRODUCTS#>

<br/><span class="error-text">{labels.ordering.offerCodeErrorProducts}</span>

<#/if#><form name="{cart.offercode.form.name}" method="post" action="{cart.

offercode.form.action}"><table class="general-table" cellspacing="1">

<caption>&nbsp;</caption><tr>

<th>{labels.ordering.offerCodeTitle}</th><th>&nbsp;</th>

</tr><tr>

<td><input id="xOfferCode" name="xOfferCode"/>

</td><td><input type="submit" name="cssubmit"

value="{labels.cart.applyOfferCode}" class="button"/></td></tr>

</table></form>

</div><#/if#>

<#/if#>

2.4.5 Other Offer Code Changes

On checkoutstep3.html the following addition can be made to the list of offer code errors:

<#if:ordering.payment.offerCodeError:eq:PRODUCTS#><br/><span class="error-text">{labels.ordering.offerCodeErrorProducts}</span>

<#/if#>

On the cart.html template the following can be used to replace your existing discount line to provide feedbackon offer code used and a remove link:

<th class="total" colspan="5">{labels.cart.discountTotalTitle}<#if:cart.offerCode:neq:blank#>, Offer Code {cart.

offerCode} <a href="{cart.offercode.remove}">Remove</a><#/if#></th>

9Updating To 2.3.0 : Template Changes

9

2.4.6 Dispatch Information on Order History

To include dispatch information on the customer's order history, include the following on customerorder.html:

<#if:order.dispatches.available:eq:Y#><h2>{labels.order.dispatchTitle}</h2><div class="general-table-div">

<table class="general-table" cellspacing="2"><tr>

<th>{labels.order.dispatchDate}</th><th>{labels.order.dispatchCourier}</th><th>{labels.order.dispatchTracking}</th><th>{labels.order.dispatchAdditional}</th>

</tr><#loop:order.dispatches.entries#>

<tr><td>{order.dispatches.entries.formattedDate}</td><td>{order.dispatches.entries.courier.name}</td><td>{order.dispatches.entries.trackingReference} <#if:

order.dispatches.entries.courier.weburl:neq:blank#> (<a href="{order.dispatches.entries.courier.weburl}">{labels.order.dispatchTrackLink}</a>)<#/if#></td>

<td>{order.dispatches.entries.trackingMisc}</td></tr>

<#/loop#></table>

</div><#/if#>

2.4.7 Order Status Display

On customerorderlist.html a new field is available to replace the long list of if statements currently used tooutput the current order staus. These can now be replaced with:

{orderlist.orders.statusName} or {orderlist.orders.statusNameNative}

2.4.8 Automatic Discounts

A new template called discount.html has been added which is used to display products and sections included ina given automatic discount. The layout of this template is much the same as the section.html template.

Additionally, to show discounts that a product is included on, the following code can be used on the product.html template:

<#loop:product.discounts#><span class="smaller-text"><a href="{product.discounts.link}">{product.discounts.

title}</a><br/></span><#/loop#>

To show discounts that apply to a given section, the following code can be included on your section.htmltemplate:

<#loop:section.discounts#><span class="smaller-text"><a href="{section.discounts.link}">{section.discounts.

title}</a><br/></span><#/loop#>

On cart.html, ordering_cart.html and cartstockproblem.html the following code can be placed as part of thediscount line to show the names of the discounts that have been activated for the cart:

10Updating To 2.3.0 : Template Changes

10

<#loop:cart.discounts.ids#><br/>{cart.discounts.ids.title}

<#/loop#>

Finally, a loop of the currently active discounts in your store can be included in your templates. By default, thefollowing code is included in the default leftmenu.html template to show the discounts underneath the mainsection list for your store:

<#if:loop.discounts.total:gt:0#><div class="menu-box">

<div class="menu-box-title">{labels.navigation.discounts}</div><div class="menu-box-content">

<ul id="menu-section-list"><#loop:discounts#>

<li><a href="{discounts.link}">{discounts.title}</a><#/loop#>

</ul></div>

</div><#/if#>

2.4.9 Automatic Browser RSS Links For Articles

To include support for the automatic RSS links in browsers (for instance, in Firefox a page with an RSS feedwill show an RSS icon at the right side of the address bar) place the following in your top.html file after the<head> but before the </head> tag:

<#if:shop.rssLink:neq:blank#><link rel="alternate" href="{shop.rssLink}" title="{shop.rssTitle}"

type="application/rss+xml"/><#/if#>

2.4.10 Canonical link Tag

To include support for the canonical link tag place the following in your top.html file after the <head> butbefore the </head> tag:

<#if:shop.pageCanonical:neq:blank#><link rel="canonical" href="{shop.pageCanonical}" />

<#/if#>

2.4.11 Paypal Express

Paypal has a number of requirements for their branding if you are using Paypal Express on your site. Theseare detailed on the following document from Paypal's website:

https://cms.paypal.com/us/cgi-bin/?cmd=_render-content&content_ID=developer/e_howto_api_WPButtonPlacement

We cover those requirements with the following additions.

At the top of rightmenu.html, directly under the first <div> tag place the following:

<#if:options.checkoutPaypalExpress:eq:Y#><#if:checkout.paypalExpressAccountCheck:eq:Y#><div style="text-align: center;"><a href="{checkout.paypalExpressLink}"><img

11Updating To 2.3.0 : Template Changes

11

src="https://www.paypal.com/en_US/i/btn/btn_xpressCheckout.gif" style="margin-bottom: 0px;margin-top: 10px; border: 0px;"></a></div>

<#/if#><#/if#>

On product.html place the following under where your add to basket button is output:

<#if:options.checkoutPaypalExpress:eq:Y#><#if:checkout.paypalExpressAccountCheck:eq:Y#><div>

<img src="https://www.paypal.com/en_GB/i/bnr/bnr_nowAccepting_150x40.gif"border="0" style="margin-top: 10px;">

</div><#/if#>

<#/if#>

On checkoutstep3.html replace:

{ordering.payment.options.name}

With:

<#if:ordering.payment.options.type:eq:PAYPAL#><img src="https://www.paypal.com/en_US/i/logo/PayPal_mark_37x23.gif" align="left"

style="margin-right:7px;"><span style="font-size:11px; font-family: Arial, Verdana; font-weight: normal; position: relative; top: 4px;">The safer, easier way to pay.</span><#else#>

{ordering.payment.options.name}<#/if#>

You also need to ensure that in order to comply with Paypal's branding requirements for the use of PaypalExpress that you re-order the payments options to place Paypal at the top of the list.

2.4.12 Google Checkout

Google Checkout has a number of requirements for their branding. Basically these are as follows, although youshould consult Google’s own documentation for detailed information.

At the top of rightmenu.html, directly under the first <div> tag place the following:

<#if:options.googleCheckoutEnabled:eq:Y#><#if:checkout.googleCheckoutAccountCheck:eq:Y#>

<a href="{checkout.googleCheckoutLink}"><img src="https://checkout.google.com/buttons/checkout.gif?{options.googleCheckoutButton}" style="border: 0px; {options.googleCheckoutButtonStyle}"></a>

<#/if#><#/if#>

2.4.13 One Step Checkout

JShop Server’s one step checkout implementation using JavaScript/AJAX and, as such, for those peoplebrowsing without JavaScript turned on, they will be forwarded to the normal, multi-step checkout. To supportthis, checkout links in your templates need to be altered to allow those with JavaScript to go to the one stepcheckout, those without to the normal one.

In the standard templates, in top.html you can alter the standard checkout from this:

12Updating To 2.3.0 : Template Changes

12

<a href="{checkout.link}">

To this:

<a href="{checkout.link}" <#if:options.checkout1Step:eq:Y#>onclick="jss_1stepCheckout('{checkout.1steplink}'); return false;"<#/if#>>

Any other checkout links that you have should also be altered in this way.

The one step checkout also uses a new template, called checkout1step.html, which you may need to alter tosuit your site design. This template is quite complex due to the use of JavaScript/AJAX.

2.4.14 One Step Checkout Changes for checkoutstep4.html

When using the order summary before submit option for the one step checkout, changes should be made tocheckoutstep4.html to avoid showing the extra order field entry boxes and also to allow the customer to openan account at the end of the ordering process if they’ve used the standard multi-page checkout. This changeshould replace the section that currently outputs the extra order fields. In the default templates this looks likethis:

<div class="form-div"><table class="form-table" cellspacing="1"><caption>&nbsp;</caption><#include:includes/order_extra_fields.html#><tr><td class="submit-row" colspan="2"><input type="submit" name="submit" value="{labels.ordering.submitOrder}" class="button"/></td></tr></table></div>

You should replace it with this:

<div class="form-div"><table class="form-table" cellspacing="1"><caption>&nbsp;</caption><#if:ordering.details.checkoutType:neq:1step#>

<#include:includes/order_extra_fields.html#><#/if#></table>

</div><#if:ordering.details.checkoutType:neq:1step#><#if:options.customerAccounts:eq:1#>

<#if:ordering.details.loggedin:neq:Y#><h2>{labels.customer.createAccountButton}</h2><div class="form-div">

<table class="form-table" cellspacing="1"><tr>

<th colspan="2"><input type="checkbox"name="xCreateAccount" id="xCreateAccount" value="Y" <#if:ordering.details.xCreateAccount:eq:Y#>checked="checked"<#/if#>/> {labels.customer.createAccountButton}<#if:ordering.details.accountexists:eq:Y#><span class="error-text"><br/>{labels.customer.errorEmailExists}</span><#/if#></th>

</tr><tr>

<th>{labels.customer.newPassword} <span class="error-text">*</span></th>

<td><input type="password" name="xCreatePassword"

13Updating To 2.3.0 : Template Changes

13

size="20" maxlength="20" value=""/><!-- error checking --><#if:ordering.details.passworderror:eq:

NOTMATCHING#><br/><span class="error-text">{labels.

customer.errorPasswordNotMatching}</span><#/if#><#if:ordering.details.passworderror:eq:BLANK#>

<br/><span class="error-text">{labels.customer.errorPasswordBlank}</span>

<#/if#><#if:ordering.details.passworderror:eq:TOOSHORT#>

<br/><span class="error-text">{labels.customer.errorPasswordTooShort}</span>

<#/if#>

</td></tr><tr>

<th>{labels.customer.repeatPassword} <span class="error-text">*</span></th>

<td><input type="password" name="xCreatePassword2"

size="20" maxlength="20" value=""/></td>

</tr></table>

</div><#/if#>

<#/if#><#/if#><h2>{labels.ordering.submitOrder}</h2><div class="form-div"><table class="form-table" cellspacing="1"><tr>

<td class="submit-row" colspan="2"><input type="submit" name="submit"value="{labels.ordering.submitOrder}" class="button"/></td></tr></table></div>

2.4.15 Using Articles For News

With the advent of 2.3.0, the old News section in JShop Server is depreciated. This means that, whilst it is stillcurrently available in 2.3.0, from the next version this section will be removed completely. This has been doneas the new Articles system in JShop Server provides much greater functionality. The new default templates forJShop Server use the Articles section for displaying news, instead of the pre-existing news section.

For users upgrading, you can create an article with a 'Name (For Templates)' field containing News. You canthen replace your news headlines in your templates (normally on the left menu) with the following:

<!-- news items --><#if:loop.article=News.subarticles.total:gt:0#>

<div class="menu-box"><div class="menu-box-title">{article=News.title}</div><div class="menu-box-content">

<ul id="news-links"><#loop:article=News.subarticles:5#>

<li><a href="{article=News.subarticles.link}">{article=News.subarticles.title}</a> <span class="smaller-text">({article=News.subarticles.date})</

14Updating To 2.3.0 : Template Changes

14

span></li><#/loop#></ul>

</div></div>

<#/if#><!-- /news items -->

You should also ensure that you have the new article.html, article_news.html and article_newslist.htmltemplates copied into your templates folder in order for the pages to display correctly.

Index

Bbackup 3

FFile Transfer Protocol 3

FTP 3

MmySQL 3

RRegistered Users Area 3

Uupdate installation service 3