Integrator Guide

Installation

Open Store uses the DNN CMS and requires a minimum of DNN version 8

While Open Store can have multiple websites for each DNN installation, it does NOT support "child" portals, you must create "parent" portals. 

There are 2 options to install Open Store with DNN.  After completing the installation, continue with the Open Store settings section. (below)

Installation Option 1

Use the full install package for Open Store

Download "OpenStore_DNN_Platform_8.0.4.226_Install.zip" from https://github.com/Open-Store-Project/Open-Store/releases

Install this zip as you would a normal DNN installation.  http://www.dnnsoftware.com/wiki/how-to-install-dotnetnuke

Optional : Once installed you can then apply the Open Store DNN site template.  This can be found in the default portal and is called "OpenStoreDemo.template", you can use the Site Wizard to apply the template.  This is an optional step to help speed up the setup of the website, but you can choose to apply the modules onto the page yourself..

Notes

The install package "OpenStore_DNN_Platform_8.0.4.226_Install.zip " is a standard DNN installation package, with the extra modules required to run Open Store included and installed automatically for you.

Installation Option 2

Install Open Store on an existing DNN installation

The method of installation can be applied to a DNN installation already existing or a new standard DNN install.

1.1 Install NBrightDNN_TemplateSys

Download the NBright Template System and install as you would a normal DNN module "NBrightDNN_TemplateSys_v**.**.**.**.zip"

https://github.com/nbrightproject/NBrightTS/releases

1.2 Install The Open Store package

Download the Open Store package and install as you would a normal DNN module "OpenStore_4.*.*_Install.zip"

https://github.com/Open-Store-Project/Open-Store/releases

1.3 Optional : Demo DNN Template

This document will try to explain the setup of Open Store by using a DNN template to speed things up, there is no need to use this DNN template and you may setup the different modules of Open Store as best fits your requirements.

Download the file "OpenStore_DNN_Template.zip" from the doenload link and unzip it in the DNN "/Portals/_default" folder.  Then use the DNN "Site Wizard" to build the site using this template.

Open Store settings

After creating the site structure with the DNN wizard (or manually). Enter the Open Store Back Office through the Admin>Open Store Back Office page.

NOTE : To create a Back Office page you create a page, remove all modules and then apply the "NBrightStoreBO" skin which is installed in your host skins when you install Open Store.  (If you used the DNN site template this has already been done this for you)

The first time you enter the BO you must save the default settings so goto Admin>Settings and simply click the "Save" button.

(FIX: In certain situation a cached error may be displayed on entry to the BO, if this happens exit the BO, clear cache or restart app and then go back into the BO.  It should then continue as normal)

NOTE: If you have issues with images not uploading correctly, you can use BO>Tools>Validate Store to ensure the settings are activated correctly.

Next the Store configuration should be setup (BO>Admin>Settings), in this example the pages are already created by the DNN template and so we simply need to assign what we have.

Module settings

OS_FullCart

On the Basket page, the OS_FullCart module settings will also need changing to redirect to the checkout.  The idea of having a FullCart Page and a Checkout page is so that on webistes which need a login the DNN security can be activated to force a login before the client fills out the address on the checkout.  (i.e. the Fullcart page has public access the Checkout page has only registered User access.)

OS_CategoryMenu

In this example the we're going to use the Treeview category menu, this needs to be setup in the OS_CaetgoryMenu module settings, so on the "On-line Shop" Page go into the category menu module settings and alter the "Menu Type" setting of menu to Treeview.

All Other OS Modules

For all OS modules the settings will need to be configured, so go into each OS module in each page and save the module settings. 

After all the modules have been updated, don't forget to clear the DNN cache to make sure you get all the correct setting.  You can do this by using the DNN clear cache option or by recycling the app pool.

Setup

Emails

DNN security system always uses the site administrator email as the “from” email for user notification.  While all the OS emails use the OpenStore admin email address.

The normal method of setup would be to create a new admin user for the site and set the email to the same as the OpenStore admin email address, then all “from” email addresses would be the same.

Scheduler Setup

Nevoweb.DNN.NBrightBuy.Components.NBrightBuyScheduler,NBrightBuy

The scheduler will run each provider plugin that is linked to the scheduler.  It will also clear down files older than 3 hours in the temporary OS folder.

Purchasable Downloads

If purchasable downloads are being used the you should restrict direct access to the OpenStore/docs folder.

This can eb done by adding a request filter into the web.config.

Example:

  <system.webServer>
       <security>
          <requestFiltering>
               <hiddenSegments>
                   <add segment="NBStore" />
               </hiddenSegments>
           </requestFiltering>
       </security>    
  </system.webServer>

Store Themes

OpenStore is installed with a default theme of ClassicAjax and Default.  In general "Default" contains checkout templates and templates that will not usually be changed, "ClassicAjax" contains templates that create the lient UI and hence will be changed for most bespoke designs.

Themes exist on the file system under a folder called "Themes".  In the case of ClassicAjax the theme folder exists as :

/DesktopModules/NBright/NBrightBuy/Themes/ClassicAjax

To create a new theme, create a folder under this "Themes" folder.  The folder name will be the name of the new theme and you'll need to include all  the required templates.

Themes placed in the "/DesktopModules/NBright/NBrightBuy/Themes" can be applied across all portals in the DNN installation.

If you want to create a bespoke theme for a single portals then you can create your theme folder under your portal root:

/Portals/MyPortal/Themes/MyThemeName

If you only want change or tweek the ClassicRazor theme for a specific portal you can create a "ClassicAjax" theme folder under your portal and add any templates you wish to change into this new "ClassicAjax" folder:

/Portals/MyPortal/Themes/ClassicAjax

Any files/templates found in this folder will be used in replacement of the installation wide file/template in the "DesktopModules/NBright/NBrightBuy/Themes/ClassicAjax" folder.

Theme Folder Structure

Each theme must use a set folder structure.  This structure includes a default template folder, resource folders and language folders for languages independent templates.

.../Themes/MyTheme
                    |
                    |- css
                    |- Default
                    |- fr-FR
                    |- js
                    |-resx

 CSS

Folder to keep css files that will be injected by the theme.

Default

Folder to keep all the default templates for the theme

fr-FR

Language theme folder, all the templates for a theme which needs to be different for a language, if a template is included in this folder it will be used instead of the "Default" templates when that language is active.  If no template exists in this folder for a given language then the default template is used.  The name of the folder is based on the culture code for the lanaguge. (fr-FR = French,, en-GB = UK, etc..)

JS

JavaScript files that are required by the theme.

RESX

Resource files that are used by the theme.  (NOTE: DNN label controls will not use these resx files for the help.  So if you need to use a dnn label control with the help then you need to add the resx data to the module resx files. )

More Explanation

The template system is designed to work on 2 levels. System (DesktopModules) and Portal level.

First the template system will look for a theme on the portal level and initailly in the language folder of the portal theme, if a template with the correct name is not found there, it will then look in the "default" folder of the portal theme.

Again if the template cannot be found on the Portal Level the template system will look at the system level. First at the language folder, then at the default.

So if you want your Portal to use a bespoke template, but don't want to overwrite the default system template (Which will be overwritten on upgrade) then you need to either create a new Theme folder with a new name or create a Theme folder at portal level.

For example, if I want to create a portal "0" version of the "ClassicRazor" "NBS_MiniCart.cshtml" template I would create a folder and file on the portal at :

/Portal/0/Themes/ClassicRazor/default/NBS_MiniCart.cshtml

If I wanted a lanaguge specific template then I would create:

/Portal/0/Themes/ClassicRazor/fr-FR/NBS_MiniCart.cshtml

If you want to create a new Theme, then At system level you can create :

\DesktopModules\NBright\NBrightBuy\Themes\MyNewTheme\Default\NBS_MiniCart.cshtml

And alter your module settings to use this new theme "MyNewTheme". All other templates not found in the "MyNewTheme" theme folder will be taken from the NBS default "ClassicRazor".

P.S. You could also create the "MyNewTheme" at Portal level.

Data Format

DataBase Tables

OpenStore Database structure is made of 3 tables, NBrightBuy, NBrightBuyIdx and NBrightBuyLang.

NBrightBuyIdx and NBrightBuyLang are only data index tables to help speed up processing of SQL queries, they are populated by triggers on the NBrightBuy.  These 2 tables DO NOT hold the OpenStore data.

The NBrightBuy table is the only "data table" and stores all the data that is required by OpenStore.  This table uses an XML structure to store different data types and it's this XML data that allows NBS to be so flexible.  The draw back of this type of data store is that SQL queries are more difficult/complex and updating the table through SQL is far more difficult.  We do plan to implement a set of views for OpenStore so extracting data is more simple.  But the updating of the table through SQL queries will always be difficult, that's one of the penities we have to accept when making such a dynamic system.

XML Format

The best way to find the XML data format is to place the store into "debug file output mode" this checkbox can be found in the BO>Admin>Settings. Then looking at a product from the front office will output a debug xml file of the product.  You'll see a debug_entry.xml file appear inthe portal root, this is the XML data format that the template system works with.

NOTE: There are also other debug files created in debug file output  mode for other data strucutre in OpenStore.

Search

The search functionality on NBSv3 is built by using 2 (or more) modules.  These modules work together to produce selection criteria the user has specified.  This document briefly explains how these module work and what template data needs to be specified to create bespoke search criteria.

NBS_DisplaySearch

This module displays the search criteria and saves that search criteria to a temporary file which the NBS_DisplayProducts module uses. 

In the settings of the module you can specify which NBS_DisplayProducts module the filter criteria is designated for, you use the module ref of the NBS_DisplayProducts module (found in module settings) to define this.

When the search criteria is posted back to the server (via ajax) a cookie is created on the client machine and a temporary XML file created in the Portals/{portal}/NBS_Temp folder.  This operation is done by the “XmlConnector.cs” with the command “dosearch”.

NBS_DisplayProducts

This module displays the products selected, using the criteria specified in the temporary file created by NBS_DisplaySearch.  NBS_DisplayProducts reads the cookie which has the reference to the required temporary file with the search criteria.

Specifying Search Criteria

The search criteria and filter for selecting products is done in the search template.  Hidden meta data fields in the template define what the search criteria should be, when the search is activated by the user an ajax call to the server uses the “NavigationData.cs” class on the server to read these meta fields and to build a SQL filter which will be used by the NBS_DisplayProduct module to select which products to display.

The actual data used in the SQL filter is defined by the use of client side input fields, which are also posted back with the ajax call.

Adv Search Template Example

166
OT-AmylisSearch.cshtml
65
OT-AmylisSearch_head.cshtml

Category Menu

DDRMenu Integration

<dnn:MENU MenuStyle="Mega2DNN" runat="server" NodeManipulator="Nevoweb.DNN.NBrightBuy.Components.DdrMenuInterface,NBrightBuy"></dnn:MENU>

The category structure can be injected into the DDRmenu by creating a page in DNN called "[CAT]".  When the node manipulator "Nevoweb.DNN.NBrightBuy.Components.DdrMenuInterface,NBrightBuy" is used on the DDRMenu control, this page will be replaced with the NBS category structure.

Display Category Image on DDR Menu

Example of code :

<xsl:if test="@largeimage!=''">
  <xsl:if test="contains(@largeimage,'?')">
  <img><xsl:attribute name="src"><xsl:text>/DesktopModules/NBright/NBrightBuy/NBrightThumb.ashx?w=120&amp;h=43&amp;src=</xsl:text><xsl:value-of select="substring-before(@largeimage,'?')" /></xsl:attribute></img>
  </xsl:if>
  <xsl:if test="not(contains(@largeimage,'?'))">
  <img><xsl:attribute name="src"><xsl:text>/DesktopModules/NBright/NBrightBuy/NBrightThumb.ashx?w=120&amp;h=43&amp;src=</xsl:text><xsl:value-of select="@largeimage" /></xsl:attribute></img>
  </xsl:if>
</xsl:if>

Orders

Order Status

The order status is altered either automatically or manually throughtout the order process.

The values can be found on the DB record in the NBrightBuy table with a TypeCode='ORDER'. The column GUIDKey will hold the value which is used for processing. The display/edit value for the dropdown on the UI is saved on the XML field as "genxml/dropdownlist/orderstatus"

Incomplete 010 Waiting for Bank 020 Cancelled 030
 
Payment OK 040 Payment Not Verified 050 Waiting for Payment 060 Waiting for Stock 070 Waiting 080
 
Shipped 090 Completed 100 Archived 110 Being Manufactured 120
 
NOTE: Order records are created by altering the TypeCode field of a cart, from "CART" to "ORDER".

Shipping

Free Shipping

The Free Shipping option allows the shipping calculation to return zero when the price of the order is Equal or Greater than the Free Shipping limted that is entered.  This free shipping limit is only active for the country list (CSV list) next to the free shipping limit field.

Range Shipping

The in-built range shipping calculation works by entering your settings and ranges into the BO>Shipping page.

An option of selecting the Product Model Weight or price is available, the range calculation will work on the selected value.

The country selection works on the country dropdown and the region dropdown from the cart.

The ref of the setting is the country code and the region code seperated by a colon.  (e.g.  FR:12  )  The country code must match the actaul code of the dropdown i.e. uppercase by default.

If you want to only use the country code then that is possible by only putting the country code into the ref field. (As shown below)

NOTE: The range values overlap.  The range will test >= the first range value and < the last range value.

Post Code Ranges

Ranges can also use post code string wild cards to select shipping costs.

The string entered by the client in the post Code field is checked against any CSV string the country code fields. The postcodes can be entered as full string or wildcard string.

Example:

"12100,32000" = matches if the pc enters matches exactly 12100 or 3200.

"12*,32*" = matches any PC string that starts with 12 or 32.

"*100,*000" = matches any PC string that ends with 100 or 000.

"121??,32?00" = matches any PV string the starts with 121 and have 2 following chars or matches any PC string the starts with 32 have any char in the 3rd position and ends with 00.

Country codes

List of countries codes taken fromt he DNN list Database (Note: region code are also taken from the DNN Database)

  • AD Andorra
  • AE United Arab Emirates
  • AF Afghanistan
  • AG Antigua and Barbuda
  • AI Anguilla
  • AL Albania
  • AM Armenia
  • AN Netherlands Antilles
  • AO Angola
  • AQ Antarctica
  • AR Argentina
  • AS American Samoa
  • AT Austria
  • AU Australia
  • AW Aruba
  • AZ Azerbaijan
  • BA Bosnia and Herzegovina
  • BB Barbados
  • BD Bangladesh
  • BE Belgium
  • BF Burkina Faso
  • BG Bulgaria
  • BH Bahrain
  • BI Burundi
  • BJ Benin
  • BM Bermuda
  • BN Brunei Darussalam
  • BO Bolivia
  • BR Brazil
  • BS Bahamas
  • BT Bhutan
  • BV Bouvet Island
  • BW Botswana
  • BY Belarus
  • BZ Belize
  • CA Canada
  • CC Cocos
  • CD Congo-Kinshasa
  • CF Central African Republic
  • CG Congo - Brazzaville
  • CH Switzerland
  • CI Ivory Coast
  • CK Cook Islands
  • CL Chile
  • CM Cameroon
  • CN China
  • CO Colombia
  • CR Costa Rica
  • CU Cuba
  • CV Cape Verde
  • CX Christmas Island
  • CY Cyprus
  • CZ Czech Republic
  • DE Germany
  • DJ Djibouti
  • DK Denmark
  • DM Dominica
  • DO Dominican Republic
  • DZ Algeria
  • EC Ecuador
  • EE Estonia
  • EG Egypt
  • EH Western Sahara
  • ER Eritrea
  • ES Spain
  • ET Ethiopia
  • FI Finland
  • FJ Fiji
  • FK Falkland Islands
  • FM Micronesia
  • FO Faroe Islands
  • FR France
  • GA Gabon
  • GB United Kingdom
  • GD Grenada
  • GE Georgia
  • GF French Guiana
  • GH Ghana
  • GI Gibraltar
  • GL Greenland
  • GM Gambia
  • GN Guinea
  • GP Guadeloupe
  • GQ Equatorial Guinea
  • GR Greece
  • GS S. Georgia and S. Sandwich Islands
  • GT Guatemala
  • GU Guam
  • GW Guinea-Bissau
  • GY Guyana
  • HK Hong Kong
  • HM Heard and McDonald Islands
  • HN Honduras
  • HR Croatia
  • HT Haiti
  • HU Hungary
  • ID Indonesia
  • IE Ireland
  • IL Israel
  • IN India
  • IO British Indian Ocean Territory
  • IQ Iraq
  • IR Iran
  • IS Iceland
  • IT Italy
  • JM Jamaica
  • JO Jordan
  • JP Japan
  • KE Kenya
  • KG Kyrgyzstan
  • KH Cambodia
  • KI Kiribati
  • KM Comoros
  • KN Saint Kitts and Nevis
  • KP North Korea
  • KR South Korea
  • KW Kuwait
  • KY Cayman Islands
  • KZ Kazakhstan
  • LA Laos
  • LB Lebanon
  • LC Saint Lucia
  • LI Liechtenstein
  • LK Sri Lanka
  • LR Liberia
  • LS Lesotho
  • LT Lithuania
  • LU Luxembourg
  • LV Latvia
  • LY Libya
  • MA Morocco
  • MC Monaco
  • MD Moldova
  • ME Montenegro
  • MG Madagascar
  • MH Marshall Islands
  • MK Macedonia
  • ML Mali
  • MM Myanmar
  • MN Mongolia
  • MO Macau
  • MP Northern Mariana Islands
  • MQ Martinique
  • MR Mauritania
  • MS Montserrat
  • MT Malta
  • MU Mauritius
  • MV Maldives
  • MW Malawi
  • MX Mexico
  • MY Malaysia
  • MZ Mozambique
  • NA Namibia
  • NC New Caledonia
  • NE Niger
  • NF Norfolk Island
  • NG Nigeria
  • NI Nicaragua
  • NL Netherlands
  • NO Norway
  • NP Nepal
  • NR Nauru
  • NU Niue
  • NZ New Zealand
  • OM Oman
  • PA Panama
  • PE Peru
  • PF French Polynesia
  • PG Papua New Guinea
  • PH Philippines
  • PK Pakistan
  • PL Poland
  • PM St. Pierre and Miquelon
  • PN Pitcairn
  • PR Puerto Rico
  • PT Portugal
  • PW Palau
  • PY Paraguay
  • QA Qatar
  • RE Reunion
  • RO Romania
  • RS Serbia
  • RU Russian Federation
  • RW Rwanda
  • SA Saudi Arabia
  • SB Solomon Islands
  • SC Seychelles
  • SD Sudan
  • SE Sweden
  • SG Singapore
  • SH St. Helena
  • SI Slovenia
  • SJ Svalbard and Jan Mayen Islands
  • SK Slovakia
  • SL Sierra Leone
  • SM San Marino
  • SN Senegal
  • SO Somalia
  • SR Suriname
  • ST Sao Tome and Principe
  • SU Soviet Union
  • SV El Salvador
  • SY Syria
  • SZ Swaziland
  • TC Turks and Caicos Islands
  • TD Chad
  • TF French Southern Territories
  • TG Togo
  • TH Thailand
  • TJ Tajikistan
  • TK Tokelau
  • TL Timor-Leste
  • TM Turkmenistan
  • TN Tunisia
  • TO Tonga
  • TP East Timor
  • TR Turkey
  • TT Trinidad and Tobago
  • TV Tuvalu
  • TW Taiwan
  • TZ Tanzania
  • UA Ukraine
  • UG Uganda
  • UM US Minor Outlying Islands
  • US United States
  • UY Uruguay
  • UZ Uzbekistan
  • VC Saint Vincent and The Grenadines
  • VE Venezuela
  • VG British Virgin Islands
  • VI US Virgin Islands
  • VN Viet Nam
  • VU Vanuatu
  • WF Wallis and Futuna Islands
  • WS Samoa
  • YE Yemen
  • YT Mayotte
  • YU Yugoslavia
  • ZA South Africa
  • ZM Zambia
  • ZR Zaire
  • ZW Zimbabwe

Cart & Account Structure