|
1
|
<title>Fossil Forums</title> |
|
2
|
|
|
3
|
<h2>Introduction</h2> |
|
4
|
|
|
5
|
Fossil includes a built-in discussion forum, designed to substitute |
|
6
|
for a mailing list. Email notification is available to receive posts, |
|
7
|
but the web-based UI must be used to enter new posts. Advantages of |
|
8
|
the forum include: |
|
9
|
|
|
10
|
* <b>Easy to Administer:</b> If you have already set up a |
|
11
|
[./server/|Fossil server] with [./alerts.md|email alerts] |
|
12
|
then turning on the forum feature |
|
13
|
is just a matter of flipping some permission bits. There is |
|
14
|
no new software to install and configure, and the same logins |
|
15
|
and passwords work. |
|
16
|
|
|
17
|
* <b>Consistent Display:</b> Forum posts can be in [/md_rules|Markdown], |
|
18
|
[/wiki_rules|Fossil Wiki], or plain text. Whichever format is used, the result is |
|
19
|
displayed consistently across all platforms and operating systems and |
|
20
|
between mobile devices and desktops. |
|
21
|
|
|
22
|
* <b>Editable:</b> Forum posts can be amended after they are sent, |
|
23
|
to fix typos or provide updates. The original posts are preserved |
|
24
|
as part of the historical record, but only the amended posts are |
|
25
|
displayed by default. |
|
26
|
|
|
27
|
* <b>Built-in Full-Text Search:</b> Forum posts can be included in |
|
28
|
the index used by the built-in Fossil search logic. |
|
29
|
|
|
30
|
* <b>Off-Line Access:</b> Because forum posts are synced along with |
|
31
|
all other artifacts, you can search the forum, or add new posts, or |
|
32
|
edit existing posts, all while off-line. |
|
33
|
|
|
34
|
* <b>Automatically Cross-Referenced To Other Fossil Artifacts:</b> Because forum |
|
35
|
posts are normal Fossil artifacts, you can link from them to |
|
36
|
other Fossil artifacts (check-ins, wiki, tickets) and from those other |
|
37
|
artifacts to forum posts. The reverse links are recognized and |
|
38
|
displayed automatically on the receiver. |
|
39
|
|
|
40
|
* <b>Malefactor Resistant:</b> Because Fossil accepts forum posts |
|
41
|
only via the web UI, it is more resistent to spam. Passers-by |
|
42
|
can post to the forum anonymously (subject to moderation), without |
|
43
|
the hassle of a sign-up process. |
|
44
|
|
|
45
|
* <b>Distributed and Tamper-Proof:</b> Posts are stored in the Fossil |
|
46
|
repository using the same [./fileformat.wiki | DAG/Merkle-tree design] |
|
47
|
that Fossil uses to store your check-ins, wiki documents, etc. |
|
48
|
Forum posts sync to cloned repositories. |
|
49
|
|
|
50
|
<h2>Example Installations</h2> |
|
51
|
|
|
52
|
Both the [forum:/forum|Fossil project itself] and the |
|
53
|
[https://sqlite.org/forum/forum|SQLite project] use the Fossil forum in place |
|
54
|
of mailing lists. The forum has worked well on both projects. The ability |
|
55
|
to post anonymously provides a low-resistance path for people to report |
|
56
|
problems, resulting in more problems being reported and fixed. |
|
57
|
The ability to moderate and amend forum posts means that the |
|
58
|
forums contain better information. And backups and archives |
|
59
|
are as easy as running "clone". |
|
60
|
|
|
61
|
Both Fossil and SQLite keep their forums as separate repositories. |
|
62
|
But there is no requirement to do this. A forum can be coresident in |
|
63
|
the same repository with the source code. |
|
64
|
|
|
65
|
<h2 id="setup">Setting up a Fossil Forum</h2> |
|
66
|
|
|
67
|
<h3 id="caps">Capabilities</h3> |
|
68
|
|
|
69
|
By default, no Fossil user has permission to use the forums except for |
|
70
|
users with Setup and Admin capabilities, which get these as part of the |
|
71
|
large package of other capabilities they get. |
|
72
|
|
|
73
|
For public Fossil repositories that wish to accept new users without |
|
74
|
involving a human, go into Admin → Access and enable the "Allow |
|
75
|
users to register themselves" setting. You may also wish to give users |
|
76
|
in [./caps/#ucat | the <tt>anonymous</tt> user category] the |
|
77
|
<b>[./caps/ref.html#2 | RdForum]</b> and |
|
78
|
<b>[./caps/ref.html#3 | WrForum]</b> |
|
79
|
capabilities: this allows people to post without creating an account |
|
80
|
simply by solving [./antibot.wiki | a simple CAPTCHA]. |
|
81
|
|
|
82
|
For a private repository, you probably won't want to give the |
|
83
|
<tt>anonymous</tt> user any forum access, but you may wish to give the |
|
84
|
<b>RdForum</b> capability to users in the <tt>reader</tt> category. |
|
85
|
|
|
86
|
For either type of repository, you are likely to want to give at least |
|
87
|
the <b>[./caps/ref.html#4 | WrTForum]</b> capability to users in the <tt>developer</tt> |
|
88
|
category. If you did not give the <b>RdForum</b> capability to |
|
89
|
<tt>anonymous</tt> above, you should give <tt>developer</tt> that |
|
90
|
capability here if you choose to give it <b>WrForum</b> or |
|
91
|
<b>WrTForum</b> capability. |
|
92
|
|
|
93
|
If you want to use the email alert feature, by default only those |
|
94
|
users in the Setup and Admin user categories can make use of it. Grant |
|
95
|
the <b>[./caps/ref.html#7 | EmailAlert]</b> capability to give others access to this feature. |
|
96
|
Alternately, you can handle alert signups outside of Fossil, with |
|
97
|
a Setup or Admin users manually signing users up via Admin → |
|
98
|
Notification. You'll want to grant this capability to the |
|
99
|
<tt>nobody</tt> user category if you want anyone to sign up without any |
|
100
|
restrictions. Give it to <tt>anonymous</tt> instead if you want the |
|
101
|
user to solve a simple CAPTCHA before signing up. Or, give it to |
|
102
|
<tt>reader</tt> or <tt>developer</tt> if you want only users with Fossil |
|
103
|
logins to have this ability. (That's assuming you give one or both of |
|
104
|
these capabilities to every user on your Fossil repository.) |
|
105
|
|
|
106
|
By following this advice, you should not need to tediously add |
|
107
|
capabilities to individual accounts except in atypical cases, such as |
|
108
|
to grant the <b>[./caps/ref.html#5 | ModForum]</b> capability to an uncommonly |
|
109
|
highly-trusted user. |
|
110
|
|
|
111
|
|
|
112
|
<h3 id="skin">Skin Setup</h3> |
|
113
|
|
|
114
|
If you create a new Fossil repository with version 2.7 or newer, its |
|
115
|
default skin is already set up correctly for typical forum |
|
116
|
configurations. |
|
117
|
|
|
118
|
If you have an existing repository, you have two choices if you want its |
|
119
|
skin to be upgraded to support forums: |
|
120
|
|
|
121
|
<ol> |
|
122
|
<li>Go into Admin → Skins and switch from your current skin to |
|
123
|
one of the stock skins. If you were on a stock skin, just switch away |
|
124
|
from your current one to the actual stock skin, since they will be |
|
125
|
different after the upgrade.</li> |
|
126
|
|
|
127
|
<li>If you have local customization that you do not want to throw |
|
128
|
away, you can use the diff feature of Fossil's skin editor to show how |
|
129
|
the skins differ.</li> |
|
130
|
</ol> |
|
131
|
|
|
132
|
The remainder of this section summarizes the differences you're expected |
|
133
|
to see when taking option #2. |
|
134
|
|
|
135
|
The first thing is that you'll need to add something like the following |
|
136
|
to the Header part of the skin to create the navbar link: |
|
137
|
|
|
138
|
<verbatim> |
|
139
|
if {[anycap 23456] || [anoncap 2] || [anoncap 3]} { |
|
140
|
menulink /forum Forum |
|
141
|
} |
|
142
|
</verbatim> |
|
143
|
|
|
144
|
These rules say that any logged-in user with any [./caps/ref.html#2 | |
|
145
|
forum-related capability] or an anonymous user <b>RdForum</b> or |
|
146
|
<b>WrForum</b> capability will see the "Forum" navbar |
|
147
|
link, which just takes you to <tt>/forum</tt>. |
|
148
|
|
|
149
|
The exact code you need here varies depending on which skin you're |
|
150
|
using. Follow the style you see for the other navbar links. |
|
151
|
|
|
152
|
The new forum feature also brings many new CSS styles to the table. If |
|
153
|
you're using the stock skin or something sufficiently close, the changes |
|
154
|
may work with your existing skin as-is. Otherwise, you might need to |
|
155
|
adjust some things, such as the background color used for the selected |
|
156
|
forum post: |
|
157
|
|
|
158
|
<verbatim> |
|
159
|
div.forumSel { |
|
160
|
background-color: rgba(0, 0, 0, 0.05); |
|
161
|
} |
|
162
|
</verbatim> |
|
163
|
|
|
164
|
That overrides the default — a hard-coded light cyan — with a 95% |
|
165
|
transparent black overlay instead, which simply darkens your skin's |
|
166
|
normal background color underneath the selected post. That should work |
|
167
|
with almost any background color except for very dark background colors. |
|
168
|
For dark skins, an inverse of the above trick will work better: |
|
169
|
|
|
170
|
<verbatim> |
|
171
|
div.forumSel { |
|
172
|
background-color: rgba(255, 255, 255, 0.05); |
|
173
|
} |
|
174
|
</verbatim> |
|
175
|
|
|
176
|
That overlays the background with 5% white to lighten it slightly. |
|
177
|
|
|
178
|
Another new forum-related CSS style you might want to reflect into your |
|
179
|
existing skin is: |
|
180
|
|
|
181
|
<verbatim> |
|
182
|
div.forumPosts a:visited { |
|
183
|
color: #6A7F94; |
|
184
|
} |
|
185
|
</verbatim> |
|
186
|
|
|
187
|
This changes the clicked-hyperlink color for the forum post links on the |
|
188
|
main <tt>/forum</tt> page only, which allows your browser's history |
|
189
|
mechanism to show which threads a user has read and which not. The link |
|
190
|
color will change back to the normal link color — indicating "unread" — |
|
191
|
when a reply is added to an existing thread because that changes where |
|
192
|
the link from the <tt>/forum</tt> page points, taking you to the newest |
|
193
|
post in the thread. |
|
194
|
|
|
195
|
The color given above is suitable for the stock skin. |
|
196
|
|
|
197
|
Beware that when changing this example, there are some |
|
198
|
[https://hacks.mozilla.org/2010/03/privacy-related-changes-coming-to-css-vistited/ |
|
199
|
| stringent restrictions] in modern browsers to prevent snoopy web sites |
|
200
|
from brute-forcing your browsing history. (See the link for the method, |
|
201
|
which explains the restrictions.) |
|
202
|
|
|
203
|
|
|
204
|
<h3 id="search">Enable Forum Search</h3> |
|
205
|
|
|
206
|
One of the underlying assumptions of the forum feature is that you will |
|
207
|
want to be able to search the forum archives, so the <tt>/forum</tt> |
|
208
|
page always includes a search box. Since that depends on search being |
|
209
|
enabled on the Fossil repository, Fossil warns that search is disabled |
|
210
|
until you go into Admin → Search and enable the "Search Forum" |
|
211
|
setting. |
|
212
|
|
|
213
|
You may want to enable some of the other Fossil search features while |
|
214
|
you're in there. All of this does come at some CPU and I/O cost, which |
|
215
|
is why it's disabled by default. |
|
216
|
|
|
217
|
|
|
218
|
<h3 id="sso">Single Sign-On</h3> |
|
219
|
|
|
220
|
If you choose to host your discussion forums within the same repository |
|
221
|
as your project's other Fossil-managed content, you inherently have a |
|
222
|
single sign-on system. Contrast third-party mailing list and forum |
|
223
|
software where you either end up with two separate user tables and |
|
224
|
permission sets, or you must go to significant effort to integrate the |
|
225
|
two login systems. |
|
226
|
|
|
227
|
You may instead choose to host your forums in a Fossil repository |
|
228
|
separate from your project's main Fossil repository. A good reason to do |
|
229
|
this is that you have a public project where very few of those |
|
230
|
participating in the forum have special capability bits for project |
|
231
|
assets managed by Fossil, so you wish to segregate the two user sets. |
|
232
|
|
|
233
|
Yet, what of the users who will have logins on both repositories? Some |
|
234
|
users will be trusted with access to the project's main Fossil |
|
235
|
repository, and these users will probably also participate in the |
|
236
|
project's Fossil-hosted forum. Fossil has a feature to solve this |
|
237
|
problem: [./caps/login-groups.md | login groups]. |
|
238
|
|
|
239
|
|
|
240
|
<h3 id="alerts">Email Alerts (a.k.a. Notifications)</h3> |
|
241
|
|
|
242
|
Internet email service has become rather complicated since its initial |
|
243
|
simple and insecure implementation decades ago. Fossil's role in all of |
|
244
|
this is rather small at the moment, but the details of the integration |
|
245
|
are complex enough to justify [./alerts.md | a separate document]. |
|
246
|
|
|
247
|
(The other reason that document is separate is that Fossil's email |
|
248
|
alerts system also gets used by features of Fossil other than the |
|
249
|
forum.) |
|
250
|
|
|
251
|
|
|
252
|
<h2 id="access">Accessing the Forum</h2> |
|
253
|
|
|
254
|
There are many paths to a repository's Fossil forum: |
|
255
|
|
|
256
|
<ul> |
|
257
|
<li> |
|
258
|
If you're using the default Fossil skin as shipped with Fossil |
|
259
|
2.7+ or one [#skin | updated] to support it, there |
|
260
|
is a Forum button in the navbar which appears for users able to |
|
261
|
access the forum. With the default skin, that button will only |
|
262
|
appear if the user's browser window is at least |
|
263
|
1200 pixels wide. The |
|
264
|
Fossil admin can adjust this limit in the skin's CSS section, down |
|
265
|
near the bottom in the definition of the `wideonly` style. |
|
266
|
</li> |
|
267
|
|
|
268
|
<li>The other stock skins have this button in them as of 2.7 as well, |
|
269
|
without the screen width restriction, since the navbar in those skins |
|
270
|
wraps on narrow screens more gracefully than the default skin |
|
271
|
does.</li> |
|
272
|
|
|
273
|
<li>Users who set up their Fossil repository under prior versions and |
|
274
|
who now have local skin changes they don't want to overwrite by |
|
275
|
reverting to the stock 2.7 version of the skin they chose to start |
|
276
|
with can easily [#skin | edit their skin] to include these links.</li> |
|
277
|
|
|
278
|
<li>A "Forum" link appears in the drop-down panel when you click the |
|
279
|
default skin's hamburger menu (☰) while logged in as any user |
|
280
|
with one or more of the [#caps | user capabilities listed above].</li> |
|
281
|
|
|
282
|
<li>That same link also appears on the repository's <tt>/sitemap</tt> |
|
283
|
page, since it provides the content for the hamburger menu's |
|
284
|
panel.</li> |
|
285
|
</ul> |
|
286
|
|
|
287
|
The forum uses JavaScript to allow for a more comfortable editing |
|
288
|
experience than is possible with static HTML. If one takes issue with, |
|
289
|
or has issues with, the JavaScript-based forum editing and response |
|
290
|
features, there are several ways around them: (1) Clients with JS |
|
291
|
disabled should see the legacy (pre-mid-2026) input forms and |
|
292
|
buttons. (2) Adding <code>?nojs</code> to any <code>/forumpost</code> |
|
293
|
URL will disable plugging-in of the JS UI elements. (3) When forum |
|
294
|
posts are visited via <code>/info</code> instead of |
|
295
|
<code>/forumpost</code>, the JS-based UI elements do not plug |
|
296
|
themselves in, leaving the legacy UI intact. |
|
297
|
|
|
298
|
|
|
299
|
<h2 id="moderation">How Moderation Works</h2> |
|
300
|
|
|
301
|
In this section, we're going to call all of the following a "forum |
|
302
|
update:" |
|
303
|
|
|
304
|
* create a new post |
|
305
|
* reply to an existing post |
|
306
|
* edit a post or reply |
|
307
|
|
|
308
|
When a person with the normal <b>WrForum</b> capability |
|
309
|
updates the forum, Fossil saves the update in its block chain, but this |
|
310
|
update is impermanent because of two other table updates made at the |
|
311
|
same time: |
|
312
|
|
|
313
|
<ol> |
|
314
|
<li>Fossil saves the update artifact's ID in its <tt>private</tt> |
|
315
|
table, preventing Fossil from sending such artifacts to any of the |
|
316
|
repository's clones. (This is the same mechanism behind |
|
317
|
[./private.wiki | private branches].)</li> |
|
318
|
|
|
319
|
<li>Fossil also adds a reference to that artifact in the |
|
320
|
<tt>modreq</tt> table, which backs the moderation feature. This is |
|
321
|
what causes Fossil to leave out the Reply button when rendering that |
|
322
|
post's HTML in the forum's web interface.</li> |
|
323
|
</ol> |
|
324
|
|
|
325
|
When a moderator approves an update, Fossil deletes these table entries, |
|
326
|
making the update [./shunning.wiki | semi-permanent]. This changes how Fossil renders the |
|
327
|
HTML for that update. It also means the artifact will now sync to |
|
328
|
users with <b>[./caps/ref.html#g | Clone]</b> capability. |
|
329
|
|
|
330
|
When a forum user edits a moderator-approved artifact, what actually |
|
331
|
happens under the hood is that Fossil writes another artifact to the |
|
332
|
repository which refers to the original version as its parent, causing |
|
333
|
Fossil UI to present the new version instead of the original. The |
|
334
|
original version remains in the repository, just as with historical |
|
335
|
checkins. The parent must remain in the repository for referential |
|
336
|
integrity purposes. |
|
337
|
|
|
338
|
When you "Delete" a moderator-approved post or reply through Fossil UI, |
|
339
|
it's actually an edit with blank replacement content. The only way to |
|
340
|
truly delete such artifacts is through [./shunning.wiki | shunning]. |
|
341
|
|
|
342
|
When a user with <b>WrTForum</b> capability |
|
343
|
updates the forum, it happens in the same way except that Fossil skips |
|
344
|
the <tt>private</tt> and <tt>modreq</tt> table insertions. |
|
345
|
|
|
346
|
When a moderator rejects an update, that artifact is unceremoniously |
|
347
|
removed from the tip of the block chain. This is safe because Fossil |
|
348
|
prevents replies to a reply or post awaiting moderator approval, so |
|
349
|
referential integrity cannot be harmed. Rejecting an edit is even |
|
350
|
safer, since the original post remains behind, so that replies continue |
|
351
|
to refer to that original post. |
|
352
|
|
|
353
|
|
|
354
|
<h2 id="mod-user">Using the Moderation Feature</h2> |
|
355
|
|
|
356
|
Having described all of the work that Fossil performs under the hood on |
|
357
|
behalf of its users, we can now give the short list of work left for the |
|
358
|
repository's administrators and moderators: |
|
359
|
|
|
360
|
<ol> |
|
361
|
<li>Add the <b>[./caps/ref.html#5 | ModForum]</b> capability to any of |
|
362
|
your users who should have this ability. You don't need to do this |
|
363
|
for any user with <b>[./caps/ref.html#s | Setup]</b> or |
|
364
|
<b>[./caps/ref.html#a | Admin]</b> capability; it's |
|
365
|
[/artifact/b16221ffb736caa2?ln=1246-1257 | already included].</li> |
|
366
|
|
|
367
|
<li>When someone updates the forum, an entry will appear in the |
|
368
|
timeline if the type filter is set to "Forum" or "Any Type". If that |
|
369
|
user has only the <b>WrForum</b> capability, any |
|
370
|
other user with the <b>ModForum</b> capability |
|
371
|
will see a conditional link appear at the top of the main forum |
|
372
|
page: "Moderation Requests". Clicking this takes the moderator to |
|
373
|
the <tt>/modreq</tt> page. A moderator may wish to keep the main |
|
374
|
forum page open in a browser tab, reloading it occasionally to see |
|
375
|
when the "Moderation Requests" link reappears.</li> |
|
376
|
|
|
377
|
<li>A moderator viewing an update pending moderation sees two |
|
378
|
buttons at the bottom, "Approve" and "Reject" in place of the |
|
379
|
"Delete" button that the post's creator sees. Beware that both |
|
380
|
actions are durable and have no undo. Be careful!</li> |
|
381
|
</ol> |
|
382
|
|
|
383
|
<h2 id="close-post">Closing Forum Posts</h2> |
|
384
|
|
|
385
|
As of version 2.23 the forum interface supports the notion of |
|
386
|
"closing" posts. By default, only users with the [./caps/index.md|'s' |
|
387
|
and 'a' capabilities] may close or re-open posts, or reply to closed |
|
388
|
posts. If the [/help/forum-close-policy|forum-close-policy |
|
389
|
configuration option] is enabled then users with |
|
390
|
[./caps/index.md|forum-moderator permissions] may also perform those |
|
391
|
actions. |
|
392
|
|
|
393
|
Closing a post has the following implications: |
|
394
|
|
|
395
|
* Only authorized users may edit or respond to such posts, recursively |
|
396
|
through all responses of that post. |
|
397
|
* Only authorized users may re-open a closed post. |
|
398
|
|
|
399
|
A forum thread may be closed at any given point in the conversation, |
|
400
|
not just the starting point of the thread, and affects that specific |
|
401
|
post and all existing responses to it. |
|
402
|
|
|
403
|
Note that closing a post is effectively an "advisory lock" and may be |
|
404
|
bypassed. Any user, admin or otherwise, who can push changes to a |
|
405
|
repository may bypass closure of a post by setting the appropriate |
|
406
|
artifact tags on a local copy and pushing those changes to a remote |
|
407
|
copy of the forum. |
|
408
|
|
|
409
|
The option to close a post, permissions permitting, appears as a |
|
410
|
"Close" button on the currently-selected post. If the selected post is |
|
411
|
alread closed, a "Re-open" button will be shown instead. In order to |
|
412
|
re-open a post, <em>the closed post itself</em> must be |
|
413
|
selected. Selecting a response to that post, which is implicitly |
|
414
|
closed by the closure of its parent, will <em>not</em> offer a re-open |
|
415
|
option. |
|
416
|
|
|
417
|
Though forum users are permitted to delete their own posts, they are |
|
418
|
not permitted, without appropriate permissions, to close their own |
|
419
|
posts. This is intentional, as closing one's own post can be used to |
|
420
|
antagonize other forum users. For example, by posting something |
|
421
|
trollish or highly controversial in nature and closing the post to |
|
422
|
further responses. |
|
423
|
|
|
424
|
<h2 id="status">Setting Post Statuses</h2> |
|
425
|
|
|
426
|
As of version 2.29 forum posts may be tagged with a status. The |
|
427
|
setting <tt>forum-statuses</tt> controls whether this feature is is |
|
428
|
enabled. If it is not set, is not valid JSON5, or has only a single |
|
429
|
entry, then status are not shown in the forum. |
|
430
|
|
|
431
|
<tt>forum-statuses</tt> is a JSON5-format array of objects in the |
|
432
|
following format: |
|
433
|
|
|
434
|
<verbatim> |
|
435
|
[ |
|
436
|
{label:"Open", value:"open"}, |
|
437
|
{label:"Resolved", value:"resolved"} |
|
438
|
... |
|
439
|
]</verbatim> |
|
440
|
|
|
441
|
The list defines the legal statuses for forum posts and syncs with |
|
442
|
other project-level settings. All "label" and "value" members must be |
|
443
|
unique within the scope of that list. |
|
444
|
|
|
445
|
The "value" values must be legal for use as HTML "dataset" members so |
|
446
|
that they can be used for with CSS selectors to apply per-status |
|
447
|
styling. |
|
448
|
|
|
449
|
If the list is valid JSON5 and has two or more entries then the forum |
|
450
|
behavior changes in the following ways: |
|
451
|
|
|
452
|
* Each TR element of the main <tt>/forum</tt> view table gets a |
|
453
|
<tt>data-status="X"</tt> member, where "X" is the value part from |
|
454
|
the associated status. This can be used to style the statuses |
|
455
|
in the site skin using CSS selectors such as<br> |
|
456
|
<tt>body.cpage-forum div.forumPosts tr[data-status="open"]</tt><br> |
|
457
|
Because there is no default status list, no predefined styles |
|
458
|
are applied. |
|
459
|
* The forum list shows the "label" value of the current status and |
|
460
|
a selection list of available filters. It elides the status column |
|
461
|
when filtering on a specific status. |
|
462
|
* The root of each thread, when selected, gets a new UI control for |
|
463
|
displaying or editing the status, depending on permissions. |
|
464
|
* A drop-down selection list is added to the <tt>/forum</tt> page |
|
465
|
for filtering based on the status. |
|
466
|
|
|
467
|
A list with only a single entry is treated as empty, the justification |
|
468
|
being that if there is only one option then the UI does not need to be |
|
469
|
cluttered with it. |
|
470
|
|
|
471
|
This setting is applied via a <tt>status</tt> tag on the first version |
|
472
|
of a legal post. That tag may be set to any value from the "values" |
|
473
|
members of the <tt>forum-statuses</tt> list. |
|
474
|
|
|
475
|
Status tag rules: |
|
476
|
|
|
477
|
* <tt>status</tt> is only observed on the root of each thread. The UI |
|
478
|
does nothing with that tag on responses. |
|
479
|
* The first list entry is considered to be the default status. Any post |
|
480
|
which has no <tt>status</tt> tag, or has a <tt>status</tt> tag value |
|
481
|
which is not in that list, is assumed for most purposes to have the |
|
482
|
value of the first entry in the list. |
|
483
|
* The tag is applied only to the first version of any given post. The |
|
484
|
UI ensures that the tag is applied to the proper post, even when |
|
485
|
rendering a newer version. |
|
486
|
|
|
487
|
Caveat: a "closed" status is not recommended because it's easy to confuse with |
|
488
|
the <a href='#close-post'>"closed" tag feature</a>, which behaves considerably |
|
489
|
differently and predates that "status" tag support by about three years. The |
|
490
|
"closed" semantics cannot be trivially consolidated with those of "status" |
|
491
|
but we reserve the right to do so at some point. |
|
492
|
|
|
493
|
<h2 id="attachments">Attachments</h2> |
|
494
|
|
|
495
|
As of version 2.29 users with the [./caps/index.md|'B' capability] may |
|
496
|
attach files to forum posts. Files may not be attached until a forum |
|
497
|
post is saved for the first time, after which an "Attach" button will |
|
498
|
appear in the post when it is selected. Attached files undergo |
|
499
|
moderation exactly like forum posts do. When a moderator accepts a |
|
500
|
pending-moderation posts, all files attached to it which are also |
|
501
|
pending approval are also approved. Similarly, when a moderator |
|
502
|
rejects a pending-moderation post, all files attached to it which are |
|
503
|
also pending approval are rejected. |
|
504
|
|
|
505
|
Developer notes regarding the save-before-attach limitation: |
|
506
|
|
|
507
|
* We cannot add the attachment form to the current post editor |
|
508
|
because (A) the Preview option would upload the files each time |
|
509
|
(B) we cannot pre-populate file selection elements so could not |
|
510
|
restore them when rendering the preview's response. |
|
511
|
* To work around that we need to reimplement the forum editor |
|
512
|
using AJAX-friendly APIs. That would allow us to render a preview |
|
513
|
without reloading the page, to attach multiple files at once, |
|
514
|
to support pasting a screenshot as an attachment, and to submit both |
|
515
|
a new post and its attachments at the same time. |
|
516
|
* We have AJAX-capable preview code in /wiki and /fileedit. |
|
517
|
* We have paste-screenshot code in /chat but integrating it here will |
|
518
|
require adding a "paste" button to the attachment UI. |
|
519
|
|
|
520
|
Developer notes regarding automatic acceptance/rejection of |
|
521
|
attachments: |
|
522
|
|
|
523
|
* There is a race condition here where an admin may approve |
|
524
|
attachments they have not yet seen: user creates posts, admin gets |
|
525
|
notified, admin reads post, user attaches a file at that time, |
|
526
|
admin approves post. |
|
527
|
|
|
528
|
TBD is whether to accept that case or to remove automatic approval of |
|
529
|
attached files. |
|
530
|
|
|
531
|
<h2 id="drafts">Draft Edits</h2> |
|
532
|
|
|
533
|
The forum uses, if available, JavaScript's <code>localStorage</code> |
|
534
|
or <code>sessionStorage</code> to store local drafts of new |
|
535
|
posts, replies, and edits to existing posts. Each time an editor |
|
536
|
input field loses focus, the draft is saved. When viewing a forum |
|
537
|
thread, the Edit and Reply buttons get clearly marked if they |
|
538
|
have an associated local draft. |
|
539
|
|
|
540
|
Local drafts for replies and responses (but not new posts) are |
|
541
|
automatically purged at semi-random intervals. Every Nth visit to a |
|
542
|
forum page has a small chance to run the cleanup, and drafts older |
|
543
|
than 10 days old are purged. |
|
544
|
|
|
545
|
If neither <code>localStorage</code> nor <code>sessionStorage</code> |
|
546
|
are available, it uses a transient storage object which is recreated |
|
547
|
on each page-load, so it cannot store drafts outside of a single |
|
548
|
thread at a time. |
|
549
|
|
|
550
|
Beware: Each draft is keyed to the post it is editing or replied to, |
|
551
|
which means that editing or replying to the same post from different |
|
552
|
tabs will cause collisions. The editor to most recently lose the focus |
|
553
|
will save the draft, overwriting the other. |
|
554
|
|
|
555
|
In browsers which support Web Locks, attempts to edit resp. reply to a |
|
556
|
post which is already being edited resp. replied to in another tab |
|
557
|
will show an error for the second and subsequent tabs. The first tab |
|
558
|
to use the edit/reply buttons will hold a separate Web Lock for each |
|
559
|
and forbid edit/reply access to the post in other tabs until the |
|
560
|
locking tab is closed. |
|
561
|
|
|
562
|
|
|
563
|
<h2 id="padding">Curious Extra Page Padding</h2> |
|
564
|
|
|
565
|
Users may notice that the forum pages get a bunch of padding added to |
|
566
|
the bottom of the page when an editor widget is opened. This is not a |
|
567
|
bug, but a workaround to help avoid the UI jumping around when |
|
568
|
rendering a preview wildly resizes the widget. The effect is |
|
569
|
especially helpful when working on posts while the bottom footer of |
|
570
|
the page is in the viewport, as the footer is a hard boundary against |
|
571
|
scrolling. With the extra padding, the editor widget's top edge shifts |
|
572
|
around less when the preview is shown and hidden. |
|
573
|
|
|
574
|
<h2 id="fork">Forked Edits</h2> |
|
575
|
|
|
576
|
It is possible to "fork" forum messages, in the same way that any |
|
577
|
given check-in may cause a fork. This can happen when a message is |
|
578
|
edited concurrently from two or more browser tabs or via two or more |
|
579
|
fossil instances which subsequently sync with each other. |
|
580
|
|
|
581
|
When a forum post is forked, the UI currently behaves as it does for |
|
582
|
concurrent wiki page edits, showing only the most recent |
|
583
|
edit. Currently (2026-06) the UI is incapable of showing the older |
|
584
|
forked copies but (A) the data are still part of the SCM history and |
|
585
|
(B) there are plans to improve the UI to show such forks. |
|
586
|
|
|
587
|
For trivia's sake, here's a query which finds posts which have |
|
588
|
forks: |
|
589
|
|
|
590
|
<pre><verbatim> |
|
591
|
SELECT bp.rid AS parentRid, bp.uuid parentUuid, count(f.fprev) forkCount |
|
592
|
FROM blob b, blob bp, forumpost f |
|
593
|
WHERE b.rid=f.fpid |
|
594
|
AND f.fprev=bp.rid |
|
595
|
GROUP BY f.fprev |
|
596
|
HAVING forkCount>1; |
|
597
|
</verbatim></pre> |
|
598
|
|
|
599
|
And here's one which lists forked posts: |
|
600
|
|
|
601
|
<pre><verbatim> |
|
602
|
WITH multiparent(mpid) AS ( |
|
603
|
SELECT fprev FROM forumpost f |
|
604
|
GROUP BY fprev |
|
605
|
HAVING count(fprev)>1 |
|
606
|
) |
|
607
|
SELECT datetime(fmtime), forumpost.* |
|
608
|
FROM forumpost, multiparent |
|
609
|
WHERE fprev=mpid |
|
610
|
ORDER BY mpid, fpid, fmtime; |
|
611
|
</verbatim></pre> |
|
612
|
|
|
613
|
The telling part is the <code>fprev</code> column: those with matching |
|
614
|
values forked from the post referred to by <code>fprev</code>. |
|
615
|
|