Tutorial Extension
1.0.0
SellerDeck Extensions - Tutorial Extension
|
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.
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.
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:
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:
Files in the current Site folder can be accessed using the prefix ../../site
. This would mainly be used to show images.
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 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".
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:
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.
The root folder contains 4 files described below.
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.
Any relevant information about the Extension.
Used for configuring external libraries into Vendor folder. This file should not be installed with the Extension.
Lists the external libraries used. This file should not be installed with the Extension.
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.
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.
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().
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 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 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.
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.
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.
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
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
.
The app\clases
folder contains Model classes (from MVC) specific for this Extension.
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.