XS DHTML Editor (XsDhtmlEditor)
Version 0.95
User Manual
The XS DHTML Editor has been designed to facilitate adding an HTML-aware text-editor to a standard web-page with as little effort from the web-page designer as possible.
Copy-and-Paste from Word/Excel with formatting preservation;
Block Formatting (H1, H2, H3, etc…);
Font-Face, Font-Size, and Font-Color selection;
Bold;
Italics;
Underline;
Ordered and Unordered lists;
Indent and Outdent;
Left, Center, and Right alignment, plus Full Justification;
Hyperlinks, with support for http, https, ftp, news, gopher, mailto, file, telnet, and wais;
Image support, including alignment, alternate-text, and borders;
Table support;
Emoticons support;
Cut, Copy, and Paste;
Undo and Redo;
Preview and Print commands;
Standard and HTML source views;
All of these features are presented in a recognizable, Microsoft Office-like toolbar, which ensures the least amount of training required for your end-users.
Embed the editor in a web-page with as few as 2 lines of code;
“path” property allows the editor to be used from any path within the site;
“imagesPath” property ensures image links are transformed automatically;
“content” property provides easy access to the current source of the editor;
“value” property as an alias for “content” for easier replacement of a standard <textarea> tag; *
“editorColumns” and “editorRows” properties for easier replacement of a standard <textarea> tag; *
“showSave” property allows the Save icon to be hidden if needed;
“onSave” event allows you to easily respond to the user clicking the “Save” icon;
“replaceTags” property allows for HTML tags to be replaced with different HTML tags;
“action” property for auto-posting to server on save; *
definable block format, font, and font size lists; *
definable default font and default font size; *
“styleSheet” property for a more accurate “WYSIWYG” environment; *
elect to show or hide 14 different options; *
“insert” functions for performing custom actions which insert text or html into the content; *
* = new in version 0.95
Installation of XS DHTML Editor is as simple as can be. Simply unzip the package to any folder within your site, using the “preserve folders” option of your unzip utility. When finished, you should have the following folder hierarchy (assuming you unzip to the root of your website):
<root folder of site> ---
XSDHEditor ---
XsDhtmlEditor.htc
XsDhtmlEditorToolbarButton.htc
emoticons.htc
colorPicker.html
dlg_ins_table.html
index.html
license.html
license.text
Docs ---
XsDhtmlEditor-0.95-Manual.doc (this file)
Images ---
(toolbar images, all prefixed with “icon_”)
Emoticons ---
(default emoticon images)
Samples ---
Now that the component is installed, open the “index.html” file in the “XSDHEditor” folder. This is the most basic use of the editor, and should successfully display the editor without any modifications. If “index.html” does not work, make sure you unzipped the package correctly and the folders listed above were all created in the appropriate locations.
You can embed the editor into your pages very easily. First, change your <HTML> tag to include the XML Namespace decleration, like this:
<HTML XMLNS:XS>
Next, add the HTC import line between your opening and closing <HEAD> tags, like this:
<HEAD>
<?import namespace=”XS” implementation="XsDhtmlEditor.htc" />
</HEAD>
Finally, add the line to actually embed the editor in the appropriate location of your page, like this:
<XS:XsDhtmlEditor id="xsEditor" />
That’s all there is to it!
Advanced Options
“path” property –
The “path” property is used whenever the web-page which embeds the editor is not stored in the XSDHEditor folder itself (or wherever you store the source files). For example, let’s say you have the package unzipped as shown in the hierarchy above, with the XSDHEditor folder being a sub-folder of your web-site’s root folder. If you wanted to embed the editor in a page that is saved in the root folder itself, you would need to change the htc import decleration in your page’s <head> section like this:
(standard import)
<?import namespace=”XS” implementation="XsDhtmlEditor.htc" />
(import with relative path)
<?import namespace=”XS” implementation="XSDHEditor/XsDhtmlEditor.htc" />
and add the “path” property to the standard embedding tag like this:
(standard embedding tag)
<XS:XsDhtmlEditor id="xsEditor” />
(embedding tag with “path” specified)
<XS:XsDhtmlEditor id="xsEditor” path=”XSDHEditor/” />
“action” property –
The “action” property can be set to any page you wish to post to when the “save” button is clicked. For example, if you set the “action” property to “save_content.asp”, when the “save” button is clicked the editor’s contents will be posted to the “save_content.asp” page and made available via a standard form variable called “xsContent”. In your “save_content.asp” page, you could then access the content using “Request.Form(“xsContent”)”.
Note: the “onSave” event will not fire if the “action” property is set.
“content”/”value” property –
The “content” property gives you access to the current HTML source-code of the editor’s contents. The following example adds a standard HTML button to the page which, when clicked, pops-up an alert box with the contents of the editor:
<input type=”button” onClick=”javascript:alert(xsEditor.content);”>
This assumes you gave the editor an ID of “xsEditor” when it was embedded.
You can also set this property to initialize the editor with content when it is first loaded, like this:
<XS:XsDhtmlEditor id="xsEditor” content=”<STRONG>Testing</STRONG>” />
or by setting the property to a scripting variable, such as this in ASP:
<XS:XsDhtmlEditor id="xsEditor” content=”<%= varContent %>” />
“insertText”/”insertHtml” functions –
These functions allow you to use custom scripts to insert content into the editor. Use “insertText” by default. Only use “insertHtml” if you need to insert custom HTML tags.
Example: If you wanted to provide a button which, when clicked, would insert the current date and time, you could use this (assuming the editor’s id is “xsEditor”):
<input type=”button”
value=”Insert Date/Time”
onClick=”xsEditor.insertText(new Date().toLocaleString())”>
Example: If you wanted to provide a button which, when clicked, would insert a custom HTML tag, such as <CODE>this is code</CODE>, you could use this (assuming the editor’s id is “xsEditor”):
<input type=”button”
value=”Insert <CODE> Tag”
onClick=”xsEditor.insertHtml(‘<CODE>this is code</CODE>’)”>
“imagesPath” property –
The “imagesPath” property is used to replace the paths of images inserted into the editor before the content is saved. When an image is inserted into the editor, the end-user can click the “browse” button to locate an image on their hard-drive. The path to this image as inserted into the HTML code would be a local path (such as file://c:/My Pictures/Photos/???). Such a path would be useless when viewed as a webpage from the server which presents the finished content. By using the “imagesPath” property, you can have this path automatically translated to a path that makes sense on the web-server (such as “/Photos/???”). Let’s look at an example.
Suppose you have all of your site’s images in a folder called “Photos”, and since this folder is a sub-folder of the root of the site, a valid path to the folder in an HTML <img> tag would be “/Photos/???”. Now, you have the same images stored on your local system in the following folder: “C:\My Pictures\Photos\”. You can therefore set the “imagesPath” property to “/Photos”, and any image you insert into the editor from your local system’s “C:\My Pictures\Photos\???” folder will be converted to “/Photos/???” when the content property is accessed (normally just before you save the contents of the editor).
Basically, you need to mimic the hierarchy on your local system to match that of the web-server, but it’s only necessary from the image folders base and beyond. As you can see from the example, the “Photos” folder on the web-server is just off the root, but the “Photos” folder on the local machine was within another sub-folder called “My Pictures”. This is fine. As long as the images base folder (“Photos” in this case) matches, and all files/sub-folders you use beyond that match, you’ll be fine.
“show?” properties –
The “show?” properties allow you to turn off specific toolbar options. The following options can be turned off:
- Block Format select list (showBlockFormat);
- Font select list (showFont);
- Font Size select list (showFontSize);
- Full Justification button (showJustify);
- Color Picker button (showColorPicker);
- Insert Image button (showInsertImage);
- Insert Link button (showInsertLink);
- Insert Table button (showInsertTable);
- Insert Emoticon button (showEmoticon);
- HTML/Source Mode button (showMode);
- Preview button (showPreview);
- Print button (showPrint);
- Save button (showSave);
- Cancel button (showCancel);
“onSave” event –
The “onSave” event is fired whenever the user clicks the “save” icon on the editor’s toolbar. The obvious use for this event is to kick-off your code to save the current contents of the editor. Here is an example which simply displays the current source of the editor in an alert box:
<XS:XsDhtmlEditor id="xsEditor” onSave=”javascript:alert(xsEditor.content);” />
“onCancel”, “onPreview” events –
The “onCancel” and “onPreview” events are fired when the user clicks the “cancel” or “preview” icon, respectively. The editor takes no default action for either of these events, and it is up to the developer to give these events meaning.
“Print” button –
The “Print” button will raise the browser’s default “print” dialogue”.
“replaceTags” property –
The “replaceTags” property allows you to replace HTML tags inserted by the editor with different HTML tags of your choosing. For example, the editor uses the <STRONG> </STRONG> tags when the “bold” icon is clicked on the toolbar. If you prefer to use the <B></B> tags instead, you can use the “replaceTags” property to do so, like this:
<XS:XsDhtmlEditor id="xsEditor” replaceTags=”<STRONG>,<B>” />
You can include as many tag pairs as you wish, as long as you follow the format of original_tag,new_tag,original_tag,new_tag,etc, etc, etc… Notice that the list of tags is comma-seperated and there is no space after the commas.
The replacement operation is only performed when the “content” property is accessed. Even if “replaceTags” is used, switching to the source view mode will still show the original tags inserted by the editor, not the replacement tags.
“blockFormatList”/”fontList”/”fontSizeList” properties –
These properties accept comma-delimited strings specifying the options to be displayed in the respective toolbar select lists. For example:
<XS:XsDhtmlEditor id=”xsEditor”
blockFormatList=”H1,H2,H3”
fontList=”Arial,Helvetica”
fontSizeList=”small,medium,large” />
Using these settings, the editor will display only “H1”, “H2”, and “H3” in the block format select list, only “Arial” and “Helvetica” in the font select list, and only “small”, “medium”, and “large” in the font-size select list.