Tutorial Extension  1.0.0
SellerDeck Extensions - Tutorial Extension
Tutorial Extension Index Page

Table of Contents

Introduction

This is the documentation for the SellerDeck Desktop Tutorial Extension.

All Extensions based on the SellerDeck PHP Extension Framework should follow the same structure as the Tutorial extension. It consists of four directories and a number of files - see the Files link above.

If debug files are used when creating the extension, e.g. .src.js files for JavaScript libraries, they should not be installed with the extension. The convention within SellerDeck is to create another top-level folder called debug with the files stored there using the same folder structure as below. The SellerDeck installer build process omits those files.

Extension Architecture

You should be familiar with the environment provided for Extensions within SellerDeck Desktop. That is covered in other documentation within the Extension Development Kit.

Extensions are free to provide their services within the constraints outlined in the other documentation. However, development of the first Extensions has shown that the best architecture is a statically-generated page with background Ajax requests for data.

The request for a page e.g. a dialog, or the page displayed in a tab, should complete quickly. This would normally be done by simply returning a page without any database queries or similar calculations being made during its generation. Then JavaScript operating in the page makes background requests to PHP modules to get appropriate data. While waiting for the request to finish, a waiting image can be shown.

This means that when showing the page in a dialog, the outline of the dialog appears quickly, with content appearing later. This gives the best user experience.

A page shown in a tab in the user interface may have multiple Ajax requests for different parts of the page; and may update them on a timer basis.

Note that PHP Session storage works but care has to be taken to ensure that the Session is cleared after handshaking so that if changing sites, information from the old site is not retained for the new site.

Browser compatibility

As Internet Explorer is used as the embedded browser, emulation mode has to be set so that it understands more recent CSS and HTML. All pages must have this line in the header:

<meta http-equiv="X-UA-Compatible" content="IE=10" />

Standard files

SellerDeck Desktop has a number of standard files in C:\Program Files (x86)\SellerDeck\SellerDeck 2016\Extensions\Sde\htdocs\assets.

The CSS must be used for dialogs.

As of SellerDeck Desktop 2016 (16.0.0), jQuery v1.11.2 is also installed centrally and can be linked to, avoiding the need to install a local copy with each extension.

A standard progress image is included.

The root of the standard files can be accessed from the app\public\ folder using the sequence ../../root. Therefore the standard header for a dialog might have:

<link href="../../root/assets/css/sde-dialog.css" rel="stylesheet" type="text/css" />
<script src="../../root/assets/js/jquery.min.js" type="text/javascript"></script>

Site files

Files in the current Site folder can be accessed using the prefix ../../site. This would mainly be used to show images.

Dialogs

Dialogs have a strict structure using styles defined in sde-dialog.css. For an example dialog see settings.php.

Group boxes are used to collect controls together.

The buttons for the bottom of the dialog must be in nested divs as per the example. The CSS for this creates a band across the bottom of the dialog for the buttons so they show regardless of the size of the dialog. Scrollbars are shown in the body of the dialog if needed. The IDs of the buttons are picked up automatically in the Desktop code and used to close the dialog.

The convention on buttons is to use a "Close" button if there is no significant storage of options from the dialog e.g. if just storing user preferences on UI elements (column sizes). The "Close" button has an ID of ButtonOK so that the C++ will close the dialog. If the dialog has a significant setting that affects operation of the Extension then there must be "OK" - ButtonOK, "Apply" - ButtonApply, and "Cancel" - ButtonCancel buttons which carry out the usual operations.

The convention with Extensions developed within SellerDeck is to add click handlers to the OK and Apply buttons. The handler makes an Ajax call, sending relevant data to a PHP module which saves the settings.

Help

Help is a special case of a dialog. The content of the Help page uses a div with id sde-help-content rather than sde-dialog-content. This gives a white background with margin rather than a dialog-coloured background. The buttons are the same. See for example help.html.

Help also should have a "Close" button rather than "OK".

Logging

There is a logging class in the Framework. See CLogger. This uses Monolog.

The default log location is prescribed by SellerDeck Desktop. For the tutorial and for Site1 it is:

C:\ProgramData\SellerDeck\SellerDeck 2016\Logs\Sites\Site1\sde\Tutorial 1.0.0

Normally log calls at level Info or Debug are suppressed. If the -extdebug command-line flag is passed to catalog.exe then Info and Debug level log calls are not suppressed.

Root Folder

The root folder contains 4 files described below.

Settings.ini

Contains the location of the Program Data folder for the extension. This is required for storing information before the handshaking process is complete. It also contains the build number of the extension, created by the installer.

[extension]
extension_program_data=C:\ProgramData\SellerDeck\Extensions\Tutorial 1.0.0\
revision=1

Readme

Any relevant information about the Extension.

Composer.phar

Used for configuring external libraries into Vendor folder. This file should not be installed with the Extension.

Composer.json

Lists the external libraries used. This file should not be installed with the Extension.

Vendor

The vendor directory contains 3rd party code installed by the Composer tool. If your extension needs to use such code please create a subdirectory and put the code here. The Tutorial extension uses some 3rd party libraries.

Note that these libraries are not included in this documentation.

Framework

The framework directory contains the code provided by SellerDeck. This implements functions like calling the API or connecting to the database.

The code is common to the different extensions. In the future the framework code may change as SellerDeck improves the code. It is highly advised not to modify framework code. If you need to implement your functionality then please extend framework classes and override the code you need. The inherited classes should go to the appropriate subfolder of the app folder.

Database

You are strongly advised to use the existing database access layer. This ensures that any queries work with both Access and SQL Server databases. For more information see the class CDataBase, particularly CDataBase::Select().

App

The app directory contains the extension specific code. Extension developers should implement and place their own code in this directory. The structure is based on the MVC (Model - View - Controller) architecture.

app_bootstrap.php

app_bootstrap.php contains code to load any essential application modules. The default file loads app_constants.php. See also bootstrap.php in the framework.

app_constants.php

app_constants.php contains any constants defined for the Extension. This includes the Extension version, and the minimum SellerDeck Desktop version required to run the Extension. These constants are used in the handshaking process.

Public folder

The app\public\ folder is where all the files that can be accessed in a browser instance in SellerDeck Desktop are stored. These are the Controllers in MVC.

The installer for the extension must set up a registry key DirectoryPath that contains the path to this folder. The registry key ConfigUri refers to the file handshaking.php in this folder. This is called by SellerDeck Desktop and uses the framework code to carry out the three-phase registration process.

Assets

Any files which are used by the Extension in the browser, e.g. images, javascript or css should be stored in app\public\assets. Create appropriate sub-folders e.g. app\public\assets\js, app\public\assets\css and app\public\assets\images.

As Help could have a number of pages, the convention has been to have app\public\help\assets as well. Additional help pages can go in \app\public\help, all images in \app\public\help\assets\iamges etc.

There may be debug (non-minified) JavaScript files used during development of the Extension. It is best that these be removed from the released Extension. A app\debug folder can be created and the files stored there. The SellerDeck build process doesn't include these files in the installer.

Views folder

The app\views folder contains views in the MVC architecture. They are loaded by a function called load_view. After initializing local variables it loads their content into a string variable by using output buffering. See: framework\classes\helper\Tools.php

Config folder

The app\config folder contains 3 configuration files handshake_response1.php, handshake_response2.php and handshake_response3.php which are used during the initial handshaking with SellerDeck Desktop.

These files control key elements for how an Extension is configured in SellerDeck Desktop. Some constants defined in app_constants.php are used in them. The structures correspond to the XML fields documented in SellerDeck 2016 Extensions.pdf.

Classes

The app\clases folder contains Model classes (from MVC) specific for this Extension.

Resources

The app\resources folder contains resource files that are generic to the extension. Currently it contains only an Images directory.

This directory may contain an extension.ico file. If your application shows a tab in SellerDeck this icon will be used if it is specified in the registry under IconPath. Your installer must install this file and create the appropriate registry setting.