[rkward-devel] Plugin development: New JS-functions getString()/getBoolean()/getList()

[Thomas Friedrichsmeier]

Hi!

I just wanted to let you know about three new functions for use in plugins' JS 
code (both code generation and gui scripting). These are replacements for the 
old getValue()-call.

Don't worry: getValue() is not going away. But for new plugins, or when 
reworking existing plugins, you should use these, instead.

- First things first: What's wrong with getValue()?
Not much. But this does have a certain peculiarity: getValue() will always 
return the value as a string, *except* when the value to get is "0", it will 
return numeric 0, instead of a string(*). This was a hack to keep plugins 
working after the conversion from PHP(*) However, this can cause problems in a 
corner case: In a free-field <input>, the user might want to enter "0". This 
can cause the plugin to bail out with an error, if it tries to use string 
methods on the value (e.g. replace()).

- getString() and getBoolean()
getString() is almost identical to getValue(), and in fact it is the function 
you will use most often. The only difference is that it will always return a 
string, even if that is "0". For use in if()-switches or other logic, there is 
now a new function getBoolean(). This will try hard to convert the value in 
question to a logical, even handling the strings "true" and "false".

Of course getBoolean() can't do magic, but in contrast to getValue(), if 
getBoolean() cannot meaningfully convert a value to a logical, it will produce 
a warning. Speaking of which: There is a new tool window to view RKWard 
internal debug messages. Activate it from the "Windows"-menu, or by right-
clicking on one of the tool docks. Use it to check your plugins for problems!

- getList()
getList() is an entirely new function, which will return an Array of strings 
(if possible). There are only a few use-cases of this, so far. The first is 
getting a list of objects from <varslot>s with multi="true". Another is the 
fetching columns from the new <matrix>-element, that is new in the development 
version. A third is the new <optionset>-element, which I will write about, 
soon. The advantages of getList() over using getValue() (or getString()), and 
then splitting by newlines, should be obvious.

Backwards compatibility note: getString() was added in RKWard 0.6.0, already. 
getBoolean() and getList() are available in the development version, only.

Regards
Thomas

----

(*): In PHP,
   if ("0") echo ("yes");
will not generate anything ("0" evaluates to false). In JS,
   if ("0") echo ("yes");
will generate "yes" ("0" evaluates to true). Returning "0" as a numeric value 
kept plugins working after the conversion from PHP. And in most - but not all 
- cases, JS is smart enough to convert the numeric representation back to a 
string, if needed.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/rkward-devel/attachments/20121204/dc118f8f/attachment.sig>