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. 

After completing the installation, continue with the Open Store settings section. (below)

Installation actions

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_**.**.**_Install.zip"

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"

Security Roles

OpenStore has a number of standard user roles which are used for security.  It's important to create and use these roles.

• Administrators
• Manager
• Editor
• ClientEditor

Administrators: Standard DNN Administrator role, with right to do everything on the portal. 

Manager: This is the store manager role and has most rights to do things in OpenStore Administration Panel.

Editor: This role has rights to edit the products, categories, orders, etc.

ClientEditor: If assigned the user can enter the Administration Panel, but ONLY edit the products they have been assigned.

Pages and modules

Pages structure

Open Store pages :

List
Detail
Client Account
>Orders
>Addresses
>Favorites
>Profile
Cart
Checkout
Payment

Plus extra pages for the DNN integration :

• [CAT] page to integrate the catalog categories inside the DDR menu
• OpenStore Admin page to access the back office (See Below)

When creating the pages, make sure to give at least the Manager Role access to them

Settings

After creating the site structure with DNN. 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.

When evaluation all the settings keep the default fallback theme to "Default". The "ClassicAjax" should be used in the module settings of all the OpenStore modules.  This can be altered, but you need to make sure all templates are in your selected theme or in the default fallback theme.

(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.

Open Store modules

Hooks

Here are some examples on how you can use the available modules to build a webshop expierence that suits you.

1. Home page

2. Catalog page

3. Detail page

4. Cart

NOTE: In some Themes like "ClassicAjax" the API call for the cart and checkout list is make from the "MiniCart" template.  So you need to add the MiniCart module to the cart and checkout pages to make it work.

5. Client account

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

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>

DDR 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 NBrightBuy node manipulator is used on the DDRMenu control, this page will be replaced with the Open Store 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>

Sub-category Injection

You can create a subsection of categories that get injected into the DDRMenu.  This allows multiple subsections to be injected.

The is done by creating a page in the DNN pages called [CAT:categoryref].  The Category that has been selected by using the categoryref will display all sub-categories that are visible, but the category itself will not be displayed.  It may therefore require an extra level of category to be created to get the desired effect.

Page structure

[CAT] display

[CAT:grorgdtc] display

Themes and templates

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 ClassicAjax 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 at System level :

/DesktopModules/NBright/NBrightBuy/Themes/ClassicAjax

Theme Folder Structure

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 ClassicAjax "MiniCart.cshtml" template I would create a folder and file on the portal at :

/Portal/0/Themes/ClassicAjax/default/MiniCart.cshtml

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

/Portal/0/Themes/ClassicAjax/fr-FR/MiniCart.cshtml

If you want to create a new Theme, then at System level you can create :

/DesktopModules/NBright/NBrightBuy/Themes/MyNewTheme/Default/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 Open Store default "ClassicAjax".

Note : You could also create the "MyNewTheme" at Portal level.

Default templates

As you know, the default theme is splitted in 2 folders so you can easily customize your store.

By default the ClassicAjax theme is selected in every modules settings of Open Store. If the module required files that are not found in the ClassicAjax folder it will fallback to the Default folder.

/Themes/ClassicAjax contains :

• Category menu (treeview) and filters templates
• Product list and detail templates
• Featured products templates
• Mini cart template
• Search templates

/Themes/Default contains :

• Cart templates
• Client account templates
• 404 page (“Product not found”)

See below the list of templates that you can find inside each folder, and their use.

1. ClassicAjax

2. Default

Bespoke Fields

Extra fields can be added to the clients,  product and to product models.

Using the templates "clientfields.cshtml", "productfields.cshtml" and "modelfields.cshtml".  Bespoke field can be created by using these template.

Example: productfields.cshtml

@inherits NBrightBuy.render.NBrightBuyRazorTokens<NBrightDNN.NBrightRazor>
@using NBrightDNN

@{
    var info = (NBrightInfo)Model.List.First();
}

<div class="col-sm-3">
    <label class="control-label">Code couleur</label>
     @TextBox(info, "genxml/textbox/txtcolorcode", "class='form-control input-sm' ")
</div>

<div class="clearfix"></div>

Example: modelfields.cshtml

@inherits NBrightBuy.render.NBrightBuyRazorTokens<NBrightDNN.NBrightRazor>
@using NBrightDNN

    @{
        var info = (NBrightInfo)Model.List.First();
        var lp = info.GetXmlProperty("genxml/lp"); // we need to use the index of each model for the unique field name.
    }
    <div class="col-sm-2">
        <label class="control-label">TEST</label>
        @TextBox(info, "genxml/textbox/test_" + lp, "class='form-control input-sm' ")
    </div>

    <div>
        @CkEditor(info, "genxml/textbox/modeldescription_" + lp, "class='form-control' height='400' width='100%' datatype='html' ")

    </div>

Note : It is best to put bespoke field templates at portal level, otherwise on upgrade they will be overwritten.

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 OpenStore 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.

OS_DisplaySearch

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

In the settings of the module you NEED to specify which OS_ProductView module the filter criteria is designated for, you use the module ref of the OS_ProductView 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”.

OS_ProductView

This module displays the products selected, using the criteria specified in the temporary file created by OS_DisplaySearch.  OS_ProductView 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 OS_ProductView 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.  (See Search.cshtml template as an example)

Search Documentation

Adv Search Template Example

Filtering Products

The module “OS_ProductFilter” is used to add filter functionality to a product list.

The product filters use ajax to deal with the filter selection. The settings of the filter module allow you to select the behaviour and the properties that are to be used are filters. The properties that are applied to products will be used as the filters.

Filters ByProduct

Linking the filters to display only the filters that exist on the product list. This is done by specifying a Module Ref in the “Link Product Module Ref.” field. This will link the filter modules to the product list. Once linked only the property filters that exist on the initial product list are displayed in the filter list. Because we may have different property filters on each category, the initial select must be activated by a category select from the “OS_CategoryMenu” module. This should NOT use the Ajax option for this functionality. Although it will work, the results that you get may be confusing for the client, because the filters will not reset and the product list will not reflect the correct filter selection. NOTE: If you want to use the Ajax category select with the filter ByProduct functionality, then you need to create some JS in the load of the product list that will clear the filters.

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

404

The "Activate 404" setting in AP>Admin>Settings activates a 404 response when a product id the url is not found.

On some systems turning this on will be enough to make the 404 return and the "no product message appear".
However on most live systems a standard IIS 404 will be returned.  For this reason it is advised to create a bespoke 404 for the website and make your DNN install use that.
This can be done through the "IIS>Site>Error Pages", rememebr to turn on custom error pages, in "Edit Feature setting"

If you have multiple portals on the DNN install the custom 404 method will not work, so you can opted to turn off the 404.  This will cause a normal "Product not found" message to be displayed, but no 404 response. Or you can choose to use a generic 404 for all portals.