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.php 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 options regarding the database
and screen date and time formats, and the file and folder creation rights
exist. You need to add the others, above the line which contains the ending
comment:
//End Variable definitions comment
First define the preferred image library. If you
have ImageMagick installed, you should set it as the default library (it
offers superior quality). Enter the following code to configure the preferred
library:
$KT_prefered_image_lib = "imagemagick";
Note: To learn more about image editing in KTML,
see the Configure Image Library
option.
Next you must specify the path to the ImageMagick
library:
$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:
$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 spellchecking.
KTML 4 uses an external library
- aspell - for spell checking. You must define the path to the library
in the configuration file:
$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 basic KTML options and files are all set, and you can start modifying the page to replace the textarea with the KTML control.
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 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.
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.php 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': "php"
};
</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 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
<?php
session_start();
require_once('includes/ktm/ktml4.php');
?>
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
<?php
$ktml4_obj1 = new ktml4("ktml1");
$ktml4_obj1->setModuleProperty("filebrowser", "AllowedModule",
"true", false);
$ktml4_obj1->setModuleProperty("file", "UploadFolder",
"uploads/files/", true);
$ktml4_obk1->setModuleProperty("file", "UploadFolderUrl",
"uploads/files/", true);
$ktml4_obj1->setModuleProperty("file", "AllowedFileTypes",
"doc,pdf,txt", true);
$ktml4_obj1->setModuleProperty("media", "UploadFolder",
"uploads/media/", true);
$ktml4_obk1->setModuleProperty("media", "UploadFolderUrl",
"uploads/media/", true);
$ktml4_obj1->setModuleProperty("media", "AllowedFileTypes",
"bmp,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->setModuleProperty("hyperlink_browser", "ServiceProvider",
"hyperlink_service.php", true);
$ktml4_obj1->Execute();
?>
</script>
Creating a new instance of the KTML object is done with the syntax code:
$ktml4_obj1 = new ktml4("ktml1");
The ktml4 object parameters are:
The name of the KTML control on the main page in this case, 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);
The method arguments are:
module_name the name of the module for which the property is set.
property_name the name of the property to set the value for.
property_value the value of the property to set
export_to_Js whether the property will also be saved in the JavaScript module_props array as well
The modules which you must configure are:
filebrowser - this module is responsible for the Remote File Explorer. Its main properties are:
AllowedModule - this property must be set for all modules, to integrate them into KTML's security layer. In short, it means that the module is allowed for execution.
UploadFolder - set the path to the folder where files will be stored after upload.
AllowedFileTypes - specify the extensions allowed for upload for document type files or media files, based on the selected sub-module.
MaxFileSize - the maximum allowed size for a file to be uploaded.
RejectedFolders - specify which folders will be hidden from the user when using the Remote File Browser.
templates - this modules manages template uploads. Templates are HTML files that can be used to build content upon. This module only has two properties:
AllowedModule - this property must be set for all modules, to integrate them into KTML's security layer. In short, it means that the module is allowed for execution.
UploadFolder - set the path to the folder where template files will be stored after upload.
xhtml - this module ensures XHTML compliance of the generated HTML code:
AllowedModule - this property must be set for all modules, to integrate them into KTML's security layer. In short, it means that the module is allowed for execution.
xhtml_view_source - this determines whether code is displayed XHTML - compliant when switching from design to source view. It can be true or false
xhtml_save - specify whether the saved code will be XHTML compliant.
spellcheck - this module only has the AllowedModule property to specify if it is safe to run or not.
css - this module is responsible for the Cascading Sheet Style used in the editor. It only has one property: PathToStyle which takes as value the path to the CSS file to use.
hyperlink_browser - this module uses a web service to populate a drop-down menu of links to use. The only property is ServiceProvider which takes as value the URL (absolute or relative) to the web service that returns the links.
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.