[rkward-devel] Potentially incompatible changes to boolean properties in plugins

[Thomas Friedrichsmeier]

Hi!

I have just finished reworking the internal value passing in properties in 
plugins. The most important benefit of that will be, that shortly it will be 
possible to get array-like data (e.g. an array of object-names from a varslot 
that allows to select multiple objects) directly in an Array() in .js. Well, 
this is not yet done. For now, I have focused on trying to lay the foundation 
for this, without breaking anything.

Which is the point of this mail: In some corner cases, the recent changes may 
break existing plugins. In fact, among the official plugins, I had to do minor 
adjustments to four plugins: 
http://rkward.svn.sourceforge.net/rkward/?rev=4457&view=rev . That's not much, 
but it is possible that your external plugin(s) are affected, too. So here's 
how you can check, whether your plugin(s) are affected, and how to fix that.

The incompatible change concerns boolean properties, only. These are now be 
represented as "0" or "1", instead of the labeled values "true", "false", or 
custom strings, as before.

There are exactly two occurances of boolean properties, ATM(*):
 1. <checkbox> elements
 2. <convert> elements

1) Let's say, you have defined a checkbox like this:

  <checkbox id="checkbox" value_true="yes" value_false="no"/>

1a) If you're fetching the value in you .js code as
   getValue ("checkbox")
you are *not* affected. This continues to fetch the labeled representation. 
However, if your code has
   getValue ("checkbox.state")
this will now return "0"/"1", instead of "yes"/"no".

***Advice***: It is unlikely that you have written this. But please grep your 
.js files for "\.state", and review any matches for problematic usage. In 
particular, change
   if (getValue ("checkbox.state") == "yes") ...
to either
   if (getValue ("checkbox.state")) ...
or, if you want to keep backwards compatibility to RKWard <= 0.6.0 change it 
to:
   if (getValue ("checkbox.state.numeric")) ...

1b) Some ancient plugins would use logic like this to negate a checkbox state:

   <convert id="notchecked" sources="checkbox.state" mode="equals" 
standard="no"/>
   <connect client="something.enabled" governor="notchecked"/>

This is long since obsolete, and should be changed to

   <connect client="something.enabled" governor="checkbox.state.not"/>

***Advice***: Grep your .xml files for "\<convert.*\.state\"" and correct any 
matches that use "equals" or "notequals" to negate boolean properties. 
<convert> with mode="and" or mode="or" is *not* affected.

2) Let's say you have defined a <convert> property like this:

  <convert id="convert" ... />

2a) If you're fetching the value in .js code as
   getValue ("convert")
you will now get "0"/"1", instead of "true"/"false".

***Advice***: grep your .js files for "[!=]=\s*.false" and "[!=]=\s*.true", to 
find matches against labeled <convert> properties. In particular, change
   if (getValue ("something") == "true") ...
to either
   if (getValue ("something.state")) ...
or, if you want to keep backwards compatibility to RKWard <= 0.6.0 change it 
to:
   if (getValue ("something.state.numeric")) ...

2b) Some plugins use explicit conversion to a boolean property like this:
   <external id="bar" default="false"/>
   <convert id="foo" sources="bar" mode="equals" standard="true"/>
   <connect client="something.enabled" governor="foo"/>
This is no longer necessary, as boolean client properties will do smart 
conversion, automatically. Thus, you can change this to
   <external id="bar" default="false"/>	<!-- or default="0" -->
   <connect client="something.enabled" governor="bar"/>
or, if you want to keep backwards compatiblity to RKWard <= 0.6.0, change it 
to:
   <external id="bar" default="false"/>
   <convert id="foo1" sources="bar" mode="equals" standard="true"/>
   <convert id="foo" sources="bar;foo1" mode="or"/>
   <connect client="something.enabled" governor="foo"/>

***Advice***: grep your .xml files for "standard\s*=\s*\"true\"" and 
"standard\s*=\s*\"false\"" and correct problematic usages as shown above.

Sorry about the trouble. But this was really terribly inconsistent, and 
keeping all corner-cases backwards compatible would only have added to the 
mess.

Regards
Thomas

------

(*): Actually, checkable <frame> elements also hold a boolean property, but 
there, the "checked" property was already consistent with the new behavior.
-------------- 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/20121127/72c1deb4/attachment.sig>