Friday, August 25, 2006

Library again....

Working on the Formula Language analogue functions in the JS library has got me wondering. There are several @Functions (well, a lot of them, really) that will return either a single value or a list of values. In Formula Language, that's all fine and dandy, because except in a very few cases, EVERYTHING is a list. That is, you can spend most of your time oblivious to the actual output of the various lines of code you write; you don't need to make special concessions for "text" versus "text list". I've honoured that in the JS functions' inputs -- they can take a single value, an array of values, an HTML field object, or, in combination with atGetField(), a fieldname.

But what about the output? As it stands right now, I am creating the output in an array, then passing the array out if there is more than one value, and passing a scalar if there is only one value. While that's great if you want to cascade these "@Functions", I was thinking that it might make it unnecessarily difficult if you merely want to borrow a function or two to use in your own JS code. For instance, using atReplaceSubstring() is easier than writing something to iterate through two arrays, generate regular expressions on the fly, and do the replacement oneself. But is the return type uncertainty (array or scalar) going to be a problem? Should the return always be an array when the corresponding @Function allows a multi-value return?

For the record, these are the functions I've already completed:

  • function atDbLookup()
  • function atDbColumn()
  • function atExplode()
  • function atGetDocField()
  • function atGetField()
  • function atImplode()
  • function atLeft()
  • function atMember()
  • function atMiddle()
  • function atReplace()
  • function atReplaceSubstring()
  • function atRight()
  • function atSetDocField()
  • function atSetField()
  • function atSort()
  • function atTrim()
  • function atURLDecode()
  • function atURLEncode()
  • function atURLQueryString()
  • function atWord()

As much as I would like to have used a proper "@" in the names, it's an illegal character thanks to Microsoft's conditional evaluation. Okay, the list isn't very long yet, but the atDbLookup() and atDbColumn() functions took a while, as did atGetDocField() and atSetDocField(). All of them rely on XmlHTTPRequests, and the xxxDocField functions need a server-side agent to work. Okay, we're talking about the simplest, smallest web agent ever, but it's still an extra piece. And it will grow as more server-interactive atFunctions are added, like atUserRoles(). Even atURLQueryString() has more to it than you'd think. And don't get me started on atReplaceSubstring(). There are also a few helper functions to do listwise and permuted operations, since JavaScript doesn't know that [text array] + [string] should add the string to every member of the array.

I am also posting this, or something like it, on the LDD forum, but again, your input is valuable to me.


Anonymous said...

Wow. Everything there is just so unbelievably valuable, what an incredible asset.

I know you are asking for ideas on how to grow this library, but frankly, it seems to be doing just fine with your brain behind it. You probably are more aware than most others about what the big needs are out there, with your phenomenal developerworks presence. :)

I am a bit speechless at this point, but here's my best try for two possible additions. Note: they are very much orientated to overall application design, I'll leave it to the rocket scientists out there to comment on more specific encapsulated functions that would add value:
a) I do believe there is a need for the One and Only Final Word form validation library (similar to the LotusScript one in the Sandbox).
b) Perhaps a collection of view functions, building on your previous post, including things like a dynamic expand and collapse twistie function, inview editing on the web, etc. etc.

You know, with a library like this out there, one will have to retrain oneself on how to develop on the web for Domino: it would really be a different world, and a revolutionary one at that.

Chad Schelfhout said...

JavaScript handles things just like Formula. If there was one field on the form called 'Chad' then you could reference it as Chad.value, but if there were two or more you would need to use Chad[0].value and Chad[1].value. (the syntax might not be correct).

I think it should act like JavaScript, which happens to be just like @Formula.

Stan Rogers said...

@Chad -- and that is like Formula Language how, exactly? In Formula Language, you can usually treat strings and string lists identically. In JavaScript, unless you test the typeof and fork the code, if you feed a string where an array should be or an array where a string should be, something's gonna break. What I want to know is whether a single value should come out of a function as an array (the way it does in a Lotusscript Evaluate statement), as a string, or should you be able to add a returnSingleAsArray Boolean switch to the function? I'm leaning towards the latter (with true as a default), but it does mean extra complexity on the developer's end if what they really want is a string.

Adi said...

Stan, I just have to say this: every now and again I get the impression that, now, I know Notes and I can consider myself an experienced developer. Then I read posts like these and I realise that, no... I still just have no idea. What I have is a few grains of sand I picked up, while there are those out there that are eroding away rocks through time to form their own beaches. Your ideas are already far more advanced than mine were, when you first posted the idea of a library, so I'm afraid I can't just pull more functions out of a hat to add to the already impressive list. However, I have no doubt that the more these are used by the community, the more you are going to get swamped with more requests and ideas. If you need anything from our side, at all, to make this happen (testing, sample db's, etc), just put us to work. This is a most worthwhile project.

Chad Schelfhout said...

With Formula depending on what you put in dictates what you get out. I think that is how JavaScript works also. LotusScript on the hand force things like Evaluate it will always be an string array.
I think the switch would be a nice touch and can understand why you want to add it. I would lean more towards the single value return just because that is how JavaScript works today like I described in my previous post.

Rob McDonagh said...

Stan, you're right. I know, shocking, isn't it? Heh. I'd go with returnSingleAsArray. Yes, it requires the developer to pay a bit of attention, but the increased flexibility is worth it.

Brian Miller said...

Stan, you should take a look at jQuery. One of the neat things about that library is the way that the core functionality is encapsulated in an object, which looks/acts like an array (in this case, an array of DOM elements), and also manages to chain methods by returning objects shaped like the core "jQuery" object.

I could see you doing the same thing with an "atFormula" object, or simply a "Domino" object, which would look/act like a Domino list.