dhtmlxEditor Guide and Code Samples

1. Introduction

1.1 Scope of the Document

This document describes dhtmlxEditor component and defines its key features. This documentation is created to give users full understanding of every feature of this component and also to enable them to use it quickly and easily.

1.2 Target Readers

Target readers are users (developers).

2. What is dhtmlxEditor

This component is a simple text editor that can be used in web pages.
It contains functionality that is often used in desktop editors. So if you've ever used MS Word or Open Office, you wouldn't have any trouble using dhtmlxEditor for writing texts and formatting them in the Web.

2.1 Main Features

2.2 Supported Browsers

3. Interface

dhtmlxEditor's interface is simple and clear. This text editor consists of:

3.1 Toolbar

The Toolbar is the area in dhtmlxEditor, where all the editor features are located, and where the user can activate them. Each toolbar button is responsible for a certain function.
Among editor's basic functions, there are ones dealing with simple text formatting.

By clicking any button the user executes the function this button is responsible for. When the user hovers the mouse over the button, it becomes highlighted and the button's tooltip appears providing the information about the button function.

3.2 Editing Area

Editing Area is the area where the typed in text can be formatted.
To format the text the user should select it and then click the corresponding formatting button in the toolbar. If there is more text than the editing area allows to display, the scroll bar will appear.

4. Working with dhtmlxEditor

dhtmlxEditor is used to create texts that are going to be published on the Internet, and to be read using web browsers.

4.1 Text Formatting

Text formatting sets the way the text will look like. dhtmlxEditor's formatting tools are a very easy way of making the text look nice and readable.

Making the font bold, italic, underlined or stroked through contributes to adding expressiveness: 
- bold, italic, underlined or strikethrough formatting is applied to the text.

Note: If the user applies any of these options to the selected text, the toolbar button will be highlighted. In case the formatting needs to be removed, the user should press the highlighted button again. Any of the options can be applied to the text individually or in any combination with other options.

 

The user can set the text relative to the editing area which is called text alignment.There are four types of alignment available in dhtmlxEditor:


Buttons are used to set the text alignment (left, centered, right, or justified)
The selected text can be arranged in the following types of lists:
- these buttons create numbered or bulleted lists
The user can easily increase or decrease the text indent:
  - these buttons increase or decrease the text indent
dhtmlxEditor provides a number of functions that allow users to manipulate the following font settings in the editing area:

- these buttons superscript or subscript the text
- these buttons set the text as headings of different levels (h1 is the highest-level one)

5. Initializing dhtmlxEditor

The first steps that need to be taken for dhtmlxEditor's initialization are the following:


<link rel="stylesheet" type="text/css" href="[full path to this file]/dhtmlxeditor_dhx_blue.css">
<link rel="stylesheet" type="text/css" href="[full path to this file]/dhtmlxtoolbar_dhx_blue.css">
<script src="[full path to this file]/dhtmlxeditor.js"></script>
<script src="[full path to this file]/dhtmlxcommon.js"></script>
<script src="[full path to this file]/dhtmlxtoolbar.js"></script>
The user needs to create an object where dhtmlxEditor will be placed later. In this example the object is a <div> element on page, which is placed in the <body> tag.   
<div id="editorObj" style="width: 100%; height: 300px; border: #909090 1px solid;"></div>
The next step is to create a new dhtmlXEditor object and place it after the <div> element (object) that we've just created:
var editor = new dhtmlXEditor(objId, skin);
objId defines an HTML object on page ,to which the editor is attached (the main editor container in the code mentioned above).
skin is the optional parameter which defines the skin, that will be applied to the editor.
If this argument is not set, the component will be created with the default skin (dhx_blue).

Then the
method setIconsPath() should be used to set the full path to the directory, where editor image files are located. By means of this method the user is able to set path to the directory, where icons images are stored.
editor.setIconsPath("[full path to this directory]/codebase/imgs/");
Icon images are grouped by skin name in the directories inside this imgs one. The user shouldn't indicate the directory for icons images for a certain skin inside imgs one in setIconsPath() method, as the system will do it itself.

And the last line of code for initialization is the following:
editor.init();
So, in our case the initialization code for dhtmlxEditor will look like this:
var editor = new dhtmlXEditor("editorObj");
editor.setIconsPath("[full path to this directory]/codebase/imgs/");
editor.init();

6. Available Skins

The following predefined skins are available for dhtmlxEditor users:



It should be noted that some other skins can be available as addons, and they are not included into the package. But they can be downloaded from the site.

7. API Functions

Most of the functions do not have any incoming arguments and work with selected text.

The following functions are responsible for applying the bold, italic, underlined or stroked through styles to the selected text:
applyBold();
applyItalic();
applyUnderscore();
applyStrikethrough();
To set selected text alignment, the following functions are used:
alignLeft();
alignRight();
alignCenter();
alignJustify();

Use these two methods to superscript or subscript the selected text:

applySub();
applySuper();

The lists can be created and the text indent can be increased or decreased like this:

createNumList();
createBulList();
increaseIndent();
decreaseIndent();

The following methods are used with the selected text block to set the heading:

applyH1();

applyH2();

applyH3();

applyH4();
There is the method that gets html content of the editor document:
getContent();
The following method sets the content to the editor document, passing the parameter htmlString - a html string that should be set as the editor content:
 setContent(htmlString)
There is also the possibility to set the content from an html document to the editor document, passing the parameter url - the path to the html page:
setContentHTML(url);