jQuery alias (ticket #1032)
FND
global jQuery variable:
http://trac.tiddlywiki.org/ticket/1032
Jeremy brought this up as it might improve code readability, and also
save some bytes.
As an alternative to introducing such a global variable, we could use
closures for creating local aliases[1] within the respective modules.
Another alternative, of course, is to just keep it as "jQuery" (at least
for now, until we have more experience and/or a stronger use case).
Personally, I don't like the "jq" name, also because it seems like we're
creating an arbitrary name specific to the TiddlyWiki community (FWIW,
the jQuery documentation uses $j[2]).
I also think that such a global shortcut is not required.
Any thoughts?
-- F.
[1] http://tiddlywiki.org/wiki/Dev:Best_Practices#Creating_Aliases
[2] http://docs.jquery.com/Using_jQuery_with_Other_Libraries
Paul Downey
> There's a ticket suggesting we introduce an alias/shortcut for the
> global jQuery variable:
> http://trac.tiddlywiki.org/ticket/1032
Um, do we want a thread here, or on the ticket?
> As an alternative to introducing such a global variable, we could use
> closures for creating local aliases[1] within the respective modules.
I like that approach for plugins, given $ is my preference for a
jQuery abbreviation.
> Another alternative, of course, is to just keep it as "jQuery" (at
> least
> for now, until we have more experience and/or a stronger use case).
> Personally, I don't like the "jq" name, also because it seems like
> we're
> creating an arbitrary name specific to the TiddlyWiki community (FWIW,
> the jQuery documentation uses $j[2]).
> I also think that such a global shortcut is not required.
Keeping to as many jQuery established conventions will help, so I'd
suggest avoiding jq for now, given that depends upon TiddlyWiki and
it's jQuery which provides "jquery".
Paul (psd)
--
http://blog.whatfettle.com
Eric Shulman
> closures for creating local aliases[1] within the respective modules.
'local alias' technique for defining $(...) should probably be avoided
within TiddlyWiki, because it can still create conflicts with any
other JS libraries that already define the $(...) function as a simple
abbreviation for:
var $=document.getElementById;
For example, let's suppose that a call to wikify() occurs within the
scope of a locally-defined alias where $(...) invokes the jQuery()
function. In this case, all processing that falls within that scope
-- every macro handler, formatter, or inline script invoked during
rendering -- will attempt to use the jQuery function, even if that
handler, formatter or inline script doesn't actually apply a 'local
alias' wrapper itself or may even be using custom-written code that
calls upon $(...), expecting it to be invoking a simple non-jQuery
version of the function defined in some other plugin or JS library.
Fortunately, the jQuery team has provided the jQuery.noConflict()
function, which TiddlyWiki is currenlty invoking at the start of the
main() function in order to completely avoid this potentially fatal
conflict by telling jQuery *not* apply its own definition of $(...).
Even so, it would be good to have an abbreviation for "jQuery" would
save a considerable number of bytes in the TW core source code... If
the jQuery docs are using $j as an alternative abbreviation, then I
think that's what we should use as well.
-e
FND
The ticket didn't seem to draw much attention, and this groups seems
more suitable for extensive discussions.
> Although it might seem innocuous (and even somewhat elegant), the
> 'local alias' technique for defining $(...) should probably be avoided
> within TiddlyWiki, because it can still create conflicts
That's a good point, Eric.
If I understand this correctly, though, it might suffice to ensure that
the $ alias is not used where eval is invoked?
However, that could become a bit messy. (I'd have to think on this a
little more.)
> If the jQuery docs are using $j as an alternative abbreviation, then
> I think that's what we should use as well.
I've just brought this up on jQuery's IRC channel. People there suggest
that $j is indeed the most commonly used shortcut name.
> Even so, it would be good to have an abbreviation for "jQuery" would
> save a considerable number of bytes in the TW core source code...
We might be engaging in premature optimization here.
So I'm with Paul in that I think we should defer this issue until we
actually have more jQuery code in the core.
However, I can see the arguments for nailing it down now.
-- F.
Eric Shulman
> the $ alias is not used where eval is invoked?
etc... can also get invoked within the scope of a locally-declared $
(...) alias.
-e
Paul Downey
You know, I don't see "$" as being anything too special given there
are other clashes between libraries and TiddlyWiki's extension of
String, Date, etc.
I guess I'm saying I can live with loss of backwards compatibility
with external libraries introduced by plugins and as with other
similar clashes, and think the onus is on the plugin author to resolve
such clashes, not TiddlyWiki.
FND
> etc... can also get invoked within the scope of a locally-declared $
> (...) alias
I don't believe this is correct - please take a look at this test case:
http://fnd.lewcid.org/tmp/alias_scope.html
It boils down to the following:
---------------
var $ = "lorem ipsum";
var foo;
(function($) {
foo = function() {
console.log(typeof $); // prints "function", referencing jQuery
};
// hijack
foo_orig = foo;
foo = function() {
foo_orig.apply(this, arguments);
console.log(typeof $); // prints "string", referencing custom $
};
foo(); // prints both "function" and "string"
---------------
Am I missing something?
-- F.
Martin Budden
"I guess I'm saying I can live with loss of backwards compatibility
with external libraries introduced by plugins and as with other
similar clashes, and think the onus is on the plugin author to resolve
such clashes, not TiddlyWiki."
String and Date extensions (and those extensions are historical - we
wouldn't do them now).
There might be a case for accepting clashes if it was really difficult
to avoid them, but it is not. It's easy to avoid clashes, so we should
do so.
My favoured option is to defer the decision and use jQuery. If we
really want to resolve the issue then my next favourite option is to
use $j.
Martin
2009/4/21 FND <FN...@gmx.net>:
Eric Shulman
> with external libraries introduced by plugins and as with other
> similar clashes, and think the onus is on the plugin author to resolve
> such clashes, not TiddlyWiki.
disagree with.
The "onus" to preserve backward-compatibility *must* always be on
TiddlyWiki to not ignore the needs of the community of *existing*
users, who have already created thousands of documents that could be
instantly and severely broken in ways that they are almost certainly
not equipped to deal with. The negative backlash from such a move
could *kill* TiddlyWiki by screwing over the entire community in one
fell swoop!
And it's not just plugins authors and "developer types" that will need
to work-around the mess... this problem could easily effect any non-
programmers who simply follow instructions to copy and paste some 3rd-
party "badge code" into their tiddler content to embed dynamic content
from a remote host (e.g., twitter, weather.com, etc.). Of course,
some of these badges already don't work properly in a TiddlyWiki
environment (usually because they assume a static document structure),
but many *do* work, currently.
In any event, given that the jQuery team itself has recognized how
intractable this particular conflict of definitions can be, and have
provided the jQuery.noConflict() function for precisely this reason,
I highly doubt that we will come up with an alternative approach that
somehow provides a better solution than the jQuery folks themselves
could think of.
Bottom line (my position): attempts to "shoe-horn" the jQuery $(...)
abbreviation into the core should be dropped as "wasted effort" and we
should move on to more productive issues. For now, just use "jQuery"
and get on with the migration work... but *do* leave the ticket open
to track the issue in case we want to introduce the $j abbreviation in
a subsequent release.
-e
Eric Shulman
scope of $(...) can be difficult, especially when considering the use
of hijacks, plugins, inline scripts and third-party libraries.
Even with these tests, it's still not clear to me when the scope of $
would be problematic and when it would be OK. In any case, keep in
mind that TiddlyWiki is not just an open source application... it's an
open source *development platform*... thus, while it might be possible
for us to do the work to avoid a $(...) scoping problem within the
core code, there is still a great potential for conflicts with other
code that could create a major burden for anyone else attempting to
develop new features.
Except for the core team, we are already facing a paucity of
TiddlyWiki developers in the community (primarily because of the
learning curve and lack of core API documentation). Creating
additional complexities (i.e., needing to comprehend the $(...)
scoping issue) will simply discourage yet more people from even
attempting to learn how to write new things for TiddlyWiki.
-e
FND
> scope of $(...) can be difficult, especially when considering the use
> of hijacks, plugins, inline scripts and third-party libraries.
While I don't necessarily agree about the scoping concerns (there should
never be any "leaking", except when using eval), I do agree that this
introduces an uncertainty factor due to increased complexity.
I have thus reverted the relevant commits, so we're now back to simply
using jQuery:
http://trac.tiddlywiki.org/ticket/1032#comment:5
-- F.
Paul Downey
I think this might be a better thread to help explain my position, and
how I think we should proceed on this issue.
> On Apr 21, 4:26 am, FND <F...@gmx.net> wrote:
>>> not just 'eval'... custom macro handlers, toolbar handlers, hijacks,
>>> etc... can also get invoked within the scope of a locally-declared $
>>> (...) alias
>>
>> I don't believe this is correct - please take a look at this test
>> case:
>> http://fnd.lewcid.org/tmp/alias_scope.html
>>
> As your tests illustrate, understanding and recognizing the current
> scope of $(...) can be difficult, especially when considering the use
> of hijacks, plugins, inline scripts and third-party libraries.
I do feel we may be being overly cautious, and if there is scope
leakage then it will help refactoring and plugin authors if we
understand the problem better and have regression tests to follow.
At the moment I can't help feel that our not fully understanding the
issues is leading to classic cargo-cult programming, and not in the
good sense.
The answer has to be to develop more test cases for such scenarios.
> Even with these tests, it's still not clear to me when the scope of $
> would be problematic and when it would be OK.
Again this cries out "more test cases"!
> In any case, keep in
> mind that TiddlyWiki is not just an open source application... it's an
> open source *development platform*... thus, while it might be possible
> for us to do the work to avoid a $(...) scoping problem within the
> core code, there is still a great potential for conflicts with other
> code that could create a major burden for anyone else attempting to
> develop new features.
I think I see this differently. As I understand it, the problem stems
when plugins introduce other frameworks which use "$".
We can work-around, and in the worst case, I still see it as the duty
of the developer of a plugin to work-round the clash, as it would be
if they introduced something which clashed with another existing core
library function.
> Except for the core team, we are already facing a paucity of
> TiddlyWiki developers in the community (primarily because of the
> learning curve and lack of core API documentation). Creating
> additional complexities (i.e., needing to comprehend the $(...)
> scoping issue) will simply discourage yet more people from even
> attempting to learn how to write new things for TiddlyWiki.
Again I see this a quite different issue. One could argue that by
making TiddlyWiki more open and friendly to jQuery plugins and
developers we'll expand the TiddlyWiki community of plugin authors.
I suggest we continue to use the jquery alias, build more tests for
"$" and consider flipping to "$" once we understand the problem
better. I think at this point adding TiddlyWiki special "jq" alias
will make matters worse, and only add yet another thing we are
committed to maintain for backwards compatibility.
chris...@gmail.com
On Apr 23, 11:44 am, Paul Downey <paul.s.dow...@gmail.com> wrote:
> I suggest we continue to use the jquery alias, build more tests for
> "$" and consider flipping to "$" once we understand the problem
> better. I think at this point adding TiddlyWiki special "jq" alias
> will make matters worse, and only add yet another thing we are
> committed to maintain for backwards compatibility.
"stuff" that is unique or different and thus requires special handling
in the future.
What people choose to do in plugins is their own business, but in the
core a statement of a one correct way which is adhered to, will help
to alleviate backwards compatibility problems in the future.
Plugins that fail to be resilient in the face of stability in the
public API of the core should be considered buggy. Those that rely on
behavior in private code should be considered buggy. Otherwise the
domain of backwards compatibility responsibility in the core becomes
far too large: It takes on win32 proportions and there's just not that
many core developers in the TiddlyWiki community.
Requiring a large domain of backwards compatibility constrains
TiddlyWiki's ability to evolve and move into the future. And
everything has to evolve.
Eric Shulman
> I do feel we may be being overly cautious, and if there is scope
> leakage then it will help refactoring and plugin authors if we
> understand the problem better and have regression tests to follow.
Currently, there doesn't appear to be any kind of *formal* QA process
in place to test the core code. Except for individual developer's
doing their own idiomatic testing, plus a few unit tests (which are
incomplete, at best), proper "acceptance" testing before releasing a
new version into the community is simply not occuring at any level...
no regression tests, no integration tests, no cross-platform tests, no
stress tests... none.
As a result, serious (but subtle) problems are sometimes not found
until exposed to the varied use-cases 'in the wild', where they can
have an immediate "show stopping" impact on unsuspecting members of
the TiddlyWiki community that rely upon a reasonable expectation that
new releases will always be as backward-compatible as they can
possibly be.
In addition, the usual response from the core team to these show-
stopping problems has been, to say the least, extremely
disappointing. Even when a ticket has been created, very little if
anything seems to get done in the short-term to address the problem.
Typically, a ticket will sit for months and months while the folks at
BT/Osmosoft are busy working on their own "cool stuff" and plans for
where they want to take the 'future of TiddlyWiki'...
Paul wrote:
> We can work-around, and in the worst case, I still see it as the duty
> of the developer of a plugin to work-round the clash, as it would be
> if they introduced something which clashed with another existing core
> library function.
that clashes with an *existing* core function, versus an *existing*
plugin being broken by the introduction of *new* code into a core
function.
We are not just talking about new plugin code that has yet to be
written. When a core change breaks a plugin, it's not simply a matter
of publishing an update to the plugin code to work-around the problem
(if that's even possible)...
The issue is that *existing* installed copies of that plugin will
break as soon as the documents in which they are already installed are
upgraded with the latest official core release. From the end-user's
standpoint, upgrading the core causes their *previously functioning*
TiddlyWiki documents to unexpectedly fail in very dramatic ways (hang/
errors on startup, numerous plugin/macro errors, and even tiddler data
corruption are all possible outcomes).
Among the typical users responses:
* revert to a backup copy using the previous core release, and then
*never* upgrade that document. Of course, because each TW document is
self-contained, this is always an option, but really defeats the
purpose of releasing a core upgrade in the first place... we really
want people to adopt the latest core code without hesitation, so that
support for backward-compatible deprecated/legacy code actually can
eventually be left behind... but only *after* an overwhelming majority
of the TW community has successfully moved on to the newer code
code.
* For some users, especially novices, upgrade failures will lead to
FUD (Fear, Uncertainty, and Doubt), resulting in a complete loss of
confidence in TiddlyWiki as practical solution for their information
needs. If the FUD starts to spread (e.g., via published reports of
upgrade failures), TiddlyWiki can quickly become relegated to simple
"personal/hobby" use, and lose all credibility as a serious, robust,
viable platform for production-level uses (especially commercial uses,
where even small errors can cost a lot of money!)
* for users who hang in there, finding the problems in numerous
plugins often involves a tedious trial-and-error process to reduce
complex use-cases and isolate the causes with simple, reproducible
test cases that can then be reported the individual plugin developers
in hopes that a fix will be forthcoming.
Of course, some of these developer's are no longer actively involved
with TiddlyWiki development ('orphaned code'), or are busy working on
other things ('a real job'), or don't know how to fix the problem, or
simply don't respond for other reasons. Even when a plugin developer
does respond, the amount of time and effort it takes to analyze,
diagnose, write and test the necessary changes to just one plugin can
be extensive (depending upon the complexity, of course).
For my own part, here's a little math: the core code size is currently
about 335K, and there are at least 5 core developers at BT/Osmosoft.
In comparison, the TiddlyTools codebase -- which provides enhanced
features to support *thousands* of varied use-cases, primarily written
in response to the specific real-word needs of actual TiddlyWiki
users, authors and developers world wide
-- is over 2Mb and contains nearly 200 separate plugins and scripts,
all maintained by one developer (me). Even fixing just one plugin can
take many hours/days... all just to keep existing functionality
working.
Paul wrote:
> Again I see this a quite different issue. One could argue that by
> making TiddlyWiki more open and friendly to jQuery plugins and
> developers we'll expand the TiddlyWiki community of plugin authors.
> Plugins that fail to be resilient in the face of stability in the
> public API of the core should be considered buggy. Those that rely on
> behavior in private code should be considered buggy. Otherwise the
> domain of backwards compatibility responsibility in the core becomes
> far too large: It takes on win32 proportions and there's just not that
> many core developers in the TiddlyWiki community.
> Requiring a large domain of backwards compatibility constrains
> TiddlyWiki's ability to evolve and move into the future. And
> everything has to evolve.
will be determined not by some theoretical principles of software
architecture discussed amongst a small group of core developers and
then released upon the world as a "fait accompli". Rather, the
success or failure of TiddlyWiki as whole is entirely dependent upon
whether or not it fullfills the needs, interests and intentions of the
people who are actually *using* it. Sure, making it easier for jQuery
developers may help encourage more plugin authors, but not if it
damages the end-user experience and introduces FUD into the mix.
> I suggest we continue to use the jquery alias, build more tests for
> "$" and consider flipping to "$" once we understand the problem
> better. I think at this point adding TiddlyWiki special "jq" alias
> will make matters worse, and only add yet another thing we are
> committed to maintain for backwards compatibility.
() instead of jQuery()... I just don't think it's *necessary* and see
it as a complication, rather than an advantage.
respectfully,
-e
Paul Downey
> Paul wrote:
>> I do feel we may be being overly cautious, and if there is scope
>> leakage then it will help refactoring and plugin authors if we
>> understand the problem better and have regression tests to follow.
>
> Unfortunately, BT/Osmosoft's track record on testing is *abysmal*
Um, I'd like to separate "BT/Osmosoft" from "core developers". Whilst
the people may overlap as in set theory, they are very distinct things
- for example I'm Osmosoft but am not a core contributor.
It is also true that coverage of the current core is pretty abysmal.
We don't have many tests, and code has been added to the core without
tests, but that doesn't prevent writing tests from being the answer.
I'd also note it is hard to write tests for a large code base which
runs in many environments retrospectively and whilst we have
periodically had splurges of writing tests, we do need to carry on
with such initiatives and welcome contributions from others following
the pattern laid out in the core test area - yet another area where
jQuery and qunit is helping us move forward.
If you really feel current TiddlyWiki core testing is abysmal, or
following the wrong approach, then I'd encourage you and others to
show us by examples for plugins and in contributions to the core how
to write better tests.
Best,
Jeremy Ruston
on the central jQuery integration issue there is actually a high
degree of agreement that we should keep the thing as "jQuery", and a
fairly high level of agreement that we might still consider adding "$"
in the future, guided by further experiments.
Other issues have also been raised, notably core testing and
documentation, which are as sore points as they've ever been. Let's
discuss in separate threads. I hear Eric's criticisms of problems with
some core releases, and am keen to resolve them,
Cheers
Jeremy
Jeremy Ruston
mailto:jer...@osmosoft.com
http://www.tiddlywiki.com
chris...@gmail.com
> Paul wrote:
> > I do feel we may be being overly cautious, and if there is scope
> > leakage then it will help refactoring and plugin authors if we
> > understand the problem better and have regression tests to follow.
>
> Unfortunately, BT/Osmosoft's track record on testing is *abysmal*
of) it is currently better than anybody else's record in the
TiddlyWiki community (I'm not counting TiddlyWeb here, which has
awesome tests ;) ).
BT/Osmosoft is not TiddlyWiki development. TiddlyWiki development, out
here in the open, on this list, etc. That's TiddlyWiki development.
It's unfortunate that BT/Osmosoft is perceived and/or allowed to be
some locus of control, because it isn't, or shouldn't be. TiddlyWiki
is an open source project.
I fear as we trend further and further down this thread that we are
losing track of that. TiddlyWiki is a project, not a product. Products
have owners, and processes and formalisms. Projects have people that
get together and discuss and sometimes get things done.
There's no formal QA process for the core code, because the
development community hasn't gotten around to making one. Not because
Osmosoft doesn't have one.
I'm not trying to be an apologist for Osmosoft here. You're right,
there have been some abysses, mostly related to the flow and
distribution of information. The most unfortunate side effect of these
flows is that people start expecting Osmosoft to be responsible for
various things which the community at large could or should be doing.
Where the community happens to include several people who happen to
work at BT/Osmosoft.
> As a result, serious (but subtle) problems are sometimes not found
> until exposed to the varied use-cases 'in the wild', where they can
> have an immediate "show stopping" impact on unsuspecting members of
> the TiddlyWiki community that rely upon a reasonable expectation that
> new releases will always be as backward-compatible as they can
> possibly be.
community of a project discovers a bug, they've fulfilled one of their
most glorious purposes. Obviously it is good to minimize the number of
times someone has to suffer a show stopper, but when someone finds a
heretofore hidden bug they are making a huge contribution to the
community and to the project.
With a product, instead, when someone finds a bug, they've been put
out by some power structure off yonder in which they have little
investment or opportunity to be heard.
> In addition, the usual response from the core team to these show-
> stopping problems has been, to say the least, extremely
> disappointing. Even when a ticket has been created, very little if
> anything seems to get done in the short-term to address the problem.
> Typically, a ticket will sit for months and months while the folks at
> BT/Osmosoft are busy working on their own "cool stuff" and plans for
> where they want to take the 'future of TiddlyWiki'...
couldn't take that ticket, fix it, make a patch or even make a
release. That might end up being a fork, but if the existing release
process is not satisfactory there are plenty of other ways to do
things.
> * for users who hang in there, finding the problems in numerous
> plugins often involves a tedious trial-and-error process to reduce
> complex use-cases and isolate the causes with simple, reproducible
> test cases that can then be reported the individual plugin developers
> in hopes that a fix will be forthcoming.
plugins being far too fragile. Sometimes you gotta let stuff break to
get to a better place. When I experience bugs when upgrading
TiddlyWiki I see it as a flaw in the API, and API which needs to
change. And some of that change will break backwards compatibility in
some cases. It's inevitable. But time carries on, and so does our
data.
I know: That's easy for me to say, I can fix the stuff. I appreciate
that other people sometimes won't and sometimes can't and we must be
considerate of these situations.
> Of course, some of these developer's are no longer actively involved
> with TiddlyWiki development ('orphaned code'), or are busy working on
> other things ('a real job'), or don't know how to fix the problem, or
> simply don't respond for other reasons. Even when a plugin developer
> does respond, the amount of time and effort it takes to analyze,
> diagnose, write and test the necessary changes to just one plugin can
> be extensive (depending upon the complexity, of course).
incredibly opaque and encourages a terribly difficult debug scenario.
[snip]
> all maintained by one developer (me). Even fixing just one plugin can
> take many hours/days... all just to keep existing functionality
> working.
awesome. That's not entirely germane to this discussion, but I'd just
like to point that out.
[snip cdent talking about what constitutes a bug]
> will be determined not by some theoretical principles of software
> architecture discussed amongst a small group of core developers and
> then released upon the world as a "fait accompli". Rather, the
> success or failure of TiddlyWiki as whole is entirely dependent upon
> whether or not it fullfills the needs, interests and intentions of the
> people who are actually *using* it. Sure, making it easier for jQuery
> developers may help encourage more plugin authors, but not if it
> damages the end-user experience and introduces FUD into the mix.
only if we (the tiddlywiki community) let it. There's no reason it
needs to be true.
So to summarize, as I think I've wandered a bit:
What's going on here, in these discussions, is exactly what is
supposed to be happening: People in the community are talking about
decisions the community is making, and will be making. There has been
no failure in process: the process is happening right in front of our
eyes. Our mutual participation is gold.
TiddlyWiki is an open project with many contributors in many forms.
Osmosoft is a contributor. Open projects have bugs and will always
have bugs. Finding bugs is good form and a good way to be a
contributor. Helping to minimize bugs by various forms of testing is
good form too. TiddlyWiki is not a product. It is not owned by
something such as Osmosoft, nor released by Osmosoft. There is no
product that has to be or should be validated before it is seen by its
community: the community validates releases which the project
produces.
What and how the community chooses to release and validate for
TiddlyWiki is up to the community. The community needs to speak its
voice.