BT eTrading Intranet Site

snortfearΔιακομιστές

4 Δεκ 2013 (πριν από 3 χρόνια και 4 μήνες)

59 εμφανίσεις

BT eTrading Intranet Sit
e

Administrator Documentation

Ben Johnson, British Telecommunications plc 2002

BT eTrading Intranet Site
-

Administrator Documentation


Page
2

1

Executive Overview

The BT eTrading site


which aims to promote information sharing within the e
-
Commerce
(formerly “EDI”) team, as well as providing an efficient means of communication with
current

and potential customers


is driven by a powerful, extensible Content Management
System (CMS) named
Content Delivery XML System

(‘
cdXP
’).

Benefits offered by cdXP over alternative approaches (e.g., MS FrontPage) include:


Central management of appearance a
nd function of all site content.

→ Easily change the look and feel of the site in one step



Personnel contact information updated automatically at display time using data from
BT TeamConnect Directory

→ Eliminates outdated contact details, the # 1 web ma
intenance headache



Maintain site content by visiting a page using a standard web browser and clicking an

Edit
’ link, instead of requiring physical access to server

→ Intuitive, minimal hassle content maintenance

→ Create advanced cross
-
browser content
without web development skills

→ No need for editors to understand the physical web server configuration


BT eTrading Intranet Site
-

Administrator Documentation


Page
3

Contents

1

EXECUTIVE OVERVIEW

................................
................................
................................
............................

2

2

IN
TRODUCTION & SCOPE

................................
................................
................................
.........................

4

3

ARCHITECTURE OVERVIE
W

................................
................................
................................
...................

5

3.1)

BT

E
T
RADING
F
RAMES
I
NTERFACE

................................
................................
................................
............

5

3.2)

C
ONTENT
D
ELIVERY
XML

P
LATFORM
(
CD
XP)

................................
................................
.........................

5

4

CDXP COMPONENTS (
/CDXP/ )
................................
................................
................................
..............

6

4.1)

CDXP
.
ASP

(

/
CDXP
/

)

................................
................................
................................
................................
...

6

4.2)

CDXP
_
GETXML
.
ASP

(

/
CDXP
/

)

................................
................................
................................
...................

6

4.3)

CDXPEDIT
.
ASP

(

/
CDXP
/
SECURE
/

)

................................
................................
................................
............

7

4.4)

CDXP
_
TRANSFORM
X
ML
D
OC
_
INC
.
ASP

(

/
CDXP
/
INCLUDES
/

)

................................
................................
.......

7

4.5)

CDXP
_
PERSON
.
ASP

(

/
CDXP
/
INCLUDES
/

)

................................
................................
................................
..

7

4.6)

CDXP
_
INC
.
ASP

(

/
CDXP
/
INCLUDES
/

)

................................
................................
................................
.........

7

4.7)

CDXP
_
PARAMS
.
XML

(

/
CDXP
/

)

................................
................................
................................
..................

7

4.8)

GLOBAL
.
ASA

(

/
CDXP
/

)

................................
................................
................................
..............................

7

5

ETRADING COMPONENTS


( /CDXP/ET/ )

................................
................................
............................

8

5.1)

XML

D
ATA
F
ILES
(

/
CDXP
/
ET
/
XML
/*.
XML
)

................................
................................
..............................

8

5.2)

K
EY
XSL

T
RANSFORMATION
F
ILTERS

(

/
CDXP
/
ET
/
XSL
/*.
XSL
)

................................
..............................

8

5.3)

C
ASCADING
S
TYLE
S
HEETS

(

/
CDXP
/
ET
/
CSS
/*.
CSS
)

................................
................................
...............

9

5.4)

R
OOT
S
TATIC
HTML

F
ILES

(

/
CDXP
/
ET
/*.
HTM
)

................................
................................
......................

9

6

COMMON PROCEDURES

................................
................................
................................
.........................

10

6.1)

E
DITING
A
N
E
XISTING
P
AGE

................................
................................
................................
.....................

10

6.2)

U
SING
C
USTOM
T
AGS IN CD
XP

P
AGES

................................
................................
................................
.....

10

6.3)

C
REATING
A

N
EW
P
AGE

................................
................................
................................
............................

12

6.4)

M
ODIFYING
S
ITE
N
AVIGATION
S
TRUCTURE

................................
................................
.............................

12

7

CUSTOMISATION OPTION
S

................................
................................
................................
....................

13

7.1)

C
HANGING
H
OW
C
ONTENT
P
AGES
A
RE
D
ISPLAYED

................................
................................
................

13

7.2)

A
DDING
C
USTOM
C
ONTENT
M
ARK
-
UP
T
AGS

................................
................................
...........................

14

7.3)

A
DDING
A
DDITIONAL
P
ROCESSING
F
ILTERS TO THE
C
HAIN

................................
................................
....

15

8

KNOWN ISSUES

................................
................................
................................
................................
............

16

8.1)

F
ULL
F
ILENAME
M
UST
B
E
S
PECIFIED
W
HE
N
S
AVING
P
AGES
F
ROM CD
XP

E
DIT

................................
...

16

8.2)

E
T
RADING
E
DITORS
M
AY
W
RITE TO
A
NY
W
ELL
-
F
ORMED
F
ILE ON
W
EBSITE

................................
.......

16

8.3)

U
SER
C
ONTEXT
M
UST
B
E
S
PECIFI
ED
W
HEN
E
NTERING
U
SERNAME
D
URING
CD
XP

E
DIT

[..]

...............

16

8.4)

N
AVIGATION
B
AR
N
OT
D
YNAMIC
I
N
N
ETSCAPE
4.75

A
ND
E
ARLIER

................................
......................

17

8.5)

C
ONTENT
P
AGE
C
AC
HING
N
OT
I
MPLEMENTED

................................
................................
........................

17

8.6)

‘T
OP
.
HTM


M
AY
R
ENDER
I
NCORRECTLY IN
S
OME
B
ROWSERS

................................
...............................

17

9

APPENDICES

................................
................................
................................
................................
.................

18

9.1)

S
ERVER
C
ONFIGURATION
N
OTES

................................
................................
................................
..............

18

9.2)

CD
XP

F
OLDER
S
TRUCTURE

................................
................................
................................
......................

18

9.3)

BT

E
T
RADING
F
OLDER
S
TRUCTURE

................................
................................
................................
.........

19

9.4)

E
T
RADING
C
ONTENT
P
AGE
XML

D
ATA
F
ILES

................................
................................
.........................

19

9.5)

D
EFAULT
BT

E
T
RADING
S
ITE
URL

................................
................................
................................
..........

19

BT eTrading Intranet Site
-

Administrator Documentation


Page
4

2

Introduction & Scope

This document p
rovides information intended to assist Administrators for the BT eTrading
intranet site to understand how the site operates and how to perform tasks such managing
content, customising the site interface and changing the presentation of content pages.
1

When

documenting basic administrative tasks such as updating page content, no prior
specialist webmaster/web development knowledge is assumed. However, documentation
for more advanced customisation and configuration procedures assumes familiarity with
working
with the Microsoft IIS server platform and, in some cases, web development
technologies such as HTML, CSS, ASP, XML and XSL.

Section
3
, “
Architecture Overview
”, gives an overview of the technological architect
ure of
the site. Sections
4
, “
cdXP Components
”, and
5
, ”
eTrading Components
”, describe the
purpose, usage and location on the server of key components of the cdXP

application and
the eTrading site content respectively.

Section
6
, “
Common Procedures
”, describes key usage scenarios for day
-
to
-
day
administration of the site content. Section
7
, “
Customisation Options
”, describes more
advanced customisation procedures, such as adding new mark
-
up tags and changing the
look and feel of the site.

Section
8
, “
Known Issues
”, discusses important outstanding issues concerning security
and ease of use in the current implementation of cdXP, particularly with regards to content
editing functionality (“cdXP Edit”). This should be treated as a list of priority work areas for
deve
lopers wishing to improve the system.

Finally, Section
9
, “
Appendices
”, contains technical specifications for the cdXP system and
the eTrading site. These items are generally referenced elsewhere in this docum
ent and
include server configuration notes (including permissions, virtual folders and the default
URL for accessing the BT eTrading site).




1

This document does not cover cdXP functionality not exploited by the current BT eTrading site. For example, cdXP offers the
potential for page data to be stored in a database (e.g., SQL Server) instead of in static XML files; since this approach is
not

used
on the eTrading site, it is not covered in this document.

BT eTrading Intranet Site
-

Administrator Documentation


Page
5

3

Architecture Overview

3.1)
BT eTrading Frames Interface

The BT eTrading site uses frames to avoid the need to redisplay s
tatic elements such as
the navigation bar each time the visitor changes page, increasing navigation speed.
2

Only
the upper frame of the eTrading site contains a static HTML file (‘
top.htm
’); the left
-
hand
navigation frame and the right
-
hand content page fr
ame both contain content dynamically
generated by the
Content Delivery XML Platform

ASP application (‘
cdxp.asp
’), which is
described below.

The navigation frame contents are generated via cdXP rather than using a static DHTML
file to allow minimum effort m
odifications to the navigation structure of the site. See section
6.4
, “
Modifying Site Navigation Structure
”, for further discussion. Clicking links in the
navigation frame loads the new page in

the content frame if it is a local URL, or in a new
window if it is an external website.

3.2)
Content Delivery XML Platform (cdXP)

All content pages on the eTrading site are generated by the ASP application ‘
cdxp.asp
’. If
each page had been written as a static

HTML file
-

mixing page information with
presentation code
-

changes to the look and feel of the site would have required time
consuming manual changes to each HTML file, or to a series of files if each page was
targeted at multiple clients. cdXP avoids t
his problem by storing page information as
structured data (XML) separate from presentation rules.

When a content page is requested (by calling ‘
cdxp.asp
’ with an article ID parameter),

cdxp_getxml.asp
’ is called to obtain the page data corresponding to t
he article ID. A series
of transformations is then applied to the data to produce the final displayable code (e.g.,
HTML) that is sent to the client (typically a desktop PC browser). Specifically, a series of
XSL filters is applied to the data (eXtensible
Stylesheet Language is the industry standard
pattern
-
based scripting language for manipulating XML data).

The sequence of XSL transformations applied to the page data is controlled by

cdxp_transformXmlDoc_inc.asp
’. XSL filters are modular, self
-
contained
components,
meaning they can be re
-
used across sites and projects. One powerful example utilised on
the eTrading site is ‘
person_[xml].xsl
’, which searches for occurrences of ‘person’
elements in the page data and adds relevant information drawn from the B
T Directory
employee database. See section
7.1
, “
Changing How Content Pages Are Displayed
”.




2

A frames interface is NOT a requirement of the cdXP system, rather it is a design decision for the eTrading site. The navigat
ion
device and other static elements could easily be included on
each individual page instead, by modifying the display logic for
eTrading pages (see section
7.1
, “
Changing How Content Pages Are Displayed
”).

BT eTrading Intranet Site
-

Administrator Documentation


Page
6

4

cdXP Components

( /cdxp/ )

The following is a description of each of the main components of the cdXP

system. All
components are fully documented internally with line
-
by
-
line comments and function
descriptions; the descriptions given here are intended to give an overview. Note that the
path of the component on the server (relative to the web root) is give
n in brackets next to
each component name.

4.1)
cdxp.asp

( /cdxp/ )

Main cdXP ASP module; all cdXP content is accessed via ‘cdxp.asp’. Sends displayable
mark
-
up (e.g. HTML) to the client (e.g. Internet Explorer), corresponding to the requested
article ID (‘
a
id
’ parameter). The following example URL would cause the page
corresponding to the article ID “et_page1” to be displayed in the client:

http://147.147.7.164/cdxp/cdxp.asp?aid=et_page1


A ‘mode’ parameter may also be used to invoke a display mode other tha
n the default
‘view’ mode, e.g.:

http://147.147.7.164/cdxp/cdxp.asp?aid=et_page1&mode=edit


The exact effect of ‘mode’ parameter is determined by ‘
cdxp_transformXmlDoc_inc.asp
’.
The following values may be used:


VIEW

(Default) Presents article as a standar
d eTrading page, applying standard layout,
styling, functionality, etc.
3


EDIT

Displays an HTML form allowing key page information to be edited then the changes
saved directly back to the server (see section
6.1
, “
Editing an existing page via an
HTML form in a browser
”).
4


XML

Raw page data is displayed as XML. Contents of the XML file corresponding to the
specified article ID is displayed directly in the browser, without any transformations
being
applied.


4.2)
cdxp_getxml.asp

( /cdxp/ )

Responsible for obtaining the page data corresponding to the specified Article ID and
returning it as an XML string.
5

By default (as mentioned, cdXP can easily be configured to
obtain page information from a database
instead) this is done by obtaining the server path
of an XML file corresponding to the AID, then returning the XML contents of this file.




3

The exact chain of transformations applied to the

article data is determined by ‘
cdxp_transformXmlDoc_inc.asp
’, but this mode
normally means the final display transformation is performed using ‘
et_article_[html
-
css
-
js].xsl
’.

4

Normally this mode means the article is transformed for display using ‘
cdxpedi
t,xsl
’.

5

For complete modularity, ‘
cdxp_getxml.asp
’ operates as a totally separate ASP application from the main ‘
cdxp.asp
‘ application.
It receives the desired article ID as a GET parameter and outputs the corresponding XML string via the ASP Response ob
ject.

cdxp.asp
‘ uses the XMLHTTP protocol to call ‘cdxp_getxml.asp’ and capture the output.

BT eTrading Intranet Site
-

Administrator Documentation


Page
7

The path of this file is obtained by passing an AID to the ‘
GetXmlFilePath()
’ function. Article
IDs (e.g., “et_page1”)

consist of a project identifier (“et” = eTrading) followed by an
underscore character (“_”), then a unique page identifier (“page1”). The project identifier
determines where ‘
GetXmlFilePath()
’ looks to find the corresponding XML file.
6

4.3)
cdxpedit.asp

( /c
dxp/secure/ )

Accepts an Article ID corresponding to an XML file on the server and an encoded list of
changes to make to that file. The specified file is loaded, the changes are applied, then the
updated version is saved directly back to the server.
7

4.4)
cdxp_
transformXmlDoc_inc.asp

( /cdxp/includes/ )

Includes the function ‘
TransformXmlDoc()
’, which takes an XML Document (an ‘XML
DOMDoc’ object) and a ‘mode’ string (specifying the delivery mode, i.e., ‘view’, ‘xml’ or
‘edit’) as parameters and applies a seri
es of XSL transformations to the XML object.

The sequence of transformations is chosen based on the name of the root node of the
XML Document and on the value of the ‘mode’ parameter. For example, passing an XML
Document where the root node is ‘article’ al
ong with a ‘mode’ value of ‘view’ causes the
XML Document to be transformed into HTML code that presents the page information as a
standard eTrading page.


TransformXmlDoc()
’ sends no output to the client, it only transforms the page data ready
for display
. For information on controlling the transformation logic, see section
7.1
,

Changing How Content Pages Are Displayed
”.

4.5)
cdxp_person.asp

( /cdxp/includes/ )

Packages the TeamConnect Directory l
ook
-
up functionality employed in the

person_[xml].xsl
’ XSL filter into a number of normal ASP functions. By including a
reference to the ‘
cdxp_person.asp
’ module, other ASP pages can access data from BT
Directory by passing a Boat ID to the ‘
BtPerson()
’ f
unction.

4.6)
cdxp_inc.asp

( /cdxp/includes/ )

Contains ASP library routines for use in ‘
cdxp.asp
’ and ‘
cdxp_getxml.asp
’. See in
-
line
documentation for detailed descriptions of individual functions.

4.7)
cdxp_params.xml

( /cdxp/ )

Contains parameters controlling

the operation of cdXP, formatted as an XML document
with the root node ‘_cdxpParams’. See in
-
line documentation for descriptions of allowable
parameters. Currently, the main parameter employed is ‘dirDataPaths’, which defines the
location of information w
ithin the XML returned by TeamConnect Directory.

4.8)
global.asa

( /cdxp/ )

Loads the contents of the above ‘
cdxp_params.xml
’ file into a global XML Document object

the first time the cdXP application is accessed. This improves the speed of accessing
global c
dXP parameters.




6

Under the eTrading site’s default configuration, content data files are held in the ‘
\
cdxp
\
et
\
xml
\
’ folder.

7

The HTML form generated by the cdXP Edit XSL filter


cdxpedit_[html
-
css
-
js].xsl
’ posts this required information to ‘
cdxpedit.asp

when the user submits the form. Changes are expressed as a series of POST name
-
value pairs, where the name is an encoded
version of the XML node to be modified and the value is

the new value to use.

BT eTrading Intranet Site
-

Administrator Documentation


Page
8

5

eTrading Components

( /cdxp/et/ )

5.1)
XML Data Files
( /cdxp/et/xml/*.xml )

Two types of XML data file are utilised by default on the eTrading site, i.e., two XML
schemas exist:

nav

XML Documents with a ‘nav’ root node contain a representat
ion of the navigation structure
for the site, intended for transformation into a navigation device of some sort. ‘
et_nav.xml

is the only XML file on the eTrading site to use this schema and by default it is displayed as
the navy blue navigation bar in the

left hand frame of the eTrading site. See section
6.4
,

Modifying Site Navigation Structure
” for details of working with ‘nav’ XML documents in
order to add new site sections, etc.

article

XML
Documents with an ‘article’ root node (most eTrading XML data files) contain page
information (such as title, author, review date, etc.) intended for transformation into a
normal content page (blue background, white text, yellow headings, by default). Exam
ples
of ‘article’ XML documents include ‘
et_default.xml
’ and ‘
et_pch.xml
’, which correspond to
the eT homepage and the “Potential Customer Home” content page, respectively.
8

Viewing these files will aid understanding their function.

5.2)
Key XSL Transformation
Filters

( /cdxp/et/xsl/*.xsl )

File naming for eTrading XSL transformation filters follows the convention that the type of
output produced by the filter is included in square brackets at the end of the filename. For
example, ‘
person_[xml].xsl
’ outputs XM
L, while ‘
article_[html
-
css
-
js].xsl
’ outputs HTML
(with CSS and JavaScript).

et_nav_[html
-
css
-
js].xsl

Transforms ‘nav’ XML documents (which contain a representation of the navigation
structure of the site) into a DHTML navigation device for display in the
left hand frame of
the eTrading site. Under IE5+, sub
-
links are hidden until a section is visited, reducing
clutter and promoting drill
-
down access to information.

et_article_[html
-
css
-
js].xsl

Transforms ‘article’ XML documents into standard HTML eTrading
content pages. A
uniform look
-
and
-
feel is applied across all pages, including centrally
-
controlled colour
schemes and HTML element styling (see section
5.3
, “
Cascading Style Sheets
”) and
generat
ion of a cross
-
browser DHTML pop
-
up containing contact information when the
mouse is moved over the name of a BT employee (see ‘
person_[xml].xsl
’ below).

person_[xml].xsl

Searches for occurrences of ‘person’ elements in the XML document
-

each containing t
he
name of a BT employee
-

and inserts additional information from BT Directory about the
employee.
9

Contact details are simply stored as parameters on the ‘person’ element; it is
up to later filters to make use of the information (see ‘
et_article_[html
-
cs
s
-
js].xsl
’ above).




8

A full list of the default XML data files and their purpose is given in Appendix
9.4
, “
eTrading Content Page XML Data Files
”.

9

If a ‘
boatId
’/‘
dirId
’ parameter (BT Boat ID / Directory ID) is

included on the ‘
person
’ element, the employee’s details are retrieved
directly. Otherwise, basic search logic is used to try to guess the identity of the employee.

BT eTrading Intranet Site
-

Administrator Documentation


Page
9

node
-
copy_[xml].xsl

Searches for occurrences of ‘copy’ elements in the XML document, and processes each
appropriately (see description of ‘copy’ elements in section
6.2
, “
Using Custom Tags

in
cdXP Pages
”).

cdxpedit_[html
-
css
-
js].xsl

Transforms ‘article’ XML documents into an HTML form (‘
cdXP Edit
’) that allows the user
to modify the page information using their browser. When the form is submitted, the
changes made and the Article ID of the

document being edited are submitted to

cdxpedit.asp
’, which does the actual work of implementing changes. See sections
4.3
,

cdxpedit.asp
” and
6.1
, “
Editing An Existing Page
”, for further information about cdXP Edit.

5.3)
Cascading Style Sheets

( /cdxp/et/css/*.css )

A collection of CSS files providing a high level of presentation control over all pages on the
eTrading site (‘
et.css
’) a
nd over groups of pages such as content pages (‘
et_articles.css
’),
the navigation frame (‘
nav.css
’) and the top frame (‘
top.css
’). CSS is supported to varying
degrees by most version 4.0 browsers; other clients will still be able to view content, but
witho
ut styling applied to page elements.

5.4)
Root Static HTML Files

( /cdxp/et/*.htm )

Consists of ‘
default.htm
’, which is creates the HTML frameset for the site and is the first file
accessed by visitors to the eTrading site, and ‘
top.htm
’ which is displayed in

the upper
frame of the site frameset .

BT eTrading Intranet Site
-

Administrator Documentation


Page
10

6

Common Procedures

6.1)
Editing An Existing Page

Editing an existing page via an HTML form in a browser (cdXP Edit)

cdXP Edit allows an authorised user to make changes to content page information with
minimum effort, using

just a standard browser. All content pages on the eTrading site
include at the bottom of the page a number of links to different cdXP views on the current
page. Selecting “cdXP Edit” causes a cdXP Edit form to be displayed, populated with
current page inf
ormation.

The user can modify any displayed data item, then click “Save” at the foot of the page
(currently the full page filename must be specified; see known issues, Section
8.1
). They
will then be presented with a Basic Authenticat
ion dialog asking them to provide a valid
Windows NT username and password. If they are authenticated as a valid user and have
been granted permission to edit eTrading site pages, changes will be saved.

In order to grant a user permission to edit eTrading
site pages, they must be given NT
permission to access the ‘
/cdxp/secure/
’ folder, which contains the ‘
cdxpedit.asp
’ file. One
way of doing this would be to create an NT group named “eTrading Editors” and assign
read permission for this group to the ‘
/cdxp
/secure/
’ folder. Users could then be given
eTrading editing permission by adding their name to the “eTrading Editors” group.

The body field of the cdXP Edit form can contain standard HTML tags (e.g., ‘
<B>
’), but
authors should restrict their use of HTML t
o classification tags rather than presentation
tags such as ‘
<FONT>
’ to maintain style consistency with other pages. A range of custom
cdXP tags are also available to authors; these tags provide shortcuts and extended
functionality, without sacrificing bro
wser compatibility since they are converted into HTML
by cdXP before the page is displayed.
10

Editing an existing page directly as a text file on the server

Alternatively, page information can be edited directly on the server using any text editor. By
ident
ifying the XML data file corresponding to the page requiring modification, any aspect
of the page information may be modified directly as plain ASCII text. Note that some page
information (such as some header elements) cannot by default be modified using c
dXP
Edit, so direct text editing is the only way to change the information.

By default, the XML file corresponding to the page to be edited will be located in the

/cdxp/et/
xml
’ directory (note that this folder can also be referenced as ‘
/et/
xml
’). The fil
e of
interest will have the same name as the page’s Article ID, with the extension ‘
.xml
’. For
example, the “eTrading Team Home” page has the Article ID ‘
et_eth
’ (as seen in the page
URL); the corresponding XML file is ‘
/cdxp/et/xml/et_eth.xml’
.
11

6.2)
Using Cus
tom Tags in cdXP Pages

In addition to standard HTML tags, a number of custom tags are available for use
anywhere in the body of cdXP pages.




10

See Section
6.2
, “
Using Custom Tags in c
dXP Pages
” for more information on using custom tags and a list of default tags
available.

11

A full list of the default XML data files and their purpose is given in Appendix
9.4
, “
eTrading Content Page XML Data File
s
”.

BT eTrading Intranet Site
-

Administrator Documentation


Page
11

These tags provide timesaving shortcuts (e.g., “
<dropcap>T</dropcap>
”, which generates
standard HTML for a drop
-
cap

first letter in a paragraph) and extended functionality (e.g.,

<person>John Smith</person>
”, which looks up John Smith’s contact details in
TeamConnect Directory and displays them on the page) for page authors.

The following custom tags are available by
default (see Section
7.2
, “
Adding Custom
Content Mark
-
up Tags
” for instructions for creating additional tags) :

<person>

When wrapped around a person’s name (with a Boat ID or Directory ID optionally specifi
ed
as an attribute), the name is hyperlinked to the person’s TeamConnect directory profile
and a DHTML pop up box is displayed containing their full name, OUC, telephone number,
etc., when the visitor’s mouse hovers over the name. E.g.,

<person dirId=”3136
74”>Scott Kirby</person>

<person boatId=”johns473”>Ben Johnson </person>

<person>Steve Smith</person>


In the latter case, where no boatId/dirId attribute has been included, cdXP performs a
guess as to the closest match. If more than one person exists with
in BT with the same
name, this is indicated on the pop
-
up; equally if only one match was found, the pop
-
up
indicates an exact match. If no matches were found, the pop
-
up will be blank.

<al>

Article Link. Creates a hyperlink to a cdXP article with the speci
fied Article ID, thereby
protecting the link from future system changes. E.g.,

See <al aid=”et_feb_minutes”>February Minutes</al> for more details.


Note that other attributes applicable to regular ‘
<A>
’ hyperlinks may also be included.

<dropcap>

Generates

drop capital letter at start of paragraph. E.g.,

<dropcap>T</dropcap>he minutes were read and agreed.


<copy>

Copies information from elsewhere in the article. By using the ‘ref’ attribute to specify the
name of a header node in the current document,
12

the

information can be copied and will
be automatically updated if it changes. E.g.:

This page was last updated <copy ref="lastUpdated" />

Send suggestions to <person><copy ref="owner" /></person>.

<h1><copy ref="title" /> (<copy ref="pubDate" />)</h1>


If in
formation is required from somewhere in the document other than the header section,
the ‘
select
’ attribute allows any XML node to be specified using an XSL Pattern:

As mentioned in paragraph 2, “<copy ref="/article/body/p[2]" />”





12

Alternatively, if an XML node has an ‘
id
’ attribute, its value can be copied by specifying this ID in the ‘
ref
’ attribute of a ‘
copy

element. If there is also a header node with the same name, the node with the matching ID takes precedence.

BT eTrading Intranet Site
-

Administrator Documentation


Page
12

6.3)
Creating A New Page

The
simplest way to create a new page on the eTrading site is to copy one of the existing
‘article’ XML documents in the ‘
/et/xml
’ folder to a new file in the same folder and changing
the AID part of the filename to any unique identifier. Page information can
then be modified
as described in the previous section and the page will be accessible by specifying the new
AID in a call to ‘
cdxp.asp
’.

For example, if an existing data file was copied to ‘
/cdxp/et/xml/et_my_page.xml
’, the new
page would be accessed via ‘
cdxp.asp?aid=et_my_page.xml
’.

6.4)
Modifying Site Navigation Structure

The left
-
hand frame of the eTrading site contains a DHTML navigation device; the
hierarchy of links shown by the device can be modified very simply by editing the text file

/et/xml/et_nav.x
ml
’, which contains a ‘
nav
’ XML document.

The root ‘
nav
’ node of this file contain a number of ‘
section
’ elements, each of which is
rendered into a separate section on the navigation device. Each section contains a number

of ‘
link
’ elements, some of which
contain sub
-
links; in fact, link elements may be nested
several levels deep and will still be rendered correctly.

Each link element corresponds to a link on the navigation device, named according to the

name
’ attribute and pointing to the URL specified by


href
’. If a ‘
description
’ attribute is
included, this text will be displayed in the status bar when the user’s mouse passes over
the link. Any additional attributes will be copied directly as attributes of the link element on
the navigation device; this
allows, for example, CSS styling by including a ‘
style
’ property.

Adding a new link to the ‘Customers’ section

1)

Locate the ‘
section
’ element with the ‘
name
’ attribute “Customers”

2)

Copy and paste one of the existing ‘
link
’ elements within the section

3)

Set the

name
’ and ‘
href
’ attributes as desired


Customising the appearance of a particular link

1)

Locate the ‘
link
’ element corresponding to the link to be customised

2)

Add a ‘
style
’ attribute and insert a CSS expression, e.g., “color: red”


BT eTrading Intranet Site
-

Administrator Documentation


Page
13

7

Customisation Options

7.1)
Cha
nging How Content Pages Are Displayed

There are two methods of customising the appearance of cdXP contents pages. The
simplest method is to modify the eTrading site’s CSS (stylesheet) files, which changes the
way pages are displayed in supporting (version
4) browsers. The second (more powerful
and browser
-
independent) method is to modify the XSL transformation filters that generate
the content on the server.

Modifying eTrading Cascading Style Sheet Files

Cascading Style Sheets provide powerful control over
the appearance of elements of an
HTML page, such as headings and the page background colour. All eTrading pages
reference the CSS file ‘
/et/css/et.css
’; article pages also reference ‘
/et/css/et_articles.css
’.
Modifying existing statements or adding additio
nal ones allows the client
-
side rendering of
eTrading pages to be controlled.

For example, the following statement would make all bold text (e.g., “
<B>This text is
bold</B>
”) on the page appear green:
13

B { color: green }


Modifying eTrading XSL Transforma
tion Filters

eXtensible Stylesheet Language (XSL and more recently, XSLT) is the W3C standard for
transforming XML data into other formats.
14

Using a powerful combination of pattern
matching and templates, XSL can be used to transform XML into formats such
as HTML,
PDF or just other XML flavours. cdXP uses XSL filters extensively to handle the translation
of XML content into a format viewable by the user agent.

By default, XSL filters are stored in the ‘
/cdxp/xsl/
’ folder. Each filter is modular and can be
a
pplied to data independently or as part of a chain. As described in section
4.4
,

cdxp_transformXmlDoc_inc.asp
”, the sequence of filters applied is determined by the type
of XML data being processed (i.e.,

article/nav document) and the delivery mode specified
(i.e., ‘view’, ‘xml’ or ‘edit’).

The filters employed on the eTrading site (see section
5.2
, “
Key XSL Transformation
Filters
”, for a list of specific
key filters) fall into two categories: tag processing filters, which
perform value
-
added processing of tags in the document then output it in its original XML
form, and display filters, which completely transform the document into code displayable by
the v
isitor’s browser. Display filters always occur last in the filter chain.

A common operation is customising the layout of eTrading content pages via the main
eTrading article display filter, ‘
et_article_[html
-
css
-
js].xsl
’. For example, to remove the
redunda
nt ‘PageEdit’ link from the cdXP tagline that appears at the foot of each eTrading
page (PageEdit was removed from the final cdXP release), follow these steps:




13

Full
documentation of the CSS standard can be found on the W3C’s CSS site:


http://www.w3.org/Style/CSS/


14

Full documentation for the XSL standard may be found at the following site:


http://www.w3.org/TR/xsl/


BT eTrading Intranet Site
-

Administrator Documentation


Page
14

1)

Open ‘
/cdxp/et/xsl/et_article_[html
-
css
-
js].xsl
’ in a text editor

2)

Search for the root template

<xsl:template match="/">


(contains the HTML layout for the content page)

3)

Locate “
<I>delivered by ..
” near the end of the template

4)

Remove the HTML code corresponding to the ‘PageEdit’ link


7.2)
Adding Custom Content Mark
-
up Tags

Adding additional markup tags

to the vocabulary allowed in eTrading content pages is an
extension of the procedure described in section
7.1
, “
Modifying eTrading XSL
Transformation Filters
”. Instead of modifying existing templates, h
owever, a new match
template is created within ‘
et_article_[html
-
css
-
js].xsl
’ for the desired new tag name.

The following section describes how to enable cdXP to recognise and process ‘
date
’ tags
in eTrading content pages. The new ‘
date’

tag will allow aut
hors to specify dates in a
structured format in content pages; the date will then be presented using a standard layout
when the page is displayed. Having structured date information also opens the possibility
of intelligent searches for pages referencing a

specific date, without the problem of dates
presented in varying formats (e.g., “dd/mm/yy”, “d mmmm yyyy”).

Example


Adding a New ‘Date’ Tag


1)

Open ‘
/cdxp/et/xsl/et_article_[html
-
css
-
js].xsl
’ in a text editor

2)

Search for the string “
<xsl:template match="pe
rson">


(this is the match template for ‘
person
’ tags; we will place our new ‘
date
’ tag in the
same section of the file in order to keep custom tags together)

3)

Before this line (and any associated comment lines), add the following new line:

<xsl:template ma
tch="date"> REPLACEMENT TEXT </xsl:template>


(this XSL statement causes each ‘
date
’ element in the eTrading content page to be
replaced with the string “REPLACEMENT TEXT”)

4)

We will assume that each ‘
date
’ element contains a single ‘
day’
, ‘
month’

and ‘
year’

element, e.g:

<date> <day>21</day> <month>2</month> <year>2002</year> </date>


(note that omitting or duplicating one of these elements will generate unexpected
output rather than an error, so input checking is not required)

5)

We will also assume that the s
tandard date layout format is in the form:

d/m/yyyy


6)

Changing our XSL match template to the following will perform this conversion:

<xsl:template match="date">


<xsl:value
-
of select=”day” />/


<xsl:value
-
of select=”month” />/


<xsl:value
-
of
select=”year” />

</xsl:template>


(this match template provides very trivial support for ‘
date’

elements. It could be
improved by enforcing the 4
-
digit year format and by providing the option to convert
the month digit to its name equivalent, e.g., “2” bec
omes “February”)

BT eTrading Intranet Site
-

Administrator Documentation


Page
15

7.3)
Adding Additional Processing Filters to the Chain

The previous section described the procedure for modifying the main ‘
et_article_[html
-
css
-
js].xsl
’ XSL filter in order to process new custom tags in eTrading pages. The alternative
method i
s to create a brand new XSL processing filter and add it to the filter chain for
eTrading pages. This allows the filter to be reused in other sites if desired, as well as
encouraging an easier to maintain, modular set of filters.

The procedure for adding a

new XSL processing filter to the eTrading chain is as follows:

1)

Create a new file in the ‘
/cdxp/et/xsl/
’ folder with a filename in the form:

uniqueID_[xml].xsl


2)

Open the new file in a text editor and insert the following text:

<?xml version="1.0"?>

<xsl:st
ylesheet xmlns:xsl="http://www.w3.org/TR/WD
-
xsl">



<!
--

the following match templates copy all the elements in the XML file


without change, except those for which specific templates are


declared later (e.g., “customElement” m
atch template below)
--
>


<xsl:template match="*">


<xsl:copy>


<xsl:for
-
each select="@*">


<xsl:attribute><xsl:value
-
of /></xsl:attribute>


</xsl:for
-
each>


<xsl:app
ly
-
templates />


</xsl:copy>


</xsl:template>


<xsl:template match="text()"><xsl:value
-
of /></xsl:template>


<xsl:template match="/"><xsl:apply
-
templates /></xsl:template>



<!
--

custom match templates go below
--
>


<xsl
:template match="customElement"></xsl:template>


</xsl:stylesheet>


3)

Modify the custom match template, as described in the section
7.2

4)

Add the new filter to the cdXP filter pool by editing ‘
/cdxp/cdxp.asp
’ and searching
for the str
ing “
oXslFiles.Add( "person", "person_[xml].xsl" );
”. Insert a new line after
this statement in the form:

oXslFiles.Add( "uniqueName", "uniqueID_[xml].xsl" );


5)

Add the new filter to the eTrading filter chain by editing ‘
/cdxp/includes/
cdxp_transformXmlDoc
_inc.asp
’ and searching for the string “
case "view"
”, which
precedes the eTrading article transformation logic

6)

After the line “

oXmlDoc.Transform( oXslFiles.nodeCopy );
”, add the following:

oXmlDoc.Transform( oXslFiles.uniqueName );

BT eTrading Intranet Site
-

Administrator Documentation


Page
16

8

Known Issues

8.1)
Full Filen
ame Must Be Specified When Saving Pages From cdXP Edit

When using cdXP Edit to modify an existing page, a “Save to XML File” (i.e., “save as”)
text box appears next to the “Save” button at the foot of the page. An example filename is
inserted into the text

box, but this MUST be changed to the correct path and filename of
the XML data file for the page before pressing the “Save” button in order for the edit to be
successful.

By default, this means a filename in the following form should be specified:

/et/xml
/et_AID.xml


where AID is the Article ID of the page. For example, if editing the “eTrading Team Home”
page, the filename ‘
/et/xml/et_eth.xml
’ should be entered into the “Save to XML File” box
before saving. See Section
6.1
, “
Editing an existing page directly as a text file on the
server
” for help with determining the XML file corresponding to a page.

8.2)
eTrading Editors May Write to Any Well
-
Formed File on Website

Due to the method used to specify the path of the

data file when saving pages from cdXP
Edit, users with permission to access the ‘
/cdxp/secure/
’ folder (‘eTrading Editors’) are able
to modify data in any well
-
formed (e.g., XML) file within the website root and its sub
-
folders.
Attempting to write data t
o non
-
well
-
formed XML files will fail, but content such as HTML
may also be vulnerable if it is well
-
formed (i.e., obeys XML syntax rules).

If users with editing permissions being able to modify XML/HTML files anywhere on the
web
-
site (potentially includin
g those unrelated to the eTrading site) is considered an
unacceptable security risk, then one of the following actions should be taken:

1)

Modify ‘
cdxpedit.asp
’ to only allow editing of files within ‘
/et/xml
’. This is the only
resolution that will continue to

allow cdXP Edit to be used.

2)

Disable ‘
cdxpedit.asp
’ by removing it from the public website

3)

Remove all non
-
administrative permissions from the ‘
/cdxp/secure/
’ folder


8.3)
User Context Must Be Specified When Entering Username During
cdXP Edit

Basic Authenticatio
n

When prompted for a username and password by a Basic Authentication dialog box (e.g.,
when saving changes made using cdXP Edit), the FULL username, including NT context,
must be provided. At the time of writing, for ISE (Computing Partners) personnel the

NT
context is normally “NSH
-
SN
-
CSEC”, meaning full usernames are in the form:

NSH
-
SN
-
CSEC/jones123


instead of just:

jones123


Context information is normally added automatically when specifying a username, e.g.,
when logging into Windows NT. When using B
asic Authentication, however, it must be
specified explicitly; this is a requirement of Basic Authentication, not cdXP.

BT eTrading Intranet Site
-

Administrator Documentation


Page
17

8.4)
Navigation Bar Not Dynamic In Netscape 4.75 And Earlier

Due to DHTML limitations in Netscape 4.75 and earlier, the eTrading navigation d
evice will
appear static to visitors using it. This means that sub
-
links will not appear when a link is
clicked; a workaround would be to include them on content pages instead. Future
development work should implement a cross
-
browser version of the DHTML u
sed.

8.5)
Content Page Caching Not Implemented

Work began to implement caching of display pages, but was not completed in time for site
launch, so this functionality is not operational. The page generation process is very fast
and the eTrading site is expected
to receive minimal traffic, so this should not be a
problem unless visitor numbers increase significantly.

Implementing caching would involve adding a check to ‘
cdxp.asp
’ to see if a cached
version of the requested page exists, in which case a new version
does not need to be
generated (subject to logic as to whether the cached page is suitably up
-
to
-
date).

The file ‘
/cdxp/includes/_cdxp_cache_inc.asp
’, disabled code in the ‘
/cdxp/global.asa

‘ and
files in the folder ‘
/cdxp/_cache
’ demonstration work on the
caching mechanism so far. All
code is fully commented and would not require much work to complete.

8.6)
‘Top.htm’ May Render Incorrectly in Some Browsers

The ‘
/cdxp/et/top.htm
’ static HTML attempts to render the complicated top frame layout in
a cross
-
browser m
anner, but has only been tested in Netscape 4.x and IE5.x. Older
browsers such as IE4.x and Netscape 3.x, as well as newly released browsers such as
IE/Netscape 6+ are likely to render the content differently.

BT eTrading Intranet Site
-

Administrator Documentation


Page
18

9

Appendices

9.1)
Server Configuration Notes

Server R
equirements


Microsoft Internet Information Server 4


Microsoft XML Parser 3 (MSXSL3)
-

http://ww.microsoft.com/xml/


ProxyCFG.exe (run once)
-

http://ww.microsoft.com/
xml/


JScript ASP Engine v5.5(+)
-

http://ww.microsoft.com/scripting/


ASP Configuration

IIS Management Console should be used to set the following ASP options for cdXP:


Buffering ENABLED


Sessions DISABLE
D


Permissions



/cdxp/secure/
’ folder should have permissions restricted to administrators and the
group/individual usernames approved for editing eTrading pages. Be aware that
giving a user permission to access the ‘secure’ folder enables them to write da
ta
to any XML syntax file on the website (see Section
8.2
, “
eTrading Editors May
Write to Any Well
-
Formed File on Website
”).


Virtual Folders

The following virtual folders must be set

up for cdXP to operate:

/et

Points to ‘
/cdxp/et/


/cdxp

Points to ‘
/cdxp/
’ (redundant if default folder location)

/cdxp/newProc

Points to ‘
/cdxp/
’ (with “Run in New Process” ENABLED)



9.2)
cdXP Folder Structure

The content/data files specific to the cdXP appl
ication are by default located in the ‘
/cdxp/

folder. Note that all files and folders prefixed with an underscore character “_” are
temporary elements not required for the operation of cdXP or the site and may be ignored
(or deleted if desired).

The follo
wing shows the default folder hierarchy of the eTrading folder, with a brief
description of each folder (for fuller descriptions, see Section
5
, “
eTrading Components
”):

/cdxp/

Main cdXP ASP application files (
JScript)



css

Cascading Style Sheets for built
-
in cdXP pages



articles

Content data files for built
-
in cdXP pages



includes

ASP library files (JScript)



secure

Restricted permission applications (‘
cdxpedit.asp
’)



xsl

XML transformation filters (server sid
e)



et

eTrading site content (see below)


BT eTrading Intranet Site
-

Administrator Documentation


Page
19

9.3)
BT eTrading Folder Structure

The content/data files specific to the eTrading site are by default located in the ‘
/cdxp/et/

folder.
15

The following shows the default folder hierarchy of the eTrading folder, with
a brief
description of each folder
16

(for fuller descriptions, see Section
5
, “
eTrading Components
”):

/et/

Root static HTML files, including default.htm



css

Cascading Style Sheets (client side)



images

Sit
e graphics (client side)



jscripts

JavaScript (JScript) source files (client side)



xml

Site content data files, i.e., site content (server side)



xsl

XML transformation filters (server side)


9.4)
eTrading Content Page XML Data Files

The following is a l
ist of the default XML data files (i.e., content pages) found in the
“/cdxp/et/xml/” folder, with a description of each:

et_default.xml

-

“Main Page”

(eT homepage, ET background image)


et_pch.xml

-

“About BT eTrading”

(information for potential custome
rs)


et_eth.xml

-

“eTrading Team Home”

(news and resources for eT team)


et_ech.xml

-

Existing Customer Home

(e.g., info on Cashless customer)


et_ecf.xml

-

“eTrading Team On
-
line Contact Form”

(enquiry form)


et_ewr.xml

-

“BT eTrading Web Resources”

(
links to web resources)


et_gc.xml

-

“BT eTrading Team Contacts”

(list of team members)


et_gi.xml

-

“BT eTrading Information”

(generic information page)


et_ost.xml

-

“Foreign Travel”

(sample news page)


et_gtdh.xml

-

“Gateway Technical Docs”

(links t
o whitepapers, etc)


et_ph.xml

-

Project Home

(e.g., info on a specific Cashless project)


et_nav.xml

-

Site Navigation

(see
6.4
, “
Modifying Site Navigation Structure
”)


9.5)
Defaul
t BT eTrading Site URL

When located on the default e
-
Commerce team web server (NSH, D
-
ground, next to laser
printer beside G. Merrison’s office), the BT eTrading web site may be accessed at:

http://147.147.7.164/et/




15

Files are always accessed by cdXP via the virtual folder ‘
/et/
’, however, so the eTrading folder may be moved freely as long as
the virtual folder path is updated.

16

All files and folders prefixed with an undersco
re character “_” are temporary elements not required for the operation of cdXP or
the site and may be deleted.