Tags:
create new tag
, view all tags

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/&/&amp\;/go;
   $text =~ s/</&lt\;/go;
   $text =~ s/>/&gt\;/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/&/&amp\;/go;
    #$text =~ s/</&lt\;/go;
    #$text =~ s/>/&gt\;/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 smile

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 smile

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:

  • actively developed.

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

Edit | Attach | Watch | Print version | History: r25 < r24 < r23 < r22 < r21 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r25 - 2005-10-15 - EricSchwertfeger
 
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2015 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.