Directory
The Directory Web Service creates a gateway through which XStandard is able to browse third-party data stores, then insert the data into the editor at the current cursor position.
Requirements
- ASP / ASP.NET on Windows
- PHP 4.3.0+ on Linux / FreeBSD / Windows
ASP Installation
- Run the setup program called x-web-services-asp.exe Instructions for downloading this program are sent to you when you request download instructions for XStandard Pro.
- Set "Read & Execute" file permissions on C:\Program Files\XStandard Web Services to Everyone.
- Copy directory.asp, directory.config, directory_example_staff.csv, directory-example-product-1.txt, directory-example-product-2.txt, directory-example-product-3.txt, directory-example-product-4.txt, directory-xhtml-entities.xml, directory-xhtml-latin1.xml, directory-xhtml-special.xml and directory-xhtml-symbol.xml to C:\InetPub\wwwroot (or another path that has an IIS virtual directory mapping) and set "Read & Write" file permissions on this folder to Everyone.
ASP.NET Installation
- Unzip the file called x-web-services-aspx.zip Instructions for downloading this file are sent to you when you request download instructions for XStandard Pro.
- Copy directory.aspx, directory.config, directory_example_staff.csv, directory-example-product-1.txt, directory-example-product-2.txt, directory-example-product-3.txt, directory-example-product-4.txt, directory-xhtml-entities.xml, directory-xhtml-latin1.xml, directory-xhtml-special.xml and directory-xhtml-symbol.xml to C:\InetPub\wwwroot (or another path that has an IIS virtual directory mapping) and set "Read & Write" file permissions on this folder to Everyone. Into a sub-folder, copy the bin folder.
PHP Installation
- Unzip the file called x-web-services-php.zip Instructions for downloading this file are sent to you when you request download instructions for XStandard Pro.
- Copy directory.php, directory.config, directory_example_staff.csv, directory-example-product-1.txt, directory-example-product-2.txt, directory-example-product-3.txt, directory-example-product-4.txt, directory-xhtml-entities.xml, directory-xhtml-latin1.xml, directory-xhtml-special.xml and directory-xhtml-symbol.xml to a folder on your Web site. Make sure this folder has the broadest possible permission settings. On Unix-based systems, set permissions to
0777.
Testing
In a Web browser, navigate to the URL where the Directory service is located. For example: http://localhost/directory.asp
If you don't see Status: Ready in the browser, the Web Service is not correctly installed. The most common cause of this is incorrectly set file permissions.
To set up XStandard to use the Directory service, modify the following <param> tag:
Property DirectoryURL
(Available in XStandard Pro)
Absolute URL to a Directory Web Service. Multiple URLs can be specified, separated by a space character. For testing purposes, the following URL is available: http://soap.xstandard.com/directory.aspx
Below is a diagram illustrating how XStandard retrieves data from remote data stores using the Directory Web Service.
A user presses the Directory button on the editor's toolbar (Step 1) which brings up a dialog box (Item B). The dialog box communicates (Step 2) via HTTP with the Directory Web Service (Item C). The Web Service communicates (Step 3) with data stores (Item D) and retrieves data (Step 4). The Web Service reformats the data and sends it back to the dialog box (Step 5), populating the list box with the retrieved data. When the user selects an item from the list box, the data is inserted at the current cursor position (Step 6).
The Directory Web Service can organize data stores in a hierarchy (tree structure), permitting users to browse the data stores like folders on the file system. In the illustration below, selecting a data store displays a list of code snippets to the user.
The hierarchy of data stores and the XHTML for each snippet are constructed through a configuration file. Below is a screenshot of a sample configuration file. The file is an XML file containing a number of scripts written in VBScript or JavaScript (for the ASP version), in C# or Visual Basic .NET (for the ASP.NET version) or in PHP script (for the PHP version). With one exception, each script is identified by a unique ID. The script without an ID is called only when the user opens the Directory dialog box for the first time. In the screenshot above, this script has created 3 folders and associated an ID with each folder. When a folder is selected, the script with the corresponding folder ID is called. Thus, in our example, when the user selects the folder "Staff" the script with the ID "a" is executed. This script retrieves a list of employees and creates an XHTML snippet for each employee.
Customization For ASP Version
The script engine has a root object called "Directory". This object is global and does not need to be instantiated. It is used to create folders and code snippets. Below is the API reference for the Directory object.
Sub AddContainer(sName As String, sID As String, [sMetadata As String], [sLocation As String], [sIcon As String])
Create a folder. sName is the name of the folder. sID is the ID associated with the folder. sMetadata is additional data. sLocation is a URL to an alternate Directory Web Service and can be absolute or relative.
Sub AddObject(sName As String, sValue As String, [sIcon As String])
Create a code snippet.
Property CurrentFolder As String
Path to the folder containing the configuration file.
Property ID As String
(read-only)
ID of the script currently being executed.
Property Lang As String
(read-only)
Language code transmitted in the request.
Sub LogToFile(sText As String)
Write message to log file.
Property Metadata As String
(read-only)
Additional data.
Function ReadFromFile(sPath As String) As String
Read contents of a file.
Function URLEncode(sText As String) As String
Escape characters for use in URLs.
Function XHTMLEscape(sText As String) As String
XHTML escape markup. For example, change < to < and & to &
Customization For ASP.NET Version
The script engine has a root object called "XStandard.Directory". This object is global and does not need to be instantiated. It is used to create folders and code snippets. Below is the API reference for the XStandard.Directory object.
public void AddContainer(string name, string id, string metadata, string location, string icon)
Create a folder. name is the name of the folder. id is the ID associated with the folder. metadata is additional data. location is a URL to an alternate Directory Web Service and can be absolute or relative.
public void AddContainer(string name, string id, string metadata, string location)
Create a folder.
public void AddContainer(string name, string id, string metadata)
Create a folder.
public void AddContainer(string name, string id)
Create a folder.
public void AddObject(string name, string data, string icon)
Create a code snippet.
public void AddObject(string name, string data)
Create a code snippet.
public string CurrentFolder
Path to the folder containing the configuration file.
public string ID
(read-only)
ID of the script currently being executed.
public string Lang
(read-only)
Language code transmitted in the request.
public void LogToFile(string message)
Write message to log file.
public string Metadata
(read-only)
Additional data.
public string ReadFromFile(string path)
Read contents of a file.
public string URLEncode(string text)
Escape characters for use in URLs.
public string XHTMLEscape(string text)
XHTML escape markup. For example, change < to < and & to &
Customization For PHP Version
The script engine can access a class stored in a $directory variable. This variable is already initialized. The object it contains is used to create folders and code snippets. Below is the API reference for this class.
function add_container($name, $id, $metadata = "", $location = "", $icon = "")
Create a folder. $name is the name of the folder. $id is the ID associated with the folder. $metadata is additional data. $location is a URL to an alternate Directory Web Service and can be absolute or relative.
function add_object($name, $value, $icon = "")
Create a code snippet.
function current_folder()
Path to the folder containing the configuration file.
var id
(read-only)
ID of the script currently being executed.
function log_to_file($msg)
Write message to log file.
var metadata
(read-only)
Additional data.
function read_from_file($path)
Read contents of a file.
function xhtml_escape($text)
XHTML escape markup. For example, change < to < and & to &