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:
Unpack the downloaded zip file containing the KTML sources to a folder of choice.
Copy the includes and uploads folders and their sub-folders and files into your site root. You will have to upload these folders to the web server with the entire site in order for the editor to work.
The includes folder contains files that are required by KTML4, and the uploads folder is empty. This is where users will be able to upload files later on. To allow files be saved in this folder you must follow the instructions in the Configure file uploading topic of this manual.
Open the <site_root>\includes\common\KT_config.inc.cfm file with a text editor. In this file you must define paths to external libraries, date formats and file rights. Before defining any of the options, make sure you have followed the Installation Prerequisites topics, and you have configured your server accordingly.
By default, only the database and screen date
and time formats, and the file and folder rights are configured.
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:
Request.KT_prefered_image_lib = "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:
Request.KT_prefered_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:
Request.KT_prefered_tidy_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:
Request.KT_prefered_aspell_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.
With this, the libraries required by KTML and the paths to them are all set. You can start modifying the page to replace the text field, textarea or hidden field with the KTML editor.
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 your site, and you have uploaded them to the server, as explained above.
To create a new instance of the KTML editor and configure its properties, you must take these steps:
Add code in the <head> section of the page to load the necessary JavaScript files.
Add JavaScript code in the <head> section of the page to initialize the editor, and set its 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.
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.cfm 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': "cfm"
};
</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: 400,
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 actual code that performs these operations is different depending on the modules you have installed and you need to use with each specific control (e.g. You might want not to use HTML tidy capabilities for every control on your site).
You need to change the existing page to accomplish this task:
At the beginning of the page, you need to add
code that will include the ktml
class specific for the server model.
<cfinclude template="includes/ktm/ktml4.cfm">
After defining the main KTML
object properties, in order to set the modules to load, and additional
properties in the modules_props array, you must
add server-side code. This will create a new instance of the
ktml4 object, and use it to set modules and properties.
<cfscript>
ktml4_obj1 = Request.KTML4_CreateObject("ktml4");
ktml4_obj1.init("ktml1");
ktml4_obj1.setModuleProperty("filebrowser", "AllowedModule",
"true", false);
ktml4_obj1.setModuleProperty("file", "UploadFolder",
"uploads/files/", true);
ktml4_obj1.setModuleProperty("file", "UploadFolderUrl",
"uploads/files/", true);
ktml4_obj1.setModuleProperty("file", "AllowedFileTypes",
"doc, pdf, txt", true);
ktml4_obj1.setModuleProperty("media", "UploadFolder",
"uploads/media/", true);
ktml4_obj1.setModuleProperty("media", "UploadFolderUrl",
"uploads/media/", true);
ktml4_obj1.setModuleProperty("media", "AllowedFileTypes",
"mov, mpg, avi, mpeg, swf, wmv, jpg, jpeg, gif, png", true);
ktml4_obj1.setModuleProperty("filebrowser", "MaxFileSize",
"2000", true);
ktml4_obj1.setModuleProperty("filebrowser", "RejectedFolders",
".svn,.thumbnails", false);
ktml4_obj1.setModuleProperty("templates", "AllowedModule",
"true", false);
ktml4_obj1.setModuleProperty("templates", "UploadFolder",
"uploads/templates/", true);
ktml4_obj1.setModuleProperty("xhtml", "AllowedModule",
"true", false);
ktml4_obj1.setModuleProperty("xhtml", "xhtml_view_source",
"true", true);
ktml4_obj1.setModuleProperty("xhtml", "xhtml_save",
"true", true);
ktml4_obj1.setModuleProperty("spellchecker", "AllowedModule",
"true", false);
ktml4_obj1.setModuleProperty("css", "PathToStyle",
"includes/ktm/styles/KT_styles.css", true);
ktml4_obj1.Execute();
</cfscript>
Note: all of the properties used in the code above have the same significance
as the ones explained for the PHP server
model.
Creating a new instance of the KTML
object is done with the syntax code:
ktml4_obj1 = Request.KTML4_CreateObject("ktml4");
ktml4_obj1.init("ktml1");
Each module property is added by calling the setModuleProperty method of the ktml4 object. The function
syntax is:
ktml4_obj1.setModuleProperty(module_name, property_name, property_value,
export_to_Js);
After adding all properties for all modules you
want to use, the Execute method of the object must be invoked. This will
add all properties in the respective arrays, and will also generate an
unique identifier for the KTML control. The syntax of the method is:
ktml4_obj1.Execute();
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.