Tags:
javascript1Add my vote for this tag create new tag
view all tags

TWiki JavaScript refactoring

A growing number of TWiki skins and plugins make use of JavaScript . TWiki provides a basic JavaScript library with twiki.js that offers a number of functions for pop-up windows, CSS class manipulation, WikiWord checking and creation, query string querying and cookie reading and setting.

Some things bug me with twiki.js:

  • TWiki.PageQuery is the only class with proper namespace, all other functions lack a namespace. A function with the same name from some contrib or plugin will overwrite a TWiki function leading to non-functioning code.
  • Private methods are exposed. This makes it unclear what function should be called and what functions are used internally.

Proposal

There is need for code refactoring. Not the code of the functions, but the way the functions are presented to the outer world.

Proper packaging of functions will:

  • Reduce fear for function name clashes
  • Make it easier to decide what functions to call
  • Create a stable js API
  • Provide better documentation ("classes" will become functional modules with a better interface)
  • Set JavaScript coding standards for TWiki code

To ease the pain of migrating I propose to create a new JavaScript file named twikilib.js and to deprecate twiki.js. At a later stage we can decide when to lift support from twiki.js (think years instead of months).

Changes

What will change for users of twiki.js?

The code that is now in one file will be distributed in separate files, each one strongly focused on an area. Users may need to include a number of files:

<script type="text/javascript" src="%PUBURLPATH%/%TWIKIWEB%/TWikiJavascripts/twikilib.js"></script>
<script type="text/javascript" src="%PUBURLPATH%/%TWIKIWEB%/TWikiJavascripts/twikiFunction.js"></script>
<script type="text/javascript" src="%PUBURLPATH%/%TWIKIWEB%/TWikiJavascripts/twikiPref.js"></script>

Functions calls will be different:

  • instead of launchWindow() use twiki.Window.openPopup()
  • instead of addLoadEvent(myFunc) use twiki.Event.addLoadEvent(myFunc)
  • and so on...

Proposed classes

Open for discussion:

Status Class name Function area Current functions New functions
Done twiki namespace none  
Done twiki.Window pop-up window related launchTheWindow openPopup
Done twiki.Event event handling addLoadEvent  
Done twiki.Form form initialization and handling initForm (empty, perhaps not needed at this level) formData2QueryString
Done twiki.HTML HTML manipulation insertHtml setHtmlOfElementWithId, setHtmlOfElement, getHtmlOfElementWithId, getHtmlOfElement, clearElementWithId, clearElement, deleteElementWithId, deleteElement, insertAfterElement, insertBeforeElement, replaceElement, setNodeAttributesInList, setElementAttributes
Done twiki.Function inheritance extendClass  
Done twiki.CSS CSS class manipulation removeClass, addClass, replaceClass, getClassList, setClassList, applyToAllElements, hasClass  
Done twiki.Array Array utility methods indexOf remove, convertArgumentsToArray, indexOf
Done twiki.String String utility methods capitalize, isWikiWord, removeSpaces, removePunctuation, removeSpacesAndPunctiation, makeWikiWord  
  twiki.String.PageQuery (is not used by any code) query string parsing TWiki.PageQuery, TWiki.PageQuery.prototype.getValue, TWiki.PageQuery.prototype.getParameters, TWiki.PageQuery.prototype.getLength  
Done twiki.Prefs writing TWiki ui variables to cookies; layer on top of TWiki.Cookie cookie reading and writing setPref, getPref, getPrefValueFromPrefList, getPrefList, _writePrefValues, _getPrefCookie, _getKeyValue, _getKeyValueLoc; getCookieVal, FixCookieDate, GetCookie, SetCookie, DeleteCookie  

Development

Bugs:Item3064

Unit tests

See TestCases/TestCaseTWikiJavascripts. Complete:
  • twiki.Form
  • twiki.HTML

-- Contributors: ArthurClemens - 27 Oct 2006

Discussion

Note: Last date to argue against this is 10 Nov 2006 per process. Please do not make this topic a generic discussion on javascript. Discuss only the actual proposal. Ie. code refactoring and unique namespace. I would think most will agree that this proposal is a good thing.

-- KennethLavrsen - 06 Nov 2006

no argument smile good work Arthur, I'm looking forward to what we do for 4.2

-- SvenDowideit - 06 Nov 2006

Refactoring is done. Documentation written. Unit tests run.

-- ArthurClemens - 30 Nov 2006

Is there still time for adding a function like addUnloadEvent for 4.2 ? Maybe it was done already?

-- StephaneLenclud - 02 Jul 2007

It can be added if you also write the test case, in TestCases.TestCaseTWikiJavascripts.

-- ArthurClemens - 02 Jul 2007

I'm guessing it should be a simple duplication of the code we used for addLoadEvent so there should be no much thinking involved. I'll see if I can find that code and test cases in the SVN repository.

-- StephaneLenclud - 03 Jul 2007

BasicForm
TopicClassification TWikiDevDoc
TopicSummary Refactor the TWiki JavaScript library twiki.js by wrapping the functions into namespace classes
InterestedParties

RelatedTopics

Edit | Attach | Watch | Print version | History: r19 < r18 < r17 < r16 < r15 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r19 - 2007-07-03 - StephaneLenclud
 
  • 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-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.