AJAX Example Developer's Guide

Version 5.9.4

Table of Contents

• Introduction
• Configuration
• Style (CSS)
• Static contents (HTML)
• Dynamic contents (JavaScript)
• Imported libraries
• Code design and functioning
• Creating floating windows and tabs
• Result view (XSLT)
• Image generation
• Export
• URL generation
• Supported browsers

Introduction

The AJAX client application uses the SOAP interface of JChem Web Services. It applies several services such as getting table information, getting JChem information, running searches, etc. Since web services can be called from any platform, the client application could also be implemented in other programming languages and communication handling principles should be similar to this example.

Configuration

The most important things can be configured in config.xml file, including

• Database parameters
• Data handling mode: table or relational
• Marvin directory
• Path of JSP (molecule image and export file generation) files
• SOAP service path and function names
• GUI parameters (initial table displayed, minimized navigation width in pixels, enumeration, etc.)
• Columns to be displayed in the spreadsheet

Configuration tag	Meaning
config	Root element of the configuration xml
db	Parent element of database configurations
username	Username for database connection (optional)
password	Password for database connection (optional)
driver	Database driver (e.g. com.mysql.jdbc.Driver)
url	Database url (e.g. jdbc:mysql://localhost/jchem)
propertyTable	Name of the JChem property table
mode	Data handling mode. Can be 'table' or 'relational'. Relational mode is only supported for Mysql, Oracle and Derby. See: Relational mode
marvinPath	Absolute or relative path of the marvin directory (e.g. http://localhost:8180/marvin OR /marvin)
jspPath	Parent element of JSP configurations
getImage	Absolute or relative path of the molecule image generator .jsp file (e.g. /ajax/jsp/img.jsp)
import	Absolute or relative path of the molecule importer .jsp file (e.g. /ajax/jsp/import.jsp)
export	Absolute or relative path of the result exporter .jsp file (e.g. /ajax/jsp/export.jsp)
stConfig	Absolute or relative path of the standardizer configuration handler .jsp file (e.g. /ajax/jsp/stconfig.jsp)
sslPort	SSL port number for JSP files in case of https (optional)
soapPath	Collector element of WebService access points
tableInfo	Path of the JChemSearch WebService
tableInfo2	Path of the JChemSearch WebService
complete	Path of the JChemSearch WebService
getMolData	Path of the JChemSearch WebService
getMoreHits	Path of the JChemSearch WebService
insert	Path of the DataManipulation WebService
edit	Path of the DataManipulation WebService
remove	Path of the DataManipulation WebService
recalculate	Path of the DataManipulation WebService
upgrade	Path of the DataManipulation WebService
createTable	Path of the DataDefinition WebService
dropTable	Path of the DataDefinition WebService
addColumn	Path of the DataDefinition WebService
dropColumn	Path of the DataDefinition WebService
import	Path of the DataManipulation WebService
export	Path of the JChemSearch WebService
versionInfo	Path of the JChemSearch WebService
tableInfoRel	Path of the RelSearch WebService
completeRel	Path of the RelSearch WebService
getMolDataRel	Path of the RelSearch WebService
exportRel	Path of the RelSearch WebService
getRelatedTableData	Path of the RelSearch WebService
markushLibrarySize	Path of the Markush WebService
markushEnumerate	Path of the Markush WebService
close	Path of the Connection WebService
soapMethod	Parent element of WebService method names
tableInfo	WebService method that provides a database connection and JChem table information
complete	WebService method that runs a complete search and gives back the results immediately
getMolData	WebService method that returns certain molecules of a search
getMoreHits	WebService method which returns similar hits for a query
insert	WebService method which inserts a molecule into the database
edit	WebService method which modifies a molecule in the database
remove	WebService method which removes a molecule from the database
recalculate	WebService method which recalculates the structure table data
upgrade	WebService method which automatically upgrades to the current version
createTable	WebService method that creates a structure table
dropTable	WebService method that removes a structure table
addColumn	WebService method that creates a custom column in a structure table
dropColumn	WebService method that drops a custom column from a structure table
import	WebService method which handles molecule imports
export	WebService method which exports the result set of a particular search
versionInfo	WebService method that provides version information
tableInfoRel	Relational WebService method that provides a database connection and JChem table information
completeRel	Relational WebService method that runs a complete search and gives back the results immediately
getMolDataRel	Relational WebService method that returns certain molecules of a search
exportRel	Relational WebService method that exports the result set of a particular search
getRelatedTableData	Relational WebService method that returns all related data for a structure table row
markushLibrarySize	WebService method which calculates the library size of a markush structure
markushEnumerate	WebService method which enumerates a markush structure sequentially or randomly
close	WebService method that closes the database connection
guiAttributes	Parent element of miscellaneous GUI attributes
defaultResults	Name of the table which is loaded first
navigationWidth	Minimized navigation pane width in pixels
hitColor	RGB color code of the substructure hits in the molecule images of the Result pane (e.g. #0000ff = blue)
previewLimit	Maximum number of molecules to be displayed on the preview page
enumDisplayMode	Display mode of molecule enumeration. Accepted values are 'original', 'reduction' or 'hgexpansion'.
enumMaxNumber	Maximum number of molecules in an enumeration (e.g. More similar hits)
relatedPageSize	Maximum number of related rows to display at once
relatedPreviewLimit	Number of rows to check in the next related table in preview mode
formulaComparison	Formula comparison mode affects the result of sorting and <, > operations when they applied to cd_formula column. Accepted values are 'string' or 'chemical'.
appletPreloading	Sets whether the application should preload Marvin applets (MView and MSketch), or not. Accepted values are 'true' and 'false'.
spreadsheet	Parent element of the spreadsheet layout definitions
default	Default spreadsheet layout settings for tables which are not defined. The column names are separated by space characters from each other. In addition there are predefined constants for columns sets, which are enumerated in the following table. These constants can be changed easily in the JS code. CD all cd columns NON-CD  all non-cd columns FP all fingerprint columns SIM similarity value, if it exists
<tablename>	Each table may have its own layout specification. If there is no definition for a particular table then it will use the default layout.

Configuring the spreadsheet

You can enumerate the tables inside the <spreadsheet> section.

	<spreadsheet>
		<tablename1>...</tablename1>
		<tablename2>...</tablename2>
		...
	</spreadsheet>

The rules the format has to follow are:

1. Inside the table tags you can determine the column order. There are predefined constants: CD for all cd_ columns, NON-CD for all columns which do not start with cd_, FP for all fingerprint columns, and SIM for similarity value if it exists. For example
   
   <jchem_table1>SIM cd_id cd_formula cd_molweight NON-CD</jchem_table1>
   means the first column should be the similarity value if it exists, then cd_id, cd_formula and cd_molweight columns should come in this particular order, and finally all non cd_ columns should be listed.
2. Table tags can have a writable attribute with values of: 'true', 'false', 'searchOnly' or 'managerOnly'.
3. If a table has not been configured separately then the default configuration will be applied to it. This is defined inside the mandatory <default> tag which behaves the same way like the other table tags.

Example:

	<spreadsheet>
		<default writable="true">SIM cd_id cd_formula cd_molweight NON-CD</default>
		<jchem_table1 writable="managerOnly">cd_id cd_formula cd_molweight</jchem_table1>
		<jchem_table2 writable="searchOnly">cd_formula cd_molweight NON-CD</jchem_table2>
	</spreadsheet>

This configuration defines column orders for tables jchem_table1 and jchem_table2. All other tables will follow the configuration defined inside the <default> tag. jchem_table1 will be editable only on the Manager page but not on the Search page, so insert / edit / remove molecule icon won't appear. jchem_table2 will be editable in the Search page but won't appear in the list of the Manager page. So you cannot import, manage, regenerate and remove this table. All other tables can be seen on both pages because the default configuration is writable="true".

Storing username and password in the config file

Database username and password parameters are optional. If not given, AJAX application will pop up a login window that requires these authentication data and store them in browser cookies in case the authentication is successful. Next time the authentication will be automatic if user name and password information are found in the cookies.

Note: config.xml is in a public web directory, so data inside (e.g. database details) can be accessed by anyone who has access to the AJAX application.

Style (CSS)

Style of static contents and initial style of dynamic contents are defined in the .css files of the style directory, which follow the W3C Cascading Style Sheet (CSS) standard. They consist of several parts, where the most important sections are the window style and the application style. The window style section contains the general style of the floating, closeable, draggable, and resizeable windows. The specific definitions of these windows and other graphical elements are given in the application style section, except scrollbar related attributes. Scrollbar (js/scrolling.js), Login Box (js/login.js), Window Creator (js/wndw.js) and some other parts are handled independently from the other graphical elements of the application (e.g. js/search/view.js, js/search/event.js). This separation can be seen in the different sections of the stylesheets, as well.

Static contents and layout (HTML)

Application layout, static elements, and elements containing dynamic content are coded in HTML in index.html. The print preview is a separate page, which has a much simpler layout and can be found in preview.html.

Index page has a container <div> element, inside of that can be found every available area and window. One restriction is applied to the windows: they may not have embedded JavaScript code, so using the <script> tag should be avoided here. However, JavaScript can be used in the <head> section.
In the following list you can see the HTML IDs of each important area:

Area	Element ID
Navigation pane	navigation
Result pane	result
Content part of Navigation pane	navigationContent
Content part of Result pane	resultContent
Scrollbar	scrollbarResult
DB login window	login
Result spreadsheet	spreadsheetResult
Query window	query
Column and condition list in the Query window	generatedQuery
Column and condition list in the Insert window	generatedInsert
Options window	options
Options Main page	main
Options Advanced page	advanced
Options Chemical Terms page	chemicalTerms
Molecule insert window	insert
Export window	export
Export Options page	exportOptions
Export Fields page	fields
Print preview window	preview
About window	about
Markush enumeration window	markush
Marvin applet inside the Query window	MSketchQuery
Marvin applet inside the Insert window	MSketchInsert

Dynamic contents (JavaScript)

Dynamic interactions to the graphical interface are implemented in JavaScript, and these parts can be found in the js directory. The outer elements that contain dynamic content are defined in index.html but their values or inner HTML parts are affected later by JavaScript. Also some sections are defined in JavaScript because information is needed before it could be displayed properly. Now, there is a Search page and a Manager page inside the AJAX example. As the application realizes an MVC design pattern, both search and manager have their own controllers and views. Some parts of the business logic, which are strongly connected to the page's controllers and views, are also separated in these pages, while other parts, usually independent classes, are used commonly. The Search page specific JavaScript classes can be found in js/search directory, the Manager page specific codes are in js/manager. Thus, the dynamically created HTML sections are implemented in js/search/view.js and js/manager/view.js, which are only responsible for HTML generation, while js/search/logic.js and js/manager/logic.js make structured and easily processable data for the View and the AJAX layer.

Imported libraries

The AJAX example uses a widely known JavaScript library named JQuery and the following plug-ins:

• Interface (JQuery plug-in) parts compressed
• Mousewheel event listener (JQuery plug-in)
• DHTML eXtensions - editable combobox implementation
• Fix for Internet Explorer to disable combobox options

Code design and functioning of the Search page

Dynamic elements are activated after the index page has been fully loaded. An onReady event is triggered that executes the JS code in the <head> section. It loads the configuration file, and checks whether username and password information could be retrieved from the .xml file. If yes, it executes the initialization controller. Otherwise, the login handler login.js attempts to request the missing database paramerers from the user and store them in browser cookies to avoid displaying the login box every time at startup. In case of error the cookies will be removed and autentication will be required again next time. In case of success the initialization controller will be called. Controller steps are detailed below.

1. Get all table information.
2. Process the url in the browser's address bar to set an initial query result on spreadsheet
3. Scrolling initialization, load scrolling events
4. Determine structure image size
5. Autosize Result pane
6. Define the options of the database dependent comboboxes. (table selection, similarity type selection, screening configuration selection)
7. Fill out the Fields page of the Export window according to the default table
8. Set the default search type to substructure search and sets which sections should be displayed in the Options pane
9. Attach table selection, navigation minimize/maximize, window resize and hit alignment change events to the appropriate elements
10. Create floating, resizeable windows from preview, query, url container, options, export, and about panes
11. Apply events to these panes
12. Send a retrieve all query to the WebService (for the default table) or execute the initial query if it was given in the url

From this point onwards the user controls the application. When the user clicks on something that is defined in the event handler (event.js), the appropriate callback function will be executed, and then the user may act again.

The implementation consists of several JS objects which are placed in separate .js files. Event handler callback functions are the high level controllers. ajax.js methods are also controllers but these are always called as a result of an event, so logically these functions are on a lower level in the design structure. The controllers use freely the variables and methods of the business logic which is made up of the other JS files: view.js, xml.js, logic.js, cache.js, wndw.js, scrolling.js, info.js and soap.js. Soap layer calls XML class methods in some cases as View also uses the results produced by the Logic class. mousewheel.js is independent from the other JavaScript files, but it can be viewed as a part of the business logic.

Creating windows and tabs

While the Interface plug-in makes it possible to create floating, resizeable windows, the Wndw object is able to make floating windows from regular <div> elements while eliminating code repetition. The class attribute of that element must be "window".

create() - Transforms the HTML content of the original <div> to a window that has a draggable header, and minimize, maximize, resize, and close buttons. But this is only an HTML modification, the necessary elements are created for the window where events and CSS rules can be applied. It is possible to determine which window parts or buttons have to be displayed.

attachToOpener() - Attaches a floating window to an opener element. After this moment when the opener is clicked, the floating window will appear. A window can be attached to more than one opener. The primary opener is where the floating window returns when closed and it can be set with the changePrimaryOpener() method.

applyEvents() - Enables the default events to all related window parts and buttons.

The following code creates a floating window from a <div> element with ID "preview", which has a close button and a draggable header. The code sets the title to "Print preview" and assigns two HTML elements (nav_min_preview and nav_preview) to open the window. Finally the drag and close events are activated.

			Wndw.create('preview', 'Print preview', 'close,drag');
			Wndw.attachToOpener('preview', 'nav_min_preview');
			Wndw.attachToOpener('preview', 'nav_preview');
			Wndw.applyEvents('#preview');

Tabs can be generated on any <div> elements, but inside of the <div> element every tab page must have another <div> block, which has a class attribute of "tabContent". Tabs and events attached to them are generated by applyTabs() method which needs an element ID and, optionally, the tab labels, which default to the ID of the page.

			Wndw.applyTabs('options', {chemicalTerms: 'Chemical Terms'});

There are explicit activate, minimize(), maximize(), resize, open and close() functions for cases where the default window event handling is not suitable.

Result view (XSLT)

The spreadsheet on the Result pane is generated by JavaScript but it uses an XSL template to compose the final output. The directories and names of the XSL files can be configured in the beginning section of the js/search/view.js for the Search page or the js/manager/view.js for the Manager page. By default, the generally applied templates are the style/search.xsl and the style/manager.xsl. There are two important cases that must be defined in these templates. Firstly the Result pane spreadsheet layout which can be anything that is allowed in XSL 1.0, secondly the database column labels are included to change the original database column names to some more human readable texts.

Row numbers, molecule images, formula type

There are two special columns in the Result pane that need to be managed in a different way than the others. The row ordinal number and the molecule image. When you would like to write out a row number, insert a

			<div class="rowNumber"><p /></div>

to that place in the .xsl template file. The rowNumber-classed <div> element in the result HTML will be assigned row numbers in order.
Displaying images is very similar, one must use the

			<div class="image"><p /></div>

element to insert a molecule image. The image-classed <div> element in the result HTML will be assigned molecule images in order.

There is special subscripted style for columns that contain formula-typed data. To use this format, enclose the formula value in another HTML element and set its class attribute to "formula". For example:

			<xsl:when test="name() = 'cd_formula'">
				<td class="formula"><xsl:value-of select="." /></td>
			</xsl:when>
		

Row action icons

You can place action icons to the spreadsheet using the following HTML portions, which has the same format is mentioned in the previous section.

			<div class="edit"><p /></div>
			<div class="remove"><p /></div>
			<div class="moreHits"><p /></div>
			<div class="enumerate"><p /></div>

An "edit" classed div element will assign the location of an "Edit structure" icon, which can be pressed if someone would like to modify the structure or its relating data. Likewise, the "remove" classed div element will assign the location of a "Remove structure" icon, which makes possible to remove a molecule entry. "More Hits" and "Enumerate" icons work the same way.

Image generation

Most of the browsers (e.g. Google Chrome, Firefox 2+, IE8) request the molecules as Base64 encoded (MIME variant) PNG images from the WS and display them as inline images using the <img> tag, since Base64 encoded images can be given as a value of the src attribute. The length of it is limited and dependent from the browser. Unfortunately, there are some browsers which have smaller maximum length size for src than what is needed for displaying the structure images in the AJAX example, so this solution is not applicable. These browsers start a request to the JSP image generator (jsp/img.jsp) for each image, which uses the getHitsAndData() method of the WebService to gain the molecule's structure. The image generator retrieves the molecule, converts the structure to an image binary using JChem and Marvin API functions, sets the response headers, and returns the data which then can be a source of an <img> element. Of course, using one request for each image is not that optimal than requesting all images and all structure data in one request, which is done by the first (without JSP) solution.

Molecule export

Export (jsp/export.jsp) has similar browser issues as image generation. A JavaScript code could call the exporter service directly, but the browser wouldn't able to process and save the output to the client's machine. Therefore we use JSP here. The JSP URL is the action value of an HTML <form> in the GUI. The JSP uses the exportResult() function of the WebService, sets the response headers to force the client to open or save the results, and returns the exported data.

URL generation

It is possible to generate a URL after a successfully submitted search by clicking on "Generate URL" button in the Query pane. If this encoded URL is copied to the address bar of the browser, the AJAX client will return the same query results that we had at the moment of URL generation. Beside of this the AJAX example can be called with the tablename parameter which causes the application to jump to a specific table at startup and retrieve all structures from it. For example:

			http://localhost:8180/ajax?tablename=molecules

Supported browsers

The AJAX client is tested on the following browsers:

Windows

• Internet Explorer 6+
• Mozilla Firefox 2+
• Google Chrome
• Safari 3+

Linux

• Mozilla Firefox 2+

MacOS

• Mozilla Firefox 2+
• Safari 3+