HOW TO INTEGRATE HTMLAREA WITH TWIKI
INTRODUCTION:
HTMLArea is a free, customizable online editor. It works inside your browser. It uses a non-standard features implemented in
Internet Explorer 5.5 or better for Windows and
Mozilla 1.3 or better (any platform), therefore it will only work in one of these browsers.
However it saves topics in
pure HTML so it should only be deployed if it is to be the
only editor used with topics.
Check out demo and more details at:
http://www.interactivetools.com/products/htmlarea/
NOTE: The mentioned website is no longer developing or distributing htmlarea. Because of the licensing (BSD-style),
http://xinha.python-hosting.com/ is continuing development. It should integrate with TWiki in the same way, but that needs to be tested. --
TsuDhoNimh - 20 Sep 2005
This document describes how it can be integrated with EXISTING TWiki (that already has pages in TWiki Text) as well as NEW Twiki Installation.
(I)
NEW TWIKI INSTALLATION:
For a NEW TWiki installation, there should be no problem with the standard install given in HTMLArea. Follow these instructions after installing TWiki successfully.
Procedure:
1. Download the source from
http://www.interactivetools.com/products/htmlarea/download.cgi
2. Install HTMLArea as per the standard installation instructions:
cd /var/www/html
unzip /path/to/archive/HTMLArea-3.0-rc1.zip
mv HTMLArea-3.0-rc1 htmlarea
find htmlarea/ -type f -exec chmod 644 {} \;
find htmlarea/ -type d -exec chmod 755 {} \;
find htmlarea/ -name "*.cgi" -exec chmod 755 {} \;
3. Try running the file www.yoursitename/htmlarea/index.html. If it works successfully, you are only 5 min away from integrating TWiki with HTMLArea. If it doesn't, check HTMLArea docs for more. They also have a forum:
http://www.interactivetools.com/iforum
4. Take backup of your edit.(skin).tmpl file. Open the file edit.(skin).tmpl that you are using in the edit screen.
5. Add the following code in the file, anywhere:
<script language="JavaScript">
<!--HIDE
var editor = null;
function initForm() {
editor = new HTMLArea("text");
// register the SpellChecker plugin
editor.registerPlugin(TableOperations);
// register the FullPage plugin
// remove comment in next line for Full Page plugin
// editor.registerPlugin(FullPage);
// register the SpellChecker plugin
// remove comment in next line for Spell Check plugin
//editor.registerPlugin(SpellChecker);
// add a contextual menu
editor.registerPlugin("ContextMenu");
setTimeout(function() {
editor.generate();
}, 500);
return false;
// editor.generate();
// document.main.text.focus();
}
//STOP HIDING-->
</script>
6. Find the textarea
<textarea id="text" name="text" wrap="virtual" rows="%EDITBOXHEIGHT%" cols="%EDITBOXWIDTH%">%TEXT%</textarea>
<!-- Add the ID tag if it is not present already
Change the rows="%EDITBOXHEIGHT%" cols="%EDITBOXWIDTH%" if you do not want these to be variable -->
7. Add the following lines after the
<script type="text/javascript">
_editor_url = "/htmlarea/";
_editor_lang = "en";
</script>
<script type="text/javascript" src="/htmlarea/htmlarea.js"></script>
<script type="text/javascript" src="/htmlarea/lang/en.js"></script>
<script src="/htmlarea/dialog.js" type="text/javascript"></script>
<script src="/htmlarea/popupwin.js" type="text/javascript"></script>
<script src="/htmlarea/plugins/TableOperations/table-operations.js" type="text/javascript"></script><script src="/htmlarea/plugins/TableOperations/lang/en.js" type="text/javascript"></script>
<script type="text/javascript">
HTMLArea.loadPlugin("TableOperations");
HTMLArea.loadPlugin("ContextMenu");
//HTMLArea.loadPlugin("FullPage");
//HTMLArea.loadPlugin("SpellChecker");
</script>
NOTE: _editor_url is the absolute path wher HTMLArea resides.
src is the absolute path where the scripts reside.
8. Add oLoad=initForm() on the body tag of the
HTML:
<body bgcolor="#dfdfdf" marginwidth="0" marginheight="0" leftmargin=0 topmargin=0 widthmargin=0 bottommargin=0 onLoad="initForm()" >
9. That's it ! HTMLArea will now work with NEW TWiki installation ! This will have the table operations and a right-click context sensetive menu activated.
10. You can have other plugins available: i.e. Full page, Spell Check and
CSS as per requirement. by uncommenting suitable lines of code.
(II) FOR EXISTING INSTALLATIONS:
If there is data already on your site, then consider the following before installing HTMLAREA.
Following are the advantages available now:
1. Extreme ease of editing with nearly all options right from FONT, fontsize, bold, italics, numbering, bullets, horizontal line etc right up to Tables, paragraph indentation etc.
2. The page is seen EXACTLY as it is seen on the VIEW. Images are in place, tables etc are as they were in view.
3. Content can be COPY-PASTED from MSWord/Internet Explorer or any other such application to the wysiwyg editor. Images can be copy pasted and their link is saved in the
HTML.
4. Keyboard short-cuts work
CTRL-A -- select all
CTRL-B -- bold
CTRL-I -- italic
CTRL-U -- underline
CTRL-S -- strikethrough
CTRL-L -- justify left
CTRL-E -- justify center
CTRL-R -- justify right
CTRL-J -- justify full
CTRL-1 .. CTRL-6 -- headings (<h1> .. <h6>)
CTRL-0 (zero) -- clean content pasted from Word
5. Old TWiki language will still work.
There is a button on the editor that toggles the
HTML source <> . On clicking that button, the processor becomes inactive and the area acts like any normal text area. So, the TWiki codes can be entered over there.
6. Rollback is easier. Just go to any previous version, select and copy the text from there and paste it in the edit area !
There are a few considerations, though.
1. The approach followed is that the TWiki code should be converted to
HTML and then fed to the HTMLAREA editor.
Due to this:
- The links no longer remain relative: The TWiki words like Main.UserName get converted to actual paths as /var/www/html/twiki/data/Main/UserName.
- The images no longer remain relative ( %ATTACHURLPATH% variable is lost)
- Diffs are not very...err.. intuitive.
2. Works only with IE 5.5+, Mozilla and Firefox. For other browsers, it will deprecate to normal text area and html code is seen.
3. For some plugins like Smilies plugin etc, the relative processing is lost and hard images are stored.
4. I have not been able to get in the < verbatim > tag to work flawless,
I've tried to use the functions takeOutVerbatim () and putBackVerbatim ()
I've tried to use < pre > tag and < xmp > tag as well.
If you are okay with these points, then here are the instructions:
1. Follow steps 1 thru 8 above to install HTMLArea. Changed 9th step is as follows:
9. Take backup of /twiki/bin/edit or edit.cgi or edit.pl (whatever your site convention is). Open the file
10. Find the following piece of code:
**************************************************************************************
if( $saveCmd eq "repRev" ) {
$text = TWiki::Store::readTopicRaw( $webName, $topic );
}
$text =~ s/&/&\;/go;
$text =~ s/</<\;/go;
$text =~ s/>/>\;/go;
$text =~ s/\t/ /go;
if( $TWiki::doLogTopicEdit ) {
# write log entry
&TWiki::Store::writeLog( "edit", "$webName.$topic", $extra );
***************************************************************************************
Change it as follows:
if( $saveCmd eq "repRev" ) {
$text = TWiki::Store::readTopicRaw( $webName, $topic );
}
#################ADD FOLLOWING CODE ##########################
#( $meta, $text ) = &TWiki::Store::_extractMetaData( $webName, $topic, $text );
#$text =~ s/%_(.)_%/%__$1__%/go;
#my @verbatim = ();
#$text = &TWiki::takeOutVerbatim( $text, \@verbatim );
#$text =~ s/ {3}/\t/go;
$text = &TWiki::handleCommonTags( $text, $topic );
$text = &TWiki::getRenderedVersion( $text );
#$text = &TWiki::handleCommonTags( $text, $topic );
#$text = &TWiki::putBackVerbatim( $text, "pre", @verbatim );
#$text = &TWiki::putBackVerbatim( $text, "verbatim", @verbatim );
#$text = &TWiki::putBackVerbatim( $text, "xmp", @verbatim );
#$text = &TWiki::encodeSpecialChars( $text );
#################ADD TILL HERE ###############################
##############COMMENT NEXT FOUR LINES ########################
#$text =~ s/&/&\;/go;
#$text =~ s/</<\;/go;
#$text =~ s/>/>\;/go;
#$text =~ s/\t/ /go;
##############COMMENT TILL HERE #############################
if( $TWiki::doLogTopicEdit ) {
# write log entry
&TWiki::Store::writeLog( "edit", "$webName.$topic", $extra );
***************************************************************************************
11. Done !
Also, I have attached sample files here:
- edit: Modified EDIT Perl file for HTMLArea
Hope this helps.
Contributors:
--
ManishKaduskar - 24 Jul 2004
Discussions
This documentation should be shipped in Cairo.
--
CrawfordCurrie - 24 Jul 2004
I have a question: unless you are very careful, how much is this going to screw things up when you edit pages where preferences are set? Should some note to this effect be included in the documentation?
--
ClaussStrauch - 24 Jul 2004
Thanks Manish for the detailed instructions
Crawford, I do not recommend to rush this doc into Cairo before we know more about limitations. We can however put a pointer to this doc into the Cairo docs, which is just did prominently in
TWikiInstallationGuide.
--
PeterThoeny - 25 Jul 2004
Thank you for the encouragement. Feels good
All the lines that actually change code are the two functions:handleCommonTags and getRenderedVersion. I don't think it will screw the edit preferences page.
Has anyone actually implemented it and found it useful ?
--
ManishKaduskar - 29 Jul 2004
I had an existing installation based on the March 2004 beta code. I installed the html editor (HTMLArea-3.0-rc1.zip) and made the suggested changes. Things seemed to be working fine till I tried to edit
TWikiPreferences. That seemed to mess up all the variables defined there - the ones enclosed in %% - and by consequence, the installation. I had to rely on a previous revision of the file to bail out. It would help if the editor supports the TWiki syntax. While I understand that this is a
WYSIWYG editor and the html source isn't important - but I noticed that the editor removed all the blank spaces in the html code rendering it almost unreadable. Another thing - and this could have something to do be with my setup only - but I couldn't use the mouse to select existing code and make changes. I had to fall back on selecting the code with the keyboard.
--
SriramAcharya - 23 Aug 2004
Limitations:
- As mentioned about, editing preferences breaks them. Even a shiny new wiki has preference files, so this is a significant problem.
- The output of HtmlAreaEditor is one big long line of HTML code. This renders the wiki diffs somewhat useless.
- I don't know how HTML-aware the wiki really is, but I would guess that some automated tools will not read the HTML. The big example here is the preferences, which would probably be ignored if you converted them to HTML.
Now, that said, I'm working on setting up a wiki where I want to use
HtmlAreaEditor. I've been debating on what to change to make it to work:
- HtmlAreaEditor itself will have to be changed so it outputs nicer HTML.
- I need to either make HtmlAreaEditor output WikiML, or make TWiki more HTML-aware and convert the preferences pages accordingly. I'm not sure which would be easier, but as my users don't know any WikiML and many of them do know some HTML, I suspect I'll be doing the latter. Any pointers would be appreciated.
--
TerriOda - 20 Sep 2004
You might want to take a look at
KupuEditorAddOn. It's not a solution yet, but it is being activly developed.
--
SamHasler - 20 Sep 2004
Regarding addressing the limitations, i blv we could follow the xwiki approch and have a seperate editHtml button(or link) that would invoke the htmlarea and leave the existing edit as is, so that we dont endup with the problem of messing up the pref file.
--
PremnathNarayanan - 09 Nov 2004
As seen in
KupuEditorAddOnDev, the TWiki/Kupu integration work seems to have stopped.
I see a
WYSIWYG editor as an important TWiki enhancement. We should get one sooner then later; it is a competitive question / makes TWiki more appealing to prospects.
Anyone interested in working on a high priority integration? This means to bring the
HtmlAreaEditor integration
or the
KupuEditorAddOn to production quality.
--
PeterThoeny - 02 Mar 2005
I'm part way through a hack to
HtmlAreaEditor that will make it translate
TwikiML <->
HTML on the fly, avoiding the many side effects that using straight
HtmlAreaEditor or
KupuEditorAddOn caused when going back and forth between plain text editing and
WYSIWYG editing. I designed it to need minimal changes to
HtmlAreaEditor itself, and most of it functions as a regular
HtmlAreaEditor plugin.
The biggest unaddressed problem with my design is plugins. The only way I can see it work at all is making it possible to add plugins to the filters. The second biggest problem is that
HtmlAreaEditor allows the creation of
HTML that can't be cleanly expressed in
TwikiML. My solution to that is to leave anything that can't be cleanly expressed in
TwikiML as
HTML, so you can still get the advantages of
TwikiML as long as you don't get too fancy. A side effect of this is that if you create a page in plain text that uses
HTML, the first time someone uses my editor, some of it may get translated out of
HTML. I don't see that as a good thing, so I'm toying with ways around that.
--
EricSchwertfeger - 04 Mar 2005
Eric, what you discribe does not strike me as a disadvantage. For one, most users that would use this editor will not get too fancy anyways. Secondly, if some
HTML is translated into
TWikiML even if the user had not originally planned that, this might be consideredc a benefit.
--
ThomasWeigert - 04 Mar 2005
I know that it's pretty simple in
HtmlAreaEditor to turn toolbar features off and on. One possibility would be to create a stripped-down version that
only offers the smaller, simpler set of
TWikiML-compatible formatting. I know some users of
HtmlAreaEditor do this anyway so as not to overwhelm new users.
One other thought regarding plugins is that it would be great to design a wizard-type interface for inserting
TWikiVariables. I imagine a pop-up dialog box that allows you to select a
TWikiVariable and then offers attribute options for the selected variable. I know this is not a high priority but would be a natural TWiki extension to the
HtmlAreaEditor interface. And I think I've seen some tools to simplify creation of javascript dialog boxes so it's something that perhaps some others of us can help with.
Finally, I just want to really encourage you Eric in your efforts! If you pull this off, you will definitely have earned your place among the pantheon of
TWikiHeros.
--
LynnwoodBrown - 04 Mar 2005
The problem with simply disabling things is that you wind up loosing a lot of functionality.
HtmlAreaEditor uses the same widget to create an indented paragraph as it does a nested list, even though the results are implemented in a different way. It would involve replacing just about all of the existing widgets with widgets that are context-sensitive to
TWikiML needs.
I had also thought of extensions to the markup that could be used to express anything that
HTML can express without complicating the existing
TWikiML (that is, anything that can be expressed now doesn't change, it just gets complicated fast once you go beyond what can be expressed now). The two main concepts were a mechanism to allow a number of lines to be treated as part of a single line, for example, a table to be included in a list, or vica-versa, and by necessity, this would have to be recursive. I hadn't implemented anything yet, but I was thinking something as simple as [>>>] to start a subsection and [<<<] to end it. The second concept was a way to specify any html attribute for a specific element. This got tricker, but I think I see how it could work. You'd need a variable %HTMLATTRIB% or the like, and it would add those permitted attributes to the next
HTML element. Not completely thought out, as tables get tricky. The biggest win in my mind to doing these is that if you can express all
HTML as
TWikiML and parse it out so that there's no
HTML in the store, all
HTML is generated by the parser, and javascript injection attacks become much more difficult to achieve.
At any rate, any extensions to
TWikiML would be off topic for this page, so I think when I get the chance, I'll dig around for the right page for that discussion.
--
EricSchwertfeger - 04 Mar 2005
Is there any chance that the new
MultiEditPlugin (or
RecursiveRenderPlugin) might help with the tables-within-list and similar issues? No need for detailed response if this is way off base - just wanted to make sure you were aware of some of TWiki's latest and greatest features.
--
LynnwoodBrown - 04 Mar 2005
Never assume I know everything, I'm really rather new to TWiki in general. Example 1 of
RecursiveRenderPlugin is exactly the effect and syntax I was thinking of using [>>>] and [<<<] for, just with different tokens. Glad to know I don't have to code it, but it will make that a required plugin for use of
HtmlAreaEditor if I use it. Maybe as an option, or have some way for the
HtmlAreaEditor to know what plugins are installed, and have it use raw
HTML if
RecursiveRenderPlugin isn't installed.
I should warn you right now, in all fairness, that I have a tendency to overcommit myself. I haven't touched this project in almost two months because I've been too busy, but interest in it encourages me to get back to work on it.
The exact status of this project is that I had the mods to
HtmlAreaEditor finished and tested to allow a plugin translation filter, had very basic filters written but not translated to
HtmlAreaEditor plugins. So, I need to accomplish the following:
- Improve the translator in both directions to handle some problem cases.
- Add some way to add hooks to the translator so that plugins can provide a way to alter the translation for those features it provides.
- learn how to write HtmlAreaEditor plugins, and turn the translator into a plugin.
- Add toolbar elements for TWikiML specific features.
I think that's it, but that's not a short list at any rate. Sigh.
--
EricSchwertfeger - 04 Mar 2005
Eric - I wonder if there's room for others helping out. Are the translaters modular enough that several folks could work on this effort? There's enough demand about this feature that I imagine you might find some ready volunteers if the work lends inself to any kind of delegation.
--
LynnwoodBrown - 04 Mar 2005
Part of the problem I have with figuring out how to do the plugins is that the two translators are currently
quite monolithic, so there's not much chance of delegation there. I'll spend some time this weekend getting back up to speed on this project. Goals will be:
- Design a non-hacky way to allow plugins to the interpreter. I've designed plugins for systems before, but never anything requiring this level of cooperation between plugins, so any advice is welcome.
- Define exactly how to handle some of the problem issues, so that if anyone does join in, we'll all have a basic understanding of the methedology. Right now, I'm heavily overloading the class property of elements to indicate things like "this link is a forced wikiword" or "this is a variable" because it's the one way to track things that doesn't seem to get clobbered by cut and paste. If nothing else, I need to standardize and document this kludge.
- Look into how HtmlAreaEditor plugins can interact with other plugins, so we can have HtmlAreaEditor plugins that correspond to each plugin installed in TWiki. That seems better than my current approach of hardcoding support for select plugins into the translator.
Even if I can't figure out a good way to make plugins for the translators, there's still other parts that can be delegated once I've got the processes defined, but without those definitions, deletating anything effectively will be impossible.
--
EricSchwertfeger - 04 Mar 2005
After spending two weekends in bed sick, I finally got around to looking at this again. Interesting timing, as I found out that this weekend the main developer of HTMLArea axed the project.I did a little research into alternates, and this is what I came up with.
HTMLArea
Pros:
- popups are done in HTML, not by openning another web browser window.
Cons:
- Development was slow (almost a year between release candidates) before the project was dropped. Dynarch.com say that they'll continue development.
fckeditor
Pros:
Cons:
- popups in another browser window.
TinyMCE
Pros:
- definitely loads faster than either of the other two.
- also actively developed.
- appears to already support alternate translators.
Cons:
- spellcheck is IE-only.
- no context-sensitive menus (expected in the next release).
- again, popups are in browser windows.
I need to do more research, but so far, I'm rather impresses with
TinyMCE. The load times are fast enough that I've never suspected that the window was hung even when it wasn't.
If anyone wants to look at the other editors and offer input, it would be more than welcome. At this time I'm certain that I'm moving away from HTMLArea, but that may be that I'm still in shock over it getting cancelled. I also never did feel comfortable with KupuEdit, though in light of the fact that only HTMLArea did popups without another browser window, the editor space dedicated to things that should be in dialogs is making more sense now.
--
EricSchwertfeger - 15 Mar 2005
Please guys, continue on the Wysiwyg!
I've also seen TMedit at work, is better than TinyMCE as far as my Joomla requirements are.
--
WimJanin - 14 Oct 2005
WimJanin, have you taken a look at the Wysywig plugin? It uses Kupu edit (which works much better as part of this plugin rather than the standalone
KupuEditorAddOn). Also note that both Jot and
SocialText have opensourced their
WYSIWYG editors (the
SocialText editor, which includes wiki-specific features is available as part of the JSAN collection, and Jot editor is available as part of the dojo toolkit).The
SocialText editor was designed for Wiki use (you can even toggle between
WYSIWYG html and
WikiML).
As I understand it, the way the Wysiwig Plugin is designed, it should be fairly simple to create additional plugins with a dependancy on that plugin that use different editors.
--
EricSchwertfeger - 15 Oct 2005