Details you should mention in the docs

[rozek]

I'm currently investigating and evaluating _hyperscript. This issue is intended to contain details I found which do not seem to be mentioned in the docs (but might be worth mentioning):

• case-sensitivity
  in contrast to xTalk in general, _hyperscript keywords and identifiers seem to be case-sensitive. Presumably, this approach has been chosen in order to better integrate JavaScript and _hyperscript, but (casual) programmers might not be aware of this detail
• global _hyperscript variables pollute the global JavaScript namespace
  set $x to ... creates a global JavaScript variable called $x and set global x to ... creates one with the name x (see separate issue on this). This behaviour is potentially dangerous and should definitely be mentioned in the docs!
• every _hyperscript behaviour creates a global JavaScript variable with its name
  this detail is potentially dangerous (and could probably be avoided although I am using the detail myself already) and should definitely be mentioned in the docs!
• every function defined at the top level of a <script> element creates a global JavaScript variable with its name
  this detail is potentially dangerous (but could be required if you want JS functions to be able to invoke global _hyperscript functions) and should definitely be mentioned in the docs!
• every _hyperscript function namespace creates a global JavaScript variable with the namespace name
  this detail is potentially dangerous and should also be mentioned in the docs!
• script can not be changed at runtime
  while _ is just an attribute and may be changed from within _hyperscript, doing so does not seem to set a new script on the given element
• new elements with scripts can be created
  e.g., by specifying a proper _ attribute within the HTML of the new element
• replacing an existing element with another one using replaceWith does not work
  although the resulting element has the proper _ attribute. What does work however is to put newElement after me then remove me
• cloning an element also clones its script
  and the script seems to work as intended
• changing the script of a cloned element works
  provided that the _ attribute is changed before the cloned element is inserted into the DOM. And, again, while replaceWith(clonedElement) me does not work, put clonedElement after me then remove me works
• removing attributes
  it may be a beginner's mistake (i.e., mine) but I could not remove an attribute using remove my @<attr> within a 'click' event handler but had to write remove @<attr> from me which was surprising and took some minutes to sort out...
• multiple handlers for the same event are possible
  on the same element and independent of any filters or similar
• multiple (different) behaviours may be installed on the same element
  and they seem to work fine provided that they do not overwrite each others functions (as defed functions do not seem to be behaviour-local but just element-local - as written in the docs)
• take
  has not been mentioned at all
• tell
  has not been mentioned at all (expect in an hdb example where it isn't explained) but is definitely worth mentioning

in my attempt to define self-contained "components" consisting of some HTML (e.g., within a <div/>) and some _hyperscript methods(!) I found the following approach which might be of interest to others:

• within an element, you may define some _hyperscript functions as usual
• in order to make them "publically" available (i.e., to "export" them) you have to set them as element properties: init set my <method> to <method> end where <method> is the _hyperscript function name (warning: this may collide with already existing internal methods of the DOM element)
• from elsewhere in any _hyperscript code, the method may now be invoked using a "pseudo command": <method>(<argument-list>) on <element> (or similar)
• any values returned from the method will become available as the result or simply it

More details will be added as I stumble over them....