In this topic you will learn how to replace a text field, textarea or hidden field with the KTML editor. The installation process has two steps:
Set up the files and library paths - learn what files have to be copied and where, and what general options to set.
Add the KTML control and set its properties - learn how to change the page code to load and display the editor.
The first step in replacing the textarea with the KTML editor is to upload the files needed by the editor to the server and configuring the general options. To do so, follow the instructions below:
Copy the includes and uploads folders and their sub-folders and files into your site root.
Copy the libraries from the WEB-INF/lib folder into the corresponding folder inside your web application.
Copy WEB-INF/ktml4.tld into the web application WEB-INF.
Edit includes/ktm/ktml4.config.properties to set ktml specific values (preferred image library, thumbnail and upload folder, etc).
First define the preferred image library. If you
have ImageMagick installed, you
should set it as the default library (it offers superior image processing
quality). Enter the following code to configure the preferred library:
KTML_PREFFERED_LIBRARY=imagemagick
Note: To learn more about image processing in KTML, see the
Configure Image Library option.
Next you must specify the path to the ImageMagick
library:
KTML_IMAGEMAGICK_PATH=c:\\Progra~1\\ImageMagick\\";
Note: Replace the path in the sample above with the actual path
on the server to the ImageMagick library.
In order to display and save XHTML
compliant code and clean content, KTML
4 uses the HTML Tidy library.
Like ImageMagick, this is a standalone
library, and you must configure the path to it:
RKTML_XHTML_PATH=c:\\Windows\\
Note: replace c:\windows\ with the
actual path on your server where HTML Tidy is installed. If you do not
have HTML Tidy installed, you
will not be able to use some of the features. To learn more about the
XHTML supported set of tags check out the reference
manual.
The last option to configure is the spell checking.
KTML 4 uses an external library
– aspell – for spell checking.
You must define the path to the library in the configuration file:
KTML_SPELLCHECKER_PATH=c:\\Progra~1\\Aspell\\bin\\
Note: Replace the path in the sample above with the actual path
on the server to the aspell binaries.
Save the file and close it.
In this topic you will learn what changes you must make to the page where the KTML editor is to be used. Before following the instructions in this page, make sure you have already copied all the required files in the site structure, as explained above.
To create a new instance of the KTML editor and configure its properties, you must take these steps:
Add the KTML taglib include declaration to the page.
Add code in the <head> tag of the page to load the Javascript and style files.
Add Javascript code in the <head> tag of the page to initialize the editor, and set default properties.
Add server-side code to the page to configure additional properties.
Add code that replaces the default <textarea> tag with the editor, and renders it in the page.
First you have to include the taglib for KTML in the page. Open the page that will have KTML on it, and add the following code:
<%@taglib uri="/WEB-INF/ktml4.tld" prefix="ktml"%>
In the category of required files enter the Javascript and Cascading Style Sheets files needed by KTML to load and operate properly. These are loaded through <script> and <link> tags in the page's <head> section. The paths to these files are relative to the current document. As an example, if the page is index.jsp in the site root, the path to the base.js file would be includes\common\js\base.js. If the file where the KTML control is inserted would be located in a folder named deep, on the site root, the path has to change to: ..\includes\common\js\base.js.
You need to add the following lines in the <head> tag to load the KTML dependencies:
First load the basic Javascript component files.
These are used to provide common, basic functionality, and have to be
the first loaded:
<script src="includes/common/js/base.js"></script>
<script src="includes/common/js/utility.js"></script>
The last block loads the KTML core, the editor,
the toolbars, and the selected language:
<script src="includes/ktm/core/ktml.js" type="text/javascript"></script>
<script src="includes/resources/ktml.js" type="text/javascript"></script>
<script src="includes/ktm/core/modules.js"></script>
The last to load is the Cascading Style Sheet
that determines the editor look:
<link href="includes/ktm/core/styles/ktml.css" rel="stylesheet"
type="text/css">
Save the changes. In the next section you will learn how to initialize the KTML object.
The next <script> tag sets the KTML object initialization properties. These properties are stored in an array named ktml_init_object, and it contains pairs of property names and values. The main properties that must be set are:
debugger_params – this decides if debugging will be used with the KTML control. This is useful when things do not work out as planned, as it will allow viewing in a separate window all of the steps taken by the control. Possible values are:
“FALSE” or “” (nothing) – this will disable debugging
[2,”textarea_name”] - if set to 2, the name of a textarea element on the page must also be supplied. This is where the debugging will be displayed.
path – this is the relative path to the KTML includes folder. It is relative to the current document.
server – the scripting
language installed on the server. Possible values are: php,
asp, cfm, jsp. If no server side scripting exits, do not
provide a value for this property (use “”
)
<script>
ktml_init_object = {
'debugger_params': false,
'path': "includes/ktm/",
'server': "jsp"
};
</script>
Next you have to set the properties for the specific KTML controls. You must have decided the names to use for each KTML control at this point. For this example there will only be one KTML control which will have the name ktml1. The properties are stored in an array named ktml1_config which contains pairs of properties names and values. The properties that are set through Javascript code in this array are only basic properties; you will have to define more options - specific to the server-side modules like file upload - later on.
The properties that are set are:
The editor window dimensions, through the width and height values:
width: 650 – this will set the width of the KTML control to 650 pixels. It can have any numeric value.
height: 400 – this sets the height to 400 pixels. It can have any numeric value.
When to display the editor toolbars, through the show_toolbar option. This property can take the values:
load - the toolbar is displayed when the editor loads.
focus - the toolbar is displayed when the editor receives application focus (the cursor is placed in the editor).
manual - the toolbar is not displayed at all. The user can decide to display the toolbar by clicking on the sliding arrow.
Whether to display the property inspectors or not. The property name is show_PI, and it can have one of the values:
true - the Property Inspector area is displayed, and when selecting specific elements, it is displayed.
false - the Property Inspector area is not displayed.
The editor's background color, set it in the background_color option. You can use any hexadecimal color code, or '' (nothing) to use the default background color.
Whether to remove the server name from the various links with the strip_server_location property. It can have one of the values:
true - the server name will be removed from the links.
false - the links will also contain the server name.
When the page loads, the editor can be the selected element automatically, so users can start typing. The property name is auto_focus, and it can have one of the values:
true - the editor will get focus as the page loads
false - no special focus is assigned to the editor. It can be selected by the user.
The toolbars' position and buttons to display. The property is buttons, and it receives as value an array made of the row number on which to display the toolbar, the toolbar name, and an array containing the button names.
Copy and paste the following code after the lines added in the <head> section:
<script>
ktml1_config = {
width: 650,
height: 450,
show_toolbar: 'load', //load, focus, manual
show_pi: true, //false
background_color: '#ffffff', // could be ''
strip_server_location: false, //false
auto_focus: true,
autolink:true,
module_props: { },
buttons: [
//row : [rowIndex, toolbarName, [buttons_list]]
//{
// row: 1,
// toolbarName: "",
// buttons: []
//}
[1, 'standard', ["cut", "copy", "paste", "undo", "redo", "find_replace", "toggle_visible", "spellcheck", "toggle_editmode", "help", "about"]],
[1, 'formatting', ["bold", "italic", "underline", "superscript", "subscript", "align_left", "align_center", "align_right", "align_justify", "numbered_list","bulleted_list", "indent", "outdent", "foreground_color", "background_color"]],
[2, 'styles', ["heading_list", "style_list", "fonttype_list", "fontsize_list", "clean_menu"]],
[2, 'insert', ["insert_link", "hyperlink_picker", "insert_anchor", "insert_table", "insert_image", "insert_file", "insert_template", "horizontal_rule", "insert_character"]],
[3, 'form', ["insert_form", "insert_textfield", "insert_textarea", "insert_button", "insert_checkbox", "insert_radiobutton", "insert_listmenu", "insert_filefield", "insert_hiddenfield", "insert_fieldset", "insert_label"]]
]
}
The properties that must be configured server-side are dependant to the module that are being used. Thus, if you are not using all of the provided modules, the code may vary. The properties that are being set in the code sample below have the same significance as the ones explained for the PHP server model. For a detailed explanation of each property, read this topic.
The code to add into the page must be placed within the <script> tag opened in the paragraph above, and is as follows:
<ktml:ktml4 fieldName="ktml1">
<ktml:moduleProperty module="filebrowser" name="AllowedModule"
value="true" exportToJs="false" />
<ktml:moduleProperty module="file" name="UploadFolder"
value="uploads/files/" exportToJs="true" />
<ktml:moduleProperty module="file" name="UploadFolderUrl"
value="uploads/files/" exportToJs="true" />
<ktml:moduleProperty module="media" name="UploadFolder"
value="uploads/media/" exportToJs="true" />
<ktml:moduleProperty module="media" name="UploadFolderUrl"
value="uploads/media/" exportToJs="true" />
<ktml:moduleProperty module="file" name="AllowedFileTypes"
value="doc,pdf,txt" exportToJs="true" />
<ktml:moduleProperty module="media" name="AllowedFileTypes"
value="bmp,mov,mpg,avi,mpeg,swf,wmv,jpg,jpeg,gif,png"
exportToJs="true" />
<ktml:moduleProperty module="filebrowser" name="MaxFileSize"
value="2000" exportToJs="true" />
<ktml:moduleProperty module="filebrowser" name="RejectedFolders"
value=".svn,.thumbnails" exportToJs="false" />
<ktml:moduleProperty module="templates" name="AllowedModule"
value="true" exportToJs="false" />
<ktml:moduleProperty module="templates" name="UploadFolder"
value="uploads/templates/" exportToJs="true" />
<ktml:moduleProperty module="xhtml" name="AllowedModule"
value="true" exportToJs="false" />
<ktml:moduleProperty module="xhtml" name="xhtml_view_source"
value="true" exportToJs="true" />
<ktml:moduleProperty module="xhtml" name="xhtml_save"
value="true" exportToJs="true" />
<ktml:moduleProperty module="spellchecker" name="AllowedModule"
value="true" exportToJs="false" />
<ktml:moduleProperty module="css" name="PathToStyle"
value="includes/ktm/styles/KT_styles.css" exportToJs="true"
/>
<ktml:moduleProperty module="hyperlink_browser" name="ServiceProvider"
value="hyperlink_service.jsp" exportToJs="true" />
<ktml:Execute />
</ktml:ktml4>
Also add a trailing </script> tag to match the one opened earlier.
After defining all of the properties for the KTML editor you must proceed and replace the textarea with the editor. To do so, you must:
Replace the <textarea> tag with a hidden
field tag. The hidden field mus use the same name as the one given to
the KTML object instance - e.g.
ktml1:
<input type="hidden" name="ktml1" id="ktml1"
value="">
Create the editor to replace it in a <script>
tag:
<script>
ktml_ktml1 = new ktml("ktml1");
</script>
Save the page and upload all site folders to the remote server. Then load the page in a browser to see the changes.