| |
| |
In this tutorial you will learn how to replace the default text editor for the Nucleus content management system with the KTML4 online HTML editor. Nucleus is a free content management system . It allows users create content to publish online using a basic textarea and some HTML tags.
The files you will create or modify during this tutorial can also be found in the downloaded package, inside the /documentation/CMS-Integration/Nucleus/ folder. To quickly set up your content management system to use the KTML 4 online HTML editor, simply copy the files in this folder to their respective locations.
In order to follow this tutorial you need:
The Nucleus package. You can download a free copy here.
The KTML4 zip file with the editor sources. You can download it here [link: download site].
Some knowledge of PHP and Javascript is recommended, but not mandatory. All code is provided.
A text editor.
Nucleus CMS uses a plugin system to enable the use of 3rd party bits of code. A plugin is made up of a PHP file, which has a well-defined structure, and optionally, one or more folders to accommodate any required files. After such a plugin has been created, it will be displayed in the plugins section of the administrative back-end.
To create a new plugin for Nucleus CMS which replaces the default editor with the KTML4 online editor, follow the next steps:
Open the <site_root>\nucleus\plugins\ folder with a file explorer.
Note: Replace <site_root> with the root folder of the Nucleus CMS installation.
Create a new folder named ktml. Unzip the includes folder and its contents from the downloaded package in the newly created folder.
In the <site_root>\nucleus\plugins\ folder create a new file named NP_ktml.php. This file will contain the code that registers KTML4 to the particular actions. The NP_ prefix is mandatory, as this will allow Nucleus CMS recognize the plugin.
A Nucleus plugin is in fact a class that implements the NucleusPlugin interface. This class contains methods that provide plugin information, as well as ways to associate events with plugin functions. Some of the default methods that allow retrieving plugin information are getName, getAuthor, getURL, getDescription, getVersion, etc, while some of the events to which the plugin will register itself are AdminPrePageHead and AdminPrePageFoot.
Registering the plugin to the AdminPrePageHead event will load the required KTML4 Javascript files, CSS styles and will initialize the KTML4 object with the default properties. All of this takes place only when the page is set to add or edit an event (through the action URL parameter). Registering the KTML4 plugin to the AdminPrePageFoot event will allow creating a new instance of the KTML4 editor object if an item is added or edited. The NP_ktml.php file will contain code for these two events, as well as other functions to perform various functions.
To add code to the NP_ktml.php file, open it in a text editor. First you must open the PHP tag, and declare the class - it will have the same name as the file. Then check if the selected Nucleus language exists or not; if not, english is selected:
<?php
class NP_ktml extends NucleusPlugin {
function NP_ktml() {
$available = array('english');
$this->language = getLanguageName();
if (!in_array($this->language,$available)) {
$this->language = 'english';
}
}
Next define the class methods that will display plugin related information: plugin name, author, homepage URL, version
function getName() {
return 'KTML 4';
}
function getAuthor() {
return 'InterAKT Online';
}
function getURL() {
return 'http://www.interaktonline.com/';
}
function getDescription() {
return $this->I18N('description');
}
function getVersion() {
return '0.2';
}
function getMinNucleusVersion() {
return '300';
}
function supportsFeature($what) {
switch($what) {
case 'SqlTablePrefix':
return 1;
default:
return 0;
}
}
The next function performs the installation of the KTML4 editor. It will add a new entry in the Settings dialog where you can choose to use the KTML4 editor or no visual editor at all. It also disables the automatic conversion of line breaks:
function install() {
// create plugin options (per-blog options)
$this->createMemberOption('editormode',$this->I18N('editormode'),'select','yes',$this->I18N('opt_editormode'));
// standard textmode settings
$this->createOption('enable_br', $this->I18N('enable_br'), "yesno", "yes");
$this->setLinebreakConversion(0); // disable auto-linebreak conversions
// no javascript editbar
mysql_query("UPDATE ".sql_table('config')." SET value='1' WHERE name='DisableJSTools'");
}
function setLinebreakConversion($mode) {
$res = mysql_fetch_object(sql_query("SELECT bconvertbreaks FROM ".sql_table('blog')));
if ($res->bconvertbreaks != $mode) {
mysql_query("UPDATE ".sql_table('blog')." SET bconvertbreaks=".$mode);
}
}
The next function is used when uninstalling the KTML4 editor, and it will restore the standard settings:
// restore to standard settings
function unInstall() {
$this->setLinebreakConversion(1);
mysql_query("UPDATE ".sql_table('config')." SET value='2' WHERE name='DisableJSTools'");
}
The getEventList method allows querying the plugin for the events to which it is registered:
function getEventList() {
return array(
'AdminPrePageHead', // include javascript on admin add/edit pages
'BookmarkletExtraHead', // include javascript on bookmarklet pages
'PreSendContentType', // we need to force text/html instead of application/xhtml+xml
'AdminPrePageFoot'
);
}
The rest of the functions are used by the event registration system, to create the <script> tags that include the Javascript editor file, the CSS link tag or the Javascript KTML4 initialization code. Also, code that replaces the standard element with the editor is added. The code is:
function event_BookmarkletExtraHead(&$data) {
$this->_getExtraHead($data['extrahead']);
}
function event_AdminPrePageHead(&$data) {
$action = $data['action'];
if (($action != 'createitem') && ($action != 'itemedit')) {
return;
}
$this->_getHeadContent($data['extrahead']);
}
function _getHeadContent(&$extrahead) {
global $CONF, $memberid, $memberadmin, $member;
if (empty($memberid)) {
$memberid = $member->id;
}
if (empty($memberadmin)) {
$memberadmin = $member->admin;
}
$media_path = '';
if ($memberadmin != '1') {
$media_path = $memberid . '/';
}
// get member settings
$editorMode = $this->getMemberOption($memberid, 'editormode');
$baseUrl = $this->getAdminURL();
$basePath = $this->getDirectory();
$ediCode = '';
if ($editorMode != 'no') {
// To avoid conflicts if a other user use only textmode we must set this on all calls
$CONF['DisableJsTools'] = 1; // overrule simple global settings
$this->setLinebreakConversion(0);
$ediCode .= '
<script src="'.$baseUrl.'includes/common/js/base.js" type="text/javascript"></script>
<script src="'.$baseUrl.'includes/common/js/utility.js" type="text/javascript"></script>
<script src="'.$baseUrl.'includes/ktm/core/ktml.js" type="text/javascript"></script>
<script src="'.$baseUrl.'includes/resources/ktml.js" type="text/javascript"></script>
<script src="'.$baseUrl.'includes/ktm/core/modules.js" type="text/javascript"></script>
<link href="'.$baseUrl.'includes/ktm/core/styles/ktml.css" rel="stylesheet" type="text/css">
<script type="text/javascript">
ktml_init_object = {
"debugger_params": false,
"path": "plugins/ktml/includes/ktm/",
"server": "php"
};
</script>
<script type="text/javascript">
inputbody_config = {
width: 700,
height: 500,
show_toolbar: "load",
show_pi: true,
background_color: "#ffffff",
strip_server_location: true,
auto_focus: true,
module_props: { },
buttons: [
[1, "standard", ["cut", "copy", "paste", "undo", "redo", "find_replace", "toggle_visible", "spellcheck", "toggle_editmode", "toggle_fullscreen", "help"]],
[1, "formatting", ["bold", "italic", "underline", "align_left", "align_center", "align_right", "align_justify", "numbered_list", "bulleted_list", "outdent", "indent", "clean_menu", "foreground_color", "background_color", "superscript", "subscript"]],
[2, "styles", ["heading_list", "style_list", "fonttype_list", "fontsize_list"]],
[2, "insert", ["insert_link", "insert_anchor", "insert_table", "insert_image", "insert_file", "insert_template", "horizontal_rule", "insert_character"]],
[3, "form", ["insert_form", "insert_textfield", "insert_hiddenfield", "insert_textarea", "insert_checkbox", "insert_radiobutton", "insert_listmenu", "insert_filefield", "insert_button", "insert_label", "insert_fieldset"]] "insert_filefield", "insert_hiddenfield", "insert_fieldset", "insert_label"]]
]
}
';
require_once($basePath . 'includes/ktm/ktml4.php');
ob_start();
$ktml_obj1 = new ktml4("inputbody");
$ktml_obj1->setModuleProperty("filebrowser", "AllowedModule", "true", false);
$ktml_obj1->setModuleProperty("filebrowser", "MaxFileSize", "2000", true);
$ktml_obj1->setModuleProperty("filebrowser", "RejectedFolders", ".svn,.thumbnails", false);
$ktml_obj1->setModuleProperty("file", "UploadFolder", "uploads/files/", false);
$ktml_obj1->setModuleProperty("file", "UploadFolderUrl", "uploads/files/", true);
$ktml_obj1->setModuleProperty("file", "AllowedFileTypes", "doc,pdf,txt", true);
$ktml_obj1->setModuleProperty("media", "UploadFolder", "uploads/media/", false);
$ktml_obj1->setModuleProperty("media", "UploadFolderUrl", "uploads/media/", true);
$ktml_obj1->setModuleProperty("media", "AllowedFileTypes", "bmp,mov,mpg,avi,mpeg,swf,wmv,jpg,jpeg,gif,png", true);
$ktml_obj1->setModuleProperty("templates", "AllowedModule", "true", false);
$ktml_obj1->setModuleProperty("templates", "UploadFolder", "uploads/templates/", false);
$ktml_obj1->setModuleProperty("xhtml", "AllowedModule", "true", false);
$ktml_obj1->setModuleProperty("xhtml", "xhtml_view_source", "true", true);
$ktml_obj1->setModuleProperty("xhtml", "xhtml_save", "true", true);
$ktml_obj1->setModuleProperty("spellchecker", "AllowedModule", "true", false);
$ktml_obj1->setModuleProperty("css", "PathToStyle", "includes/ktm/styles/KT_styles.css", true);
$ktml_obj1->setModuleProperty("hyperlink_browser", "ServiceProvider", "includes/ktm/hyperlink_service.php", true);
$ktml_obj1->setModuleProperty("date", "AllowedModule", "true", false);
$ktml_obj1->Execute();
$ediCode .= ob_get_contents();
ob_end_clean();
$ediCode .= '
</script>
';
} else {
$CONF['DisableJsTools'] = 2;
$linebreak_conversion = $this->getOption('enable_br') == 'yes' ? 1 : 0;
$this->setLinebreakConversion($linebreak_conversion);
}
$extrahead .= $ediCode;
}
function event_AdminPrePageFoot(&$data) {
$action = $data['action'];
if (($action != 'createitem') && ($action != 'itemedit')) {
return;
}
$this->_startKTMLinstance();
}
function _startKTMLinstance() {
echo '<script type="text/javascript">
ktml_inputbody = new ktml("inputbody");
</script>
';
}
function event_PreSendContentType(&$data) {
$pageType = $data['pageType'];
if ($pageType == 'skin') {
return;
}
if ( ($pageType != 'bookmarklet-add') && ($pageType != 'bookmarklet-edit') && ($pageType != 'admin-createitem') && ($pageType != 'admin-itemedit') ) {
return;
}
if ($data['contentType'] == 'application/xhtml+xml') {
$data['contentType'] = 'text/html';
}
}
// I18N -> short form for getLanguageTranslation
// Feel free to translate this in your language and send it to me. mailto:alfmiti@gmx.at
function I18N($key) {
$lng['opt_editormode']['english'] = 'No WYSIWIG Editor|no|KTML Editor|yes';
$lng['enable_br']['english'] = 'Enable automatic linebreak conversion in standard textmode';
$lng['description']['english'] = 'HTML-WYSIWIG editor interface. Upon install, this plugin '.
'disables the default javascript toolbar and linebreak conversion ';
return $lng[$key][$this->language];}
}
}
?>
After copying the required KTML4 files into the ktml folder and creating the NP_ktml.php file, you can start using the new editor.
After creating the new plugin, you must make it available from the Nucleus administrative section:
Load the home page of your Nucleus installation in a browser and login with the administrator's account.
From the administrative option's menu, the Management category select the Plugins menu entry:
Below the list of installed plugins, in the Install new plugin drop-down menu select the ktml option, and press the Install Plugin button:
After the installation completes, the page will refresh and display a new entry in the list of installed and available plugins.
From the menu on the right side you can uninstall the extension or edit its properties.
KTML4 has been completely integrated with the content management system. You can test it out by trying to add a new item (on the Administrative homepage click the Add item link):
You will notice that the KTML 4 interface does not look perfect. This is due to the style system in Nucleus which uses general definition - styles are applied on general td, table or body tags - which have little significance. To fix this issue, and have the KTML editor interface display properly, you must alter the Nucleus CSS style sheet file as explained further. This will also affect the Nucleus interface, which is why it is recommended that you create more specific classes and apply them on the specific Nucleus elements.
To alter the Nucleus style sheet, follow the next steps:
Open the nucleus\styles\bookmarklet.css file with a text editor.
Locate the table definition. Its code block should resemble the following:
table {
border: none;
width: 95%;
border-collapse: collapse;
margin-bottom: 10px;
margin-top: 10px;
}
You have to remove the border, width, margin-bottom and margin-top attributes from this definition.
Next locate the th tag redefinition, which is as follows:
th, td {
padding: 4px;
empty-cells: show;
}
You must remove the padding: 4px; line from this definition.
Find the .contentblock class definition:
.contentblock {
background: #ddd;
height: 400px;
overflow: auto;
padding: 1px;
margin: 0px;
vertical-align: top;
}
You can safely remove the overflow:auto; attribute. If left, it will force all pop-ups that are loaded from the user interface will display beneath the actual toolbar. To preserve the Nucleus design, you should also remove the height:400px; line.
The redefinition of the H1 and H2 styles in this file only affects how the first two items are displayed in KTML's Format drop-down menu. If you want to accurately display the styles within the editor, remove these two definitions entirely:
h1 {
border-bottom: 1px dotted gray;
font-size: medium;
color: #596d9d;
}
h2 {
font-size: 1.5em;
color: gray;
margin-top: 0px;
padding-top: 0px;
padding-bottom: 0px;
margin-top: 0px;
}
The last thing you have to change is the definition for the standard td tag. In order for KTML to display correctly, you must remove this definition entirely. This affects the Nucleus styling however. In order to fix both problems, simply rename the td class to .mytd - with the preceding dot - and edit the pages you want the td to use these style rules. This way, the <td> tag definition:
td {
background: #fff;
order: 1px solid #ddd;
ont-size: small;
ertical-align: top;
ext-align: left;
}
Must change into something like this:
.myTD{
background: #fff;
border: 1px solid #ddd;
font-size: small;
vertical-align: top;
text-align: left;
}
Now save the css file and close it. When you preview the post editing or adding once more, the editor will display correctly.