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 |
|
twiki |
namespace |
none |
|
|
twiki.Window |
pop-up window related |
launchTheWindow |
openPopup |
|
twiki.Event |
event handling |
addLoadEvent |
|
|
twiki.Form |
form initialization and handling |
initForm (empty, perhaps not needed at this level) |
formData2QueryString |
|
twiki.HTML |
HTML manipulation |
insertHtml |
setHtmlOfElementWithId , setHtmlOfElement , getHtmlOfElementWithId , getHtmlOfElement , clearElementWithId , clearElement , deleteElementWithId , deleteElement , insertAfterElement , insertBeforeElement , replaceElement , setNodeAttributesInList , setElementAttributes |
|
twiki.Function |
inheritance |
extendClass |
|
|
twiki.CSS |
CSS class manipulation |
removeClass , addClass , replaceClass , getClassList , setClassList , applyToAllElements , hasClass |
|
|
twiki.Array |
Array utility methods |
indexOf |
remove , convertArgumentsToArray , indexOf |
|
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 |
|
|
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:
--
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
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