Fossil SCM
www/forum.wiki: document the file attachment capability and add some developer notes regarding current limitations and overcoming them.
Commit
ff4caf13ba30b08c4409dcce0147f4421b714eaeb1cb154b02f405707d3c905e
Parent
0f934bb0755a5c5…
1 file changed
+42
-3
+42
-3
| --- www/forum.wiki | ||
| +++ www/forum.wiki | ||
| @@ -369,11 +369,11 @@ | ||
| 369 | 369 | actions are durable and have no undo. Be careful!</li> |
| 370 | 370 | </ol> |
| 371 | 371 | |
| 372 | 372 | <h2 id="close-post">Closing Forum Posts</h2> |
| 373 | 373 | |
| 374 | -As of version 2.23, the forum interface supports the notion of | |
| 374 | +As of version 2.23 the forum interface supports the notion of | |
| 375 | 375 | "closing" posts. By default, only users with the [./caps/index.md|'s' |
| 376 | 376 | and 'a' capabilities] may close or re-open posts, or reply to closed |
| 377 | 377 | posts. If the [/help/forum-close-policy|forum-close-policy |
| 378 | 378 | configuration option] is enabled then users with |
| 379 | 379 | [./caps/index.md|forum-moderator permissions] may also perform those |
| @@ -410,12 +410,13 @@ | ||
| 410 | 410 | trollish or highly controversial in nature and closing the post to |
| 411 | 411 | further responses. |
| 412 | 412 | |
| 413 | 413 | <h2 name="status">Setting Post Statuses</h2> |
| 414 | 414 | |
| 415 | -The setting <tt>forum-statuses</tt> controls whether this feature is | |
| 416 | -is enabled. If it is not set, is not valid JSON5, or has only a single | |
| 415 | +As of version 2.29 forum posts may be tagged with a status. The | |
| 416 | +setting <tt>forum-statuses</tt> controls whether this feature is is | |
| 417 | +enabled. If it is not set, is not valid JSON5, or has only a single | |
| 417 | 418 | entry, then status are not shown in the forum. |
| 418 | 419 | |
| 419 | 420 | <tt>forum-statuses</tt> is a JSON5-format array of objects in the |
| 420 | 421 | following format: |
| 421 | 422 | |
| @@ -474,5 +475,43 @@ | ||
| 474 | 475 | |
| 475 | 476 | Caveat: a "closed" status is not recommended because it's easy to confuse with |
| 476 | 477 | the <a href='#close-post'>"closed" tag feature</a>, which behaves considerably |
| 477 | 478 | differently and predates that "status" tag support by about three years. The |
| 478 | 479 | "closed" semantics cannot be trivially consolidated with those of "status". |
| 480 | + | |
| 481 | +<h2 name="attachments">Attachments</h2> | |
| 482 | + | |
| 483 | +As of version 2.29 users with the [./caps/index.md|'B' capabilities] | |
| 484 | +may attach files to forum posts. Files may not be attached until a | |
| 485 | +forum post is saved for the first time, after which an "Attach" button | |
| 486 | +will appear in the post when it is selected. Attached files undergo | |
| 487 | +moderation exactly like forum posts do. When a moderator accepts a | |
| 488 | +pending-moderation posts, all files attached to it which are also | |
| 489 | +pending approval are also approved. Similarly, when a moderator | |
| 490 | +rejects a pending-moderation post, all files attached to it when are | |
| 491 | +also pending approval are rejected. | |
| 492 | + | |
| 493 | +Developer notes regarding the save-before-attach limitation: | |
| 494 | + | |
| 495 | + * We cannot add the attachment form to the current post editor | |
| 496 | + because (A) the Preview option would upload the files each time | |
| 497 | + (B) we cannot pre-populate file selection elements so could not | |
| 498 | + restore them when rendering the preview's response. | |
| 499 | + * To work around that we need to reimplement the forum editor | |
| 500 | + using AJAX-friendly APIs. That would allow us to render a preview | |
| 501 | + without reloading the page, to attach multiple files at once, | |
| 502 | + to support pasting a screenshot as an attachment, and to submit both | |
| 503 | + a new post and its attachments at the same time. | |
| 504 | + * We have AJAX-capable preview code in /wiki and /fileedit. | |
| 505 | + * We have paste-screenshot code in /chat but integrating it here will | |
| 506 | + require adding a "paste" button to the attachment UI. | |
| 507 | + | |
| 508 | +Developer notes regarding automatic acceptance/rejection of | |
| 509 | +attachments: | |
| 510 | + | |
| 511 | + * There is a race condition here where an admin may approve | |
| 512 | + attachments they have not yet seen: user creates posts, admin gets | |
| 513 | + notified, admin reads post, user attaches a file at that time, | |
| 514 | + admin approves post. | |
| 515 | + | |
| 516 | +TBD is whether to accept that case or to remove automatic approval of | |
| 517 | +attached files. | |
| 479 | 518 |
| --- www/forum.wiki | |
| +++ www/forum.wiki | |
| @@ -369,11 +369,11 @@ | |
| 369 | actions are durable and have no undo. Be careful!</li> |
| 370 | </ol> |
| 371 | |
| 372 | <h2 id="close-post">Closing Forum Posts</h2> |
| 373 | |
| 374 | As of version 2.23, the forum interface supports the notion of |
| 375 | "closing" posts. By default, only users with the [./caps/index.md|'s' |
| 376 | and 'a' capabilities] may close or re-open posts, or reply to closed |
| 377 | posts. If the [/help/forum-close-policy|forum-close-policy |
| 378 | configuration option] is enabled then users with |
| 379 | [./caps/index.md|forum-moderator permissions] may also perform those |
| @@ -410,12 +410,13 @@ | |
| 410 | trollish or highly controversial in nature and closing the post to |
| 411 | further responses. |
| 412 | |
| 413 | <h2 name="status">Setting Post Statuses</h2> |
| 414 | |
| 415 | The setting <tt>forum-statuses</tt> controls whether this feature is |
| 416 | is enabled. If it is not set, is not valid JSON5, or has only a single |
| 417 | entry, then status are not shown in the forum. |
| 418 | |
| 419 | <tt>forum-statuses</tt> is a JSON5-format array of objects in the |
| 420 | following format: |
| 421 | |
| @@ -474,5 +475,43 @@ | |
| 474 | |
| 475 | Caveat: a "closed" status is not recommended because it's easy to confuse with |
| 476 | the <a href='#close-post'>"closed" tag feature</a>, which behaves considerably |
| 477 | differently and predates that "status" tag support by about three years. The |
| 478 | "closed" semantics cannot be trivially consolidated with those of "status". |
| 479 |
| --- www/forum.wiki | |
| +++ www/forum.wiki | |
| @@ -369,11 +369,11 @@ | |
| 369 | actions are durable and have no undo. Be careful!</li> |
| 370 | </ol> |
| 371 | |
| 372 | <h2 id="close-post">Closing Forum Posts</h2> |
| 373 | |
| 374 | As of version 2.23 the forum interface supports the notion of |
| 375 | "closing" posts. By default, only users with the [./caps/index.md|'s' |
| 376 | and 'a' capabilities] may close or re-open posts, or reply to closed |
| 377 | posts. If the [/help/forum-close-policy|forum-close-policy |
| 378 | configuration option] is enabled then users with |
| 379 | [./caps/index.md|forum-moderator permissions] may also perform those |
| @@ -410,12 +410,13 @@ | |
| 410 | trollish or highly controversial in nature and closing the post to |
| 411 | further responses. |
| 412 | |
| 413 | <h2 name="status">Setting Post Statuses</h2> |
| 414 | |
| 415 | As of version 2.29 forum posts may be tagged with a status. The |
| 416 | setting <tt>forum-statuses</tt> controls whether this feature is is |
| 417 | enabled. If it is not set, is not valid JSON5, or has only a single |
| 418 | entry, then status are not shown in the forum. |
| 419 | |
| 420 | <tt>forum-statuses</tt> is a JSON5-format array of objects in the |
| 421 | following format: |
| 422 | |
| @@ -474,5 +475,43 @@ | |
| 475 | |
| 476 | Caveat: a "closed" status is not recommended because it's easy to confuse with |
| 477 | the <a href='#close-post'>"closed" tag feature</a>, which behaves considerably |
| 478 | differently and predates that "status" tag support by about three years. The |
| 479 | "closed" semantics cannot be trivially consolidated with those of "status". |
| 480 | |
| 481 | <h2 name="attachments">Attachments</h2> |
| 482 | |
| 483 | As of version 2.29 users with the [./caps/index.md|'B' capabilities] |
| 484 | may attach files to forum posts. Files may not be attached until a |
| 485 | forum post is saved for the first time, after which an "Attach" button |
| 486 | will appear in the post when it is selected. Attached files undergo |
| 487 | moderation exactly like forum posts do. When a moderator accepts a |
| 488 | pending-moderation posts, all files attached to it which are also |
| 489 | pending approval are also approved. Similarly, when a moderator |
| 490 | rejects a pending-moderation post, all files attached to it when are |
| 491 | also pending approval are rejected. |
| 492 | |
| 493 | Developer notes regarding the save-before-attach limitation: |
| 494 | |
| 495 | * We cannot add the attachment form to the current post editor |
| 496 | because (A) the Preview option would upload the files each time |
| 497 | (B) we cannot pre-populate file selection elements so could not |
| 498 | restore them when rendering the preview's response. |
| 499 | * To work around that we need to reimplement the forum editor |
| 500 | using AJAX-friendly APIs. That would allow us to render a preview |
| 501 | without reloading the page, to attach multiple files at once, |
| 502 | to support pasting a screenshot as an attachment, and to submit both |
| 503 | a new post and its attachments at the same time. |
| 504 | * We have AJAX-capable preview code in /wiki and /fileedit. |
| 505 | * We have paste-screenshot code in /chat but integrating it here will |
| 506 | require adding a "paste" button to the attachment UI. |
| 507 | |
| 508 | Developer notes regarding automatic acceptance/rejection of |
| 509 | attachments: |
| 510 | |
| 511 | * There is a race condition here where an admin may approve |
| 512 | attachments they have not yet seen: user creates posts, admin gets |
| 513 | notified, admin reads post, user attaches a file at that time, |
| 514 | admin approves post. |
| 515 | |
| 516 | TBD is whether to accept that case or to remove automatic approval of |
| 517 | attached files. |
| 518 |