|
1
|
# Use of JavaScript in Fossil |
|
2
|
|
|
3
|
## Philosophy & Policy |
|
4
|
|
|
5
|
The Fossil development project’s policy is to use JavaScript where it |
|
6
|
helps make its web UI better, but to offer graceful fallbacks wherever |
|
7
|
practical. The intent is that the UI be usable with JavaScript |
|
8
|
entirely disabled. In almost all places where Fossil uses JavaScript, |
|
9
|
it is an enhancement to provided functionality, and there is always |
|
10
|
another way to accomplish a given end without using JavaScript. |
|
11
|
|
|
12
|
This is not to say that Fossil’s fall-backs for such cases are always as |
|
13
|
elegant and functional as a no-JS purist might wish. That is simply |
|
14
|
because [the vast majority of web users leave JavaScript unconditionally |
|
15
|
enabled](#stats), and of the small minority of those that do not, a |
|
16
|
large chunk use some kind of [conditional blocking](#block) instead, |
|
17
|
rather than disable JavaScript entirely. |
|
18
|
Fossil’s active developers do not deviate from that |
|
19
|
norm enough that we have many no-JS purists among us, so the no-JS case |
|
20
|
doesn’t get as much attention as some might want. We do [accept code |
|
21
|
contributions][cg], and we are philosophically in favor of graceful |
|
22
|
fall-backs, so you are welcome to appoint yourself the position of no-JS |
|
23
|
czar for the Fossil project! |
|
24
|
|
|
25
|
Evil is in actions, not in objects: we do not believe JavaScript *can* |
|
26
|
be evil. It is an active technology, but the actions that matter here |
|
27
|
are those of writing the code and checking it into the Fossil project |
|
28
|
repository. None of the JavaScript code in Fossil is evil, a fact we |
|
29
|
enforce by being careful about who we give check-in rights on the |
|
30
|
repository to and by policing what code does get contributed. The Fossil |
|
31
|
project does not accept non-trivial outside contributions. |
|
32
|
|
|
33
|
We think it’s better to ask not whether Fossil requires JavaScript but |
|
34
|
whether Fossil uses JavaScript *well*, so that [you can decide](#block) |
|
35
|
to block or allow Fossil’s use of JavaScript. |
|
36
|
|
|
37
|
The Fossil developers want to see the project thrive, and we achieve |
|
38
|
that best by making it usable and friendly to a wider audience than the |
|
39
|
minority of static web app purists. Modern users generally expect a |
|
40
|
smoother experience than was available with 1990s style HTTP |
|
41
|
POST-and-response `<form>` based interaction. We also increase the set |
|
42
|
of potential Fossil developers if we do not restrict them to such |
|
43
|
antiquated methods. |
|
44
|
|
|
45
|
JavaScript is not perfect, but it's what we have, so we will use it |
|
46
|
where we find it advantageous. |
|
47
|
|
|
48
|
[cg]: ./contribute.wiki |
|
49
|
|
|
50
|
|
|
51
|
## <a id="debate"></a>Arguments Against JavaScript & Our Rebuttals |
|
52
|
|
|
53
|
There are many common arguments against the use of JavaScript. Rather than |
|
54
|
rehash these same arguments on the [forum][ffor], we distill the common |
|
55
|
ones we’ve heard before and give our stock answers to them here: |
|
56
|
|
|
57
|
1. “**It increases the size of the page download.**” |
|
58
|
|
|
59
|
The heaviest such pages served by Fossil only have about 15 kB of |
|
60
|
compressed JavaScript. (You have to go out of your way to get Fossil |
|
61
|
to serve uncompressed pages.) This is negligible, even over very |
|
62
|
slow data connections. If you are still somehow on a 56 kbit/sec |
|
63
|
analog telephone modem, this extra script code would download in |
|
64
|
a few seconds. |
|
65
|
|
|
66
|
Most JavaScript-based Fossil pages use less code than that. |
|
67
|
|
|
68
|
Atop that, Fossil sends HTTP headers to the browser that allow it |
|
69
|
to perform aggressive caching so that typical page loads will skip |
|
70
|
re-loading this content on subsequent loads. These features are |
|
71
|
currently optional: you must either set the new |
|
72
|
[`fossil server --jsmode bundle` option][fsrv] or the corresponding |
|
73
|
`jsmode` control line |
|
74
|
in your [`fossil cgi`][fcgi] script when setting up your |
|
75
|
[Fossil server][fshome]. That done, Fossil’s JavaScript files will |
|
76
|
load almost instantly from the browser’s cache after the initial |
|
77
|
page load, rather than be re-transferred over the network. |
|
78
|
|
|
79
|
Between the improved caching and the fact that it’s quicker to |
|
80
|
transfer a partial Ajax page load than reload the entire page, the |
|
81
|
aggregate cost of such pages is typically *lower* than the older |
|
82
|
methods based on HTTP POST with a full server round-trip. You can |
|
83
|
expect to recover the cost of the initial page load in 1-2 |
|
84
|
round-trips. If we were to double the amount of JavaScript code in |
|
85
|
Fossil, the payoff time would increase to 2-4 round-trips. |
|
86
|
|
|
87
|
2. “**JavaScript is slow.**” |
|
88
|
|
|
89
|
It *was*, before September 2008. Google's introduction of [their V8 |
|
90
|
JavaScript engine][v8] taught the world that JavaScript need not be |
|
91
|
slow. This competitive pressure caused the other common JavaScript |
|
92
|
interpreters to either improve or be replaced by one of the engines |
|
93
|
that did improve to approach V8’s speed. |
|
94
|
|
|
95
|
Nowadays JavaScript is, as a rule, astoundingly fast. As the world |
|
96
|
continues to move more and more to web-based applications and |
|
97
|
services, JavaScript engine developers have ample motivation to keep |
|
98
|
their engines fast and competitive. |
|
99
|
|
|
100
|
Ajax partial page updates are faster than |
|
101
|
the no-JS alternative, a full HTTP POST round-trip to submit new |
|
102
|
data to the remote server, retrieve an entire new HTML document, |
|
103
|
and re-render the whole thing client-side. |
|
104
|
|
|
105
|
3. <a id="3pjs"></a>“**Third-party JavaScript cannot be trusted.**” |
|
106
|
|
|
107
|
Fossil does not use any third-party JavaScript libraries, not even |
|
108
|
very common ones like jQuery. Every bit of JavaScript served by the |
|
109
|
stock version of Fossil was written specifically for the Fossil |
|
110
|
project and is stored [in its code repository][fsrc]. |
|
111
|
|
|
112
|
Therefore, if you want to hack on the JavaScript code served by |
|
113
|
Fossil and mechanisms like [skin editing][cskin] don’t suffice for your |
|
114
|
purposes, you can hack on the JavaScript in your local instance |
|
115
|
directly, just as you can hack on its C, SQL, and Tcl code. Fossil |
|
116
|
is free and open source software, under [a single license][2cbsd]. |
|
117
|
|
|
118
|
4. <a id="snoop"></a>“**JavaScript and cookies are used to snoop on web users.**” |
|
119
|
|
|
120
|
There is no tracking or other snooping technology in Fossil other than |
|
121
|
that necessary for basic security, such as IP address logging on |
|
122
|
check-ins. (This is in part why we have no [comprehensive user |
|
123
|
statistics](#stats)!) |
|
124
|
|
|
125
|
Fossil attempts to set two cookies on all web clients: a login session |
|
126
|
cookie and a display preferences cookie. These cookies are restricted to |
|
127
|
the Fossil instance, so even this limited data cannot leak between |
|
128
|
Fossil instances or into other web sites. |
|
129
|
|
|
130
|
5. “**JavaScript is fundamentally insecure.**” |
|
131
|
|
|
132
|
JavaScript is certainly sometimes used for nefarious ends, but if we |
|
133
|
wish to have more features in Fossil, the alternative is to add more |
|
134
|
code to the Fossil binary, [most likely in C][fslpl], a language |
|
135
|
implicated in [over 4× more security vulnerabilities][whmsl]. |
|
136
|
|
|
137
|
Therefore, does it not make sense to place approximately four times |
|
138
|
as much trust in Fossil’s JavaScript code as in its C code? |
|
139
|
|
|
140
|
The question is not whether JavaScript is itself evil, it is whether |
|
141
|
its *authors* are evil. *Every byte* of JavaScript code used within |
|
142
|
the Fossil UI is: |
|
143
|
|
|
144
|
* ...written by the Fossil developers, vetted by their peers. |
|
145
|
|
|
146
|
* ...[open source][flic] and [available][fsrc] to be inspected, |
|
147
|
audited, and changed by its users. |
|
148
|
|
|
149
|
* ...compiled directly into the `fossil` binary in a |
|
150
|
non-obfuscated form during the build process, so there are no |
|
151
|
third-party servers delivering mysterious, obfuscated JavaScript |
|
152
|
code blobs to the user. |
|
153
|
|
|
154
|
Local administrators can [modify the repository’s skin][cskin] to |
|
155
|
inject additional JavaScript code into pages served by their Fossil |
|
156
|
server. A typical case is to add a syntax highlighter like |
|
157
|
[Prism.js][pjs] or [highlightjs][hljs] to the local repository. At |
|
158
|
that point, your trust concern is not with Fossil’s use of |
|
159
|
JavaScript, but with your trust in that repository’s administrator. |
|
160
|
|
|
161
|
Fossil's [default content security policy][dcsp] (CSP) |
|
162
|
prohibits execution of JavaScript code which is delivered from |
|
163
|
anywhere but the Fossil server which delivers the page. A local |
|
164
|
administrator can change this CSP, but again this comes down to a |
|
165
|
matter of trust with the administrator, not with Fossil itself. |
|
166
|
|
|
167
|
6. “**Cross-browser compatibility is poor.**” |
|
168
|
|
|
169
|
It most certainly was in the first decade or so of JavaScript’s |
|
170
|
lifetime, resulting in the creation of powerful libraries like |
|
171
|
jQuery to patch over the incompatibilities. Over time, the need for |
|
172
|
such libraries has dropped as browser vendors have fixed the |
|
173
|
incompatibilities. Cross-browser JavaScript compatibility issues |
|
174
|
which affect web developers are, by and large, a thing of the past. |
|
175
|
|
|
176
|
7. “**Fossil UI works fine today without JavaScript. Why break it?**” |
|
177
|
|
|
178
|
While this is true today, and we have no philosophical objection to |
|
179
|
it remaining true, we do not intend to limit ourselves to only those |
|
180
|
features that can be created without JavaScript. The mere |
|
181
|
availability of alternatives is not a good justification for holding |
|
182
|
back on notable improvements when they're within easy reach. |
|
183
|
|
|
184
|
The no-JS case is a [minority position](#stats), so those that want |
|
185
|
Fossil to have no-JS alternatives and graceful fallbacks will need |
|
186
|
to get involved with the development if they want this state of |
|
187
|
affairs to continue. |
|
188
|
|
|
189
|
8. <a id="stats"></a>“**A large number of users run without JavaScript enabled.**” |
|
190
|
|
|
191
|
That’s not what web audience measurements say: |
|
192
|
|
|
193
|
* [What percentage of browsers with javascript disabled?][s1] |
|
194
|
* [How many people are missing out on JavaScript enhancement?][s2] |
|
195
|
* [Just how many web users really disable cookies or JavaScript?][s3] |
|
196
|
|
|
197
|
Our sense of this data is that only about 0.2% of web users had |
|
198
|
JavaScript disabled while participating in these studies. |
|
199
|
|
|
200
|
The Fossil user community is not typical of the wider web, but if we |
|
201
|
were able to comprehensively survey our users, we’d expect to find |
|
202
|
an interesting dichotomy. Because Fossil is targeted at software |
|
203
|
developers, who in turn are more likely to be power-users, we’d |
|
204
|
expect to find Fossil users to be more in favor of some amount of |
|
205
|
JavaScript blocking than the average web user. Yet, we’d also expect |
|
206
|
to find that our user base has a disproportionately high number who |
|
207
|
run [powerful conditional blocking plugins](#block) in their |
|
208
|
browsers, rather than block JavaScript entirely. We suspect that |
|
209
|
between these two forces, the number of no-JS purists among Fossil’s |
|
210
|
user base is still a tiny minority. |
|
211
|
|
|
212
|
9. <a id="block"></a>“**I block JavaScript entirely in my browser. That breaks Fossil.**” |
|
213
|
|
|
214
|
First, see our philosophy statements above. Briefly, we intend that |
|
215
|
there always be some other way to get any given result without using |
|
216
|
JavaScript, developer interest willing. |
|
217
|
|
|
218
|
But second, it doesn’t have to be all-or-nothing. We recommend that |
|
219
|
those interested in blocking problematic uses of JavaScript use |
|
220
|
tools like [NoScript][ns] or [uBlock Origin][ubo] to *selectively* |
|
221
|
block JavaScript so the rest of the web can use the technology |
|
222
|
productively, as it was intended. |
|
223
|
|
|
224
|
There are doubtless other useful tools of this sort. We recommend |
|
225
|
these two only from our limited experience, not out of any wish to |
|
226
|
exclude other tools. |
|
227
|
|
|
228
|
The primary difference between these two for our purposes is that |
|
229
|
NoScript lets you select scripts to run on a page on a case-by-case |
|
230
|
basis, whereas uBlock Origin delegates those choices to a group of |
|
231
|
motivated volunteers who maintain allow/block lists to control all |
|
232
|
of this; you can then override UBO’s stock rules as needed. |
|
233
|
|
|
234
|
10. “**My browser doesn’t even *have* a JavaScript interpreter.**” |
|
235
|
|
|
236
|
The Fossil open source project has no full-time developers, and only |
|
237
|
a few of these part-timers are responsible for the bulk of the code |
|
238
|
in Fossil. If you want Fossil to support such niche use cases, then |
|
239
|
you will have to [get involved with its development][cg]: it’s |
|
240
|
*your* uncommon itch. |
|
241
|
|
|
242
|
11. <a id="compat"></a>“**Fossil’s JavaScript code isn’t compatible with my browser.**” |
|
243
|
|
|
244
|
The Fossil project’s developers aim to remain compatible with |
|
245
|
the largest portions of the client-side browser base. We use only |
|
246
|
standards-defined JavaScript features which are known to work in the |
|
247
|
overwhelmingly vast majority of browsers going back approximately 5 |
|
248
|
years, at minimum, as documented by [Can I Use...?][ciu] We avoid use of |
|
249
|
features added to the language more recently or those which are still in |
|
250
|
flux in standards committees. |
|
251
|
|
|
252
|
We set this threshold based on the amount of time it typically takes for |
|
253
|
new standards to propagate through the installed base. |
|
254
|
|
|
255
|
As of this writing, this means we are only using features defined in |
|
256
|
[ECMAScript 2015][es2015], colloquially called “JavaScript 6.” That |
|
257
|
is a sufficiently rich standard that it more than suffices for our |
|
258
|
purposes, and it is [widely deployed][es6dep]. The biggest single |
|
259
|
outlier remaining is MSIE 11, and [even Microsoft is moving their |
|
260
|
own products off of it][ie11x]. |
|
261
|
|
|
262
|
[2cbsd]: https://fossil-scm.org/home/doc/trunk/COPYRIGHT-BSD2.txt |
|
263
|
[ciu]: https://caniuse.com/ |
|
264
|
[cskin]: ./customskin.md |
|
265
|
[dcsp]: ./defcsp.md |
|
266
|
[es2015]: https://ecma-international.org/ecma-262/6.0/ |
|
267
|
[es6dep]: https://caniuse.com/#feat=es6 |
|
268
|
[fcgi]: /help/cgi |
|
269
|
[ffor]: https://fossil-scm.org/forum/ |
|
270
|
[flic]: /doc/trunk/COPYRIGHT-BSD2.txt |
|
271
|
[fshome]: /doc/trunk/www/server/ |
|
272
|
[fslpl]: /doc/trunk/www/fossil-v-git.wiki#portable |
|
273
|
[fsrc]: https://fossil-scm.org/home/file/src |
|
274
|
[fsrv]: /help/server |
|
275
|
[hljs]: https://fossil-scm.org/forum/forumpost/9150bc22ca |
|
276
|
[ie11x]: https://techcommunity.microsoft.com/t5/microsoft-365-blog/microsoft-365-apps-say-farewell-to-internet-explorer-11-and/ba-p/1591666 |
|
277
|
[ns]: https://noscript.net/ |
|
278
|
[pjs]: https://fossil-scm.org/forum/forumpost/1198651c6d |
|
279
|
[s1]: https://blockmetry.com/blog/javascript-disabled |
|
280
|
[s2]: https://gds.blog.gov.uk/2013/10/21/how-many-people-are-missing-out-on-javascript-enhancement/ |
|
281
|
[s3]: https://w3techs.com/technologies/overview/client_side_language/all |
|
282
|
[ubo]: https://github.com/gorhill/uBlock/ |
|
283
|
[v8]: https://en.wikipedia.org/wiki/V8_(JavaScript_engine) |
|
284
|
[whmsl]: https://www.whitesourcesoftware.com/most-secure-programming-languages/ |
|
285
|
|
|
286
|
|
|
287
|
---- |
|
288
|
|
|
289
|
## <a id="uses"></a>Places Where Fossil’s Web UI Uses JavaScript |
|
290
|
|
|
291
|
This section documents the areas where Fossil currently uses JavaScript |
|
292
|
and what it does when these uses are blocked. It also gives common |
|
293
|
workarounds where necessary. |
|
294
|
|
|
295
|
|
|
296
|
### <a id="timeline"></a>Timeline Graph |
|
297
|
|
|
298
|
Fossil’s [web timeline][wt] uses JavaScript to render the graph |
|
299
|
connecting the visible check-ins to each other, so you can visualize |
|
300
|
parent/child relationships, merge actions, etc. We’re not sure it’s even |
|
301
|
possible to render this in static HTML, even with the aid of SVG, due to |
|
302
|
the vagaries of web layout among browser engines, screen sizes, etc. |
|
303
|
|
|
304
|
Fossil also uses JavaScript to handle clicks on the graph nodes to allow |
|
305
|
diffs between versions, to display tooltips showing local context, etc. |
|
306
|
|
|
307
|
_Graceful Fallback:_ When JavaScript is disabled, this column of the |
|
308
|
timeline simply collapses to zero width. All of the information you can |
|
309
|
get from the timeline can be retrieved from Fossil in other ways not |
|
310
|
using JavaScript: the “`fossil timeline`” command, the “`fossil info`” |
|
311
|
command, by clicking around within the web UI, etc. |
|
312
|
|
|
313
|
_Potential Workaround:_ The timeline could be enhanced with `<noscript>` |
|
314
|
tags that replace the graph with a column of checkboxes that control |
|
315
|
what a series of form submit buttons do when clicked, replicating the |
|
316
|
current JavaScript-based features of the graph using client-server round-trips. |
|
317
|
For example, you could click two of those checkboxes and then a button |
|
318
|
labeled “Diff Selected” to replicate the current “click two nodes to |
|
319
|
diff them” feature. |
|
320
|
|
|
321
|
[wt]: https://fossil-scm.org/home/timeline |
|
322
|
|
|
323
|
|
|
324
|
### <a id="wedit"></a>The New Wiki Editor |
|
325
|
|
|
326
|
The [new wiki editor][fwt] has many new features, a |
|
327
|
few of which are impossible to get without use of JavaScript. |
|
328
|
|
|
329
|
First, it allows in-browser previews without losing client-side editor |
|
330
|
state, such as where your cursor is. With the old editor, you had to |
|
331
|
re-locate the place you were last editing on each preview, which would |
|
332
|
reduce the incentive to use the preview function. In the new wiki |
|
333
|
editor, you just click the Preview tab to see how Fossil interprets your |
|
334
|
markup, then click back to the Editor tab to resume work with the prior |
|
335
|
context undisturbed. |
|
336
|
|
|
337
|
Second, it continually saves your document state in client-side storage |
|
338
|
in the background while you’re editing it so that if the browser closes |
|
339
|
without saving the changes back to the Fossil repository, you can resume |
|
340
|
editing from the stored copy without losing work. This feature is not so |
|
341
|
much about saving you from crashes of various sorts, since computers are |
|
342
|
so much more reliable these days. It is far more likely to save you from |
|
343
|
the features of mobile OSes like Android and iOS which aggressively shut |
|
344
|
down and restart apps to save on RAM. That OS design philosophy assumes |
|
345
|
that there is a way for the app to restore its prior state from |
|
346
|
persistent media when it’s restarted, giving the illusion that it was |
|
347
|
never shut down in the first place. This feature of Fossil’s new wiki |
|
348
|
editor provides that. |
|
349
|
|
|
350
|
With this change, we lost the old WYSIWYG wiki editor, available since |
|
351
|
Fossil version 1.24. It hadn’t been maintained for years, it was |
|
352
|
disabled by default, and no one stepped up to defend its existence when |
|
353
|
this new editor was created, replacing it. If someone rescues that |
|
354
|
feature, merging it in with the new editor, it will doubtless require |
|
355
|
JavaScript in order to react to editor button clicks like the “**B**” |
|
356
|
button, meaning “make \[selected\] text boldface.” There is no standard |
|
357
|
WYSIWYG editor component in browsers, doubtless because it’s relatively |
|
358
|
straightforward to create one using JavaScript. |
|
359
|
|
|
360
|
_Graceful Fallback:_ Fossil’s lack of |
|
361
|
a script-free wiki editor mode is not from lack of |
|
362
|
desire, but because the person who wrote the new wiki editor didn’t |
|
363
|
want to maintain three different editors. (New Ajaxy editor, old |
|
364
|
script-free HTML form based editor, and the old WYSIWYG JavaScript-based |
|
365
|
editor.) If someone wants to implement a `<noscript>` alternative to the |
|
366
|
new wiki editor, we will likely accept that [contribution][cg] as long |
|
367
|
as it doesn’t interfere with the new editor. (The same goes for adding |
|
368
|
a WYSIWYG mode to the new Ajaxy wiki editor.) |
|
369
|
|
|
370
|
_Workaround:_ You don’t have to use the browser-based wiki editor to |
|
371
|
maintain your repository’s wiki at all. Fossil’s [`wiki` command][fwc] |
|
372
|
lets you manipulate wiki documents from the command line. For example, |
|
373
|
consider this Vi based workflow: |
|
374
|
|
|
375
|
```shell |
|
376
|
$ vi 'My Article.wiki' # begin work on new article |
|
377
|
...write, write, write... |
|
378
|
:w # save changes to disk copy |
|
379
|
:!fossil wiki create 'My Article' '%' # current file (%) to new article |
|
380
|
...write, write, write some more... |
|
381
|
:w # save again |
|
382
|
:!fossil wiki commit 'My Article' '%' # update article from disk |
|
383
|
:q # done writing for today |
|
384
|
|
|
385
|
....days later... |
|
386
|
$ vi # work sans named file today |
|
387
|
:r !fossil wiki export 'My Article' - # pull article text into vi buffer |
|
388
|
...write, write, write yet more... |
|
389
|
:w !fossil wiki commit - # vi buffer updates article |
|
390
|
``` |
|
391
|
|
|
392
|
Extending this concept to other text editors is an exercise left to the |
|
393
|
reader. |
|
394
|
|
|
395
|
[fwc]: /help/wiki |
|
396
|
[fwt]: ./wikitheory.wiki |
|
397
|
|
|
398
|
|
|
399
|
### <a id="fedit"></a>The File Editor |
|
400
|
|
|
401
|
Fossil’s [optional file editor feature][fedit] works |
|
402
|
much like [the new wiki editor](#wedit), only on files committed to the |
|
403
|
repository. |
|
404
|
|
|
405
|
The original designed purpose for this feature is to allow [embedded |
|
406
|
documentation][edoc] to be interactively edited in the same way that |
|
407
|
wiki articles can be. (Indeed, the associated `fileedit-glob` feature |
|
408
|
allows you to restrict the editor to working *only* on files that can be |
|
409
|
treated as embedded documentation.) This feature operates in much the |
|
410
|
same way as the new wiki editor, so most of what we said above applies. |
|
411
|
|
|
412
|
_Workaround:_ This feature is an alternative to Fossil’s traditional |
|
413
|
mode of file management: clone the repository, open it somewhere, edit a |
|
414
|
file locally, and commit the changes. |
|
415
|
|
|
416
|
_Graceful Fallback:_ There is no technical reason why someone could not |
|
417
|
write a `<noscript>` wrapped alternative to the current JavaScript based |
|
418
|
`/fileedit` implementation. It would have all of the same downsides as |
|
419
|
the old wiki editor: the users would lose their place on each save, they |
|
420
|
would have no local backup if something crashes, etc. Still, we are |
|
421
|
likely to accept such a [contribution][cg] as long as it doesn’t |
|
422
|
interfere with the new editor. |
|
423
|
|
|
424
|
[edoc]: /doc/trunk/www/embeddeddoc.wiki |
|
425
|
[fedit]: /doc/trunk/www/fileedit-page.md |
|
426
|
|
|
427
|
|
|
428
|
### <a id="ln"></a>Line Numbering |
|
429
|
|
|
430
|
When viewing source files, Fossil offers to show line numbers in some |
|
431
|
cases. ([Example][mainc].) Toggling them on and off is currently handled |
|
432
|
in JavaScript, rather than forcing a page-reload via a button click. |
|
433
|
|
|
434
|
_Workaround:_ Manually edit the URL to give the “`ln`” query parameter |
|
435
|
per [the `/file` docs](/help/www/file). |
|
436
|
|
|
437
|
_Potential Better Workaround:_ Someone sufficiently interested could |
|
438
|
[provide a patch][cg] to add a `<noscript>` wrapped HTML button that |
|
439
|
would reload the page with this parameter included/excluded to implement |
|
440
|
the toggle via a server round-trip. |
|
441
|
|
|
442
|
A related feature is Fossil’s JavaScript-based interactive method |
|
443
|
for selecting a range of lines by clicking the line numbers when they’re |
|
444
|
visible. JavaScript lets us copy the resulting URL to the clipboard |
|
445
|
to share your selection with others. |
|
446
|
|
|
447
|
_Workaround:_ These interactive features would be difficult and |
|
448
|
expensive (in terms of network I/O) to implement without JavaScript. A |
|
449
|
far simpler alternative is to manually edit the URL, per above. |
|
450
|
|
|
451
|
[mainc]: https://fossil-scm.org/home/artifact?ln&name=87d67e745 |
|
452
|
|
|
453
|
|
|
454
|
### <a id="sxsdiff"></a>Side-by-Side Diff Mode |
|
455
|
|
|
456
|
The default “diff” view is a side-by-side mode. If either of the boxes |
|
457
|
of output — the “from” and “to” versions of the repo contents for that |
|
458
|
check-in — requires a horizontal scroll bar given the box content, font |
|
459
|
size, browser window width, etc., both boxes will usually end up needing |
|
460
|
to scroll since they should contain roughly similar content. Fossil |
|
461
|
therefore scrolls both boxes when you drag the scroll bar on one because |
|
462
|
if you want to examine part of a line scrolled out of the HTML element |
|
463
|
in one box, you probably want to examine the same point on that line in |
|
464
|
the other box. |
|
465
|
|
|
466
|
_Graceful Fallback:_ Manually scroll both boxes to sync their views. |
|
467
|
|
|
468
|
### <a id="diffcontext"></a>Diff Context Loading |
|
469
|
|
|
470
|
Fossil’s diff views can |
|
471
|
dynamically load more lines of context around changed blocks. The UI |
|
472
|
controls for this feature are injected using JavaScript when the page |
|
473
|
initializes and make use of XHR requests to fetch data from the |
|
474
|
fossil instance. |
|
475
|
|
|
476
|
_Graceful Fallback:_ The UI controls for this feature do not appear |
|
477
|
when JS is unavailable, leaving the user with the "legacy" static diff |
|
478
|
view. |
|
479
|
|
|
480
|
|
|
481
|
### <a id="sort"></a>Table Sorting |
|
482
|
|
|
483
|
On pages showing a data table, the column headers may be clickable to do |
|
484
|
a client-side sort of the data on that column. |
|
485
|
|
|
486
|
_Potential Workaround:_ This feature could be enhanced to do the sort on |
|
487
|
the server side using a page re-load. |
|
488
|
|
|
489
|
|
|
490
|
### <a id="tree"></a>File Browser Tree View |
|
491
|
|
|
492
|
The [file browser’s tree view mode][tv] uses JavaScript to handle clicks |
|
493
|
on folders so they fold and unfold without needing to reload the entire |
|
494
|
page. |
|
495
|
|
|
496
|
_Graceful Fallback:_ When JavaScript is disabled, clicks on folders |
|
497
|
reload the page showing the folder contents instead. You then have to |
|
498
|
use the browser’s Back button to return to the higher folder level. |
|
499
|
|
|
500
|
[tv]: https://fossil-scm.org/home/dir?type=tree |
|
501
|
|
|
502
|
|
|
503
|
### <a id="hash"></a>Version Hashes |
|
504
|
|
|
505
|
In several places where the Fossil web UI shows a check-in hash or |
|
506
|
similar, hovering over that check-in shows a tooltip with details about |
|
507
|
the type of artifact the hash refers to and allows you to click to copy |
|
508
|
the hash to the clipboard. |
|
509
|
|
|
510
|
_Graceful Fallback:_ When JavaScript is disabled, these tooltips simply |
|
511
|
don’t appear, but you can still select and copy the hash using your |
|
512
|
platform’s “copy selected text” feature. |
|
513
|
|
|
514
|
|
|
515
|
### <a id="bots"></a>Anti-Bot Defenses |
|
516
|
|
|
517
|
Fossil has [anti-bot defenses][abd], and it has some JavaScript code |
|
518
|
that, if run, can drop some of these defenses if it decides a given page |
|
519
|
was loaded on behalf of a human, rather than a bot. |
|
520
|
|
|
521
|
_Graceful Fallback:_ You can use Fossil’s anonymous login feature to |
|
522
|
convince the remote Fossil instance that you are not a bot. Coupled with |
|
523
|
[the Fossil user capability system][caps], you can restore all |
|
524
|
functionality that Fossil’s anti-bot defenses deny to random web clients |
|
525
|
by default. |
|
526
|
|
|
527
|
[abd]: ./antibot.wiki |
|
528
|
[caps]: ./caps/ |
|
529
|
|
|
530
|
|
|
531
|
### <a id="hbm"></a>Hamburger Menu |
|
532
|
|
|
533
|
Several of the stock skins (including the default) include a “hamburger menu” (☰) which uses |
|
534
|
JavaScript to show a simplified version of the Fossil UI site map using |
|
535
|
an animated-in dropdown. |
|
536
|
|
|
537
|
_Graceful Fallback:_ Clicking the hamburger menu button with JavaScript |
|
538
|
disabled will take you to the `/sitemap` page instead of showing a |
|
539
|
simplified version of that page’s content in a drop-down. |
|
540
|
|
|
541
|
_Workaround:_ You can remove this button by [editing the skin][cskin] |
|
542
|
header. |
|
543
|
|
|
544
|
|
|
545
|
### <a id="clock"></a>Clock |
|
546
|
|
|
547
|
Some stock Fossil skins include JavaScript-based features such as the |
|
548
|
current time of day. The Xekri skin includes this in its header, for |
|
549
|
example. A clock feature requires JavaScript to get the time on initial |
|
550
|
page load and then to update it once a minute. |
|
551
|
|
|
552
|
You may observe that the server could provide the current time when |
|
553
|
generating the page, but the client and server may not be in the same |
|
554
|
time zone, and there is no reliably-provided information from the client |
|
555
|
that would let the server give the page load time in the client’s local |
|
556
|
time zone. The server could only tell you *its* local time at page |
|
557
|
request time, not the client’s time. That still wouldn’t be a “clock,” |
|
558
|
since without client-side JavaScript code running, that part of the page |
|
559
|
couldn’t update once a second. |
|
560
|
|
|
561
|
_Potential Graceful Fallback:_ You may consider showing the server’s |
|
562
|
page generation time rather than the client’s wall clock time in the |
|
563
|
local time zone to be a useful fallback for the current feature, so [a |
|
564
|
patch to do this][cg] may well be accepted. Since this is not a |
|
565
|
*necessary* Fossil feature, an interested user is unlikely to get the |
|
566
|
core developers to do this work for them. |
|
567
|
|
|
568
|
|
|
569
|
### <a id="chat"></a>Chat |
|
570
|
|
|
571
|
The [chat feature](./chat.md) is deeply dependent |
|
572
|
on JavaScript. There is no obvious way to do this sort of thing without |
|
573
|
active client-side code of some sort. |
|
574
|
|
|
575
|
_Potential Workaround:_ It would not be especially difficult for someone |
|
576
|
sufficiently motivated to build a Fossil chat gateway, connecting to |
|
577
|
IRC, Jabber, etc. The messages are stored in the repository’s `chat` |
|
578
|
table with monotonically increasing IDs, so a poller that did something |
|
579
|
like |
|
580
|
|
|
581
|
SELECT xfrom, xmsg FROM chat WHERE msgid > 1234; |
|
582
|
|
|
583
|
…would pull the messages submitted since the last poll. Making the |
|
584
|
gateway bidirectional should be possible as well, as long as it properly |
|
585
|
uses SQLite transactions. |
|
586
|
|
|
587
|
### <a id="brlist"></a>List of branches |
|
588
|
|
|
589
|
The [`/brlist`](/brlist) page uses JavaScript to enable |
|
590
|
selection of several branches for further study via `/timeline`. |
|
591
|
Client-side script interactively responds to checkboxes' events |
|
592
|
and constructs a special hyperlink in the submenu. |
|
593
|
Clicking this hyperlink loads a `/timeline` page that shows |
|
594
|
only these selected branches (and the related check-ins). |
|
595
|
|
|
596
|
_Potential Workaround:_ A user can manually construct an appropriate |
|
597
|
regular expession and put it into the "Tag Filter" entry of the |
|
598
|
`/timeline` page (in its advanced mode). |
|
599
|
|
|
600
|
---- |
|
601
|
|
|
602
|
## <a id="future"></a>Future Plans for JavaScript in Fossil |
|
603
|
|
|
604
|
As of mid-2020, the informal provisional plan is to increase Fossil |
|
605
|
UI's use of JavaScript considerably compared to its historically minimal |
|
606
|
uses. To that end, a framework of Fossil-centric APIs is being developed |
|
607
|
in conjunction with new features to consolidate Fossil's historical |
|
608
|
hodgepodge of JavaScript snippets into a coherent code base. |
|
609
|
|
|
610
|
When deciding which features to port to JavaScript, the rules of thumb |
|
611
|
for this ongoing effort are: |
|
612
|
|
|
613
|
- Pages which primarily display data (e.g. the timeline) will remain |
|
614
|
largely static HTML with graceful fallbacks for all places they do |
|
615
|
use JavaScript. Though JavaScript can be used effectively to power |
|
616
|
all sorts of wonderful data presentation, Fossil currently doesn't |
|
617
|
benefit greatly from doing so. We use JavaScript on these pages only |
|
618
|
to improve their usability, not to define their primary operations. |
|
619
|
|
|
620
|
- Pages which act as editors of some sort (e.g. the `/info` page) are |
|
621
|
prime candidates for getting the same treatment as the old wiki |
|
622
|
editor: reimplemented from the ground up in JavaScript using Ajax |
|
623
|
type techniques. Similarly, a JS-driven overhaul is planned for the |
|
624
|
forum’s post editor. |
|
625
|
|
|
626
|
These are guidelines, not immutable requirements. Our development |
|
627
|
direction is guided by our priorities: |
|
628
|
|
|
629
|
1) Features the developers themselves want to have and/or work on. |
|
630
|
|
|
631
|
2) Features end users request which catch the interest of one or more |
|
632
|
developers, provided the developer(s) in question are in a position to |
|
633
|
expend the effort. |
|
634
|
|
|
635
|
3) Features end users and co-contributors can convince a developer into |
|
636
|
coding even when they really don't want to. |
|
637
|
|
|
638
|
In all of this, Fossil's project lead understandably has the final |
|
639
|
say-so in whether any given feature indeed gets merged into the mainline |
|
640
|
trunk. Development of any given feature, no matter how much effort was |
|
641
|
involved, does not guarantee its eventual inclusion into the public |
|
642
|
releases. |
|
643
|
|