initial commitHEADmaster

1 files changed, 317 insertions, 0 deletions

diff --git a/www/fileedit-page.md b/www/fileedit-page.md
new file mode 100644
index 0000000..c8f7eeb
--- /dev/null
+++ b/www/fileedit-page.md
@@ -0,0 +1,317 @@
+# The fileedit Page
+
+This document describes the limitations of, caveats for, and
+disclaimers for the [](/fileedit) page, which provides users with
+ basic editing features for files via the web interface when they
+ have [checkin privileges](./caps/index.md).
+
+# Important Caveats and Disclaimers
+
+Predictably, the ability to edit files in a repository from a web
+browser halfway around the world comes with several obligatory caveats
+and disclaimers...
+
+## <a id="cap"></a> `/fileedit` Does *Nothing* by Default.
+
+In order to "activate" it, a user with [the "setup"
+permission](./caps/index.md) must set the
+[fileedit-glob](/help/fileedit-glob) repository setting to a
+comma- or newline-delimited list of globs representing a whitelist of
+files which may be edited online. Any user with commit access may then
+edit files matching one of those globs. Certain pages within the UI
+get an "edit" link added to them when the current user's permissions
+and the whitelist both permit editing of that file.
+
+## <a id="csrf"></a> CSRF & HTTP Referrer Headers
+
+In order to protect against [Cross-site Request Forgery (CSRF)][csrf]
+attacks, Fossil UI features which write to the database require that
+the browser send the so-called [HTTP `Referer` header][referer]
+(noting that the misspelling of "referrer" is a historical accident
+which has long-since been standardized!). Modern browsers, by default,
+include such information automatically for *interactive* actions which
+lead to a request, e.g. clicking on a link back to the same
+server. However, `/fileedit` uses asynchronous ["XHR"][xhr]
+connections, which browsers *may* treat differently than strictly
+interactive elements.
+
+- **Firefox**: configuration option `network.http.sendRefererHeader`
+  specifies whether the `Referer` header is sent. It must have a value
+  of 2 (which is the default) for XHR requests to get the `Referer`
+  header. Purely interactive Fossil features, in which users directly
+  activate links or forms, work with a level of 1 or higher.
+- **Chrome**: apparently requires an add-on in order to change this
+  policy, so Chrome without such an add-on will not suppress this
+  header.
+- **Safari**: ???
+- **Other browsers**: ???
+
+If `/fileedit` shows an error message saying "CSRF violation," the
+problem is that the browser is not sending a `Referer` header to XHR
+connections. Fossil does not offer a way to disable its CSRF
+protections.
+
+[referer]: https://en.wikipedia.org/wiki/HTTP_referer
+[csrf]: https://en.wikipedia.org/wiki/Cross-site_request_forgery
+[xhr]: https://en.wikipedia.org/wiki/XMLHttpRequest
+
+## <a id="commit"></a> `/fileedit` **Works by Creating Commits**
+
+Thus any edits made via that page become a normal part of the
+repository.
+
+## <a id="intent"></a> `/fileedit` is *Intended* for use with Embedded Docs
+
+... and similar text files, and is most certainly
+**not intended for editing code**.
+
+Editing files with unusual syntax requirements, e.g. hard tabs in
+makefiles, may break them. *You Have Been Warned.*
+
+Similarly, though every effort is made to retain the end-of-line
+style used by being-edited files, the round-trip through an HTML
+textarea element may change the EOLs. The Commit section of the page
+offers three different options for how to treat newlines when saving
+changes. **Files with mixed EOL styles** *will be normalized to a single
+EOL style* when modified using `/fileedit`. When "inheriting" the EOL
+style from a previous version which has mixed styles, the first EOL
+style detected in the previous version of the file is used.
+
+## <a id="checkout"></a> `/fileedit` **is Not a Replacement for a Checkout**
+
+A full-featured checkout allows far more possibilities than this basic
+online editor permits, and the feature scope of `/fileedit` is
+intentionally kept small, implementing only the bare necessities
+needed for performing basic edits online. It *is not, and will never
+be, a replacement for a checkout.*
+
+It is to be expected that users will want to do "more" with this
+page, and we generally encourage feature requests, but be aware that
+certain types of ostensibly sensible feature requests *will be
+rejected* for `/fileedit`. These include, but are not limited to:
+
+- Features which are already provided by other pages, e.g.
+the ability to create a new named branch or add tags.
+- Features which would require re-implementing significant
+capabilities provided only within a checkout (e.g. merging files).
+- The ability to edit/manipulate files which are in a local
+checkout. (If you have a checkout, use your local editor, not
+`/fileedit`.)
+- Editing of non-text files, e.g. images. Use a checkout and your
+preferred graphics editor.
+- Support for syncing/pulling/pushing of a repository before and/or
+after edits. Those features cannot be *reliably* provided via a web
+interface for several reasons.
+
+Similarly, some *potential* features have significant downsides,
+abuses, and/or implementation hurdles which make the decision of
+whether or not to implement them subject to notable contributor
+debate. e.g. the ability to add new files or remove/rename older
+files.
+
+
+## <a id="storage"></a> `/fileedit` **Stores Only Limited Local Edits While Working**
+
+When changes are made to a given checkin/file combination,
+`/fileedit` will, if possible, store them in [`window.localStorage`
+or `window.sessionStorage`][html5storage], if available, but...
+
+- Which storage is used is unspecified and may differ across
+  environments.
+- If neither of those is available, the storage is transient and
+  will not survive a page reload. In this case, the UI issues a clear
+  warning in the editor tab.
+- It stores only the most recent checkin/file combinations which have
+  been modified (exactly how many may differ - the number will be
+  noted somewhere in the UI). Note that changing the "executable bit"
+  is counted as a modification, but the checkin *comment* is *not*
+  and is reset after a commit.
+- If its internal limit on the number of modified files is exceeded,
+  it silently discards the oldest edits to keep the list at its limit.
+
+Edits are saved whenever the editor component fires its "change"
+event, which essentially means as soon as it loses input focus. Thus
+to force the browser to save any pending changes, simply click
+somwhere on the page outside of the editor.
+
+Exactly how long `localStorage` will survive, and how much it or
+`sessionStorage` can hold, is environment-dependent. `sessionStorage`
+will survive until the current browser tab is closed, but it survives
+across reloads of the same tab.
+
+If `/fileedit` determines that no persistent storage is available a
+warning is displayed on the editor page.
+
+[html5storage]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API
+
+## <a id="power"></a> The Power is Yours, but...
+
+> "With great power comes great responsibility."
+
+**Use this feature judiciously, *if at all*.**
+
+Now, with those warnings and caveats out of the way...
+
+-----
+
+# <a id="tips"></a> Tips and Tricks
+
+## <a id="global-js"></a> `fossil` Global-scope JS Object
+
+`/fileedit` is largely implemented in JavaScript, and makes heavy use
+of the global-scope `fossil` object, which provides
+infrastructure-level features intended for use by Fossil UI pages.
+(That said, that infrastructure was introduced with `/fileedit`, and
+most pages do not use it.)
+
+The `fossil.page` object represents the UI's current page (on pages
+which make use of this API - most do not). That object supports
+listening to page-specific events so that JS code installed via
+[client-side edits to the site skin's footer](customskin.md) may react
+to those changes somehow. The next section describes one such use for
+such events...
+
+## <a id="syn-hl"></a> Integrating Syntax Highlighting
+
+Assuming a repository has integrated a 3rd-party syntax highlighting
+solution, it can probably (depending on its API) be told how to
+highlight `/fileedit`'s wiki/markdown-format previews. Here are
+instructions for doing so with [highlightjs](https://highlightjs.org/):
+
+At the very bottom of the [site skin's footer](customskin.md), add a
+script tag similar to the following:
+
+```javascript
+<script nonce="$<nonce>">
+if(window.fossil && fossil.page && fossil.page.name==='fileedit'){
+  fossil.page.addEventListener(
+    'fileedit-preview-updated',
+    (ev)=>{
+     if(ev.detail.previewMode==='wiki'){
+       ev.detail.element.querySelectorAll(
+         'code[class^=language-]'
+        ).forEach((e)=>hljs.highlightBlock(e));
+     }
+    }
+  );
+}
+</script>
+```
+
+Note that the `nonce="$<nonce>"` part is intended to be entered
+literally as shown above. It will be expanded to contain the current
+request's nonce value when the page is rendered.
+
+The first line of the script just ensures that the expected JS-level
+infrastructure is loaded. It's only loaded in the `/fileedit` page and
+possibly pages added or "upgraded" since `/fileedit`'s introduction.
+
+The part in the `if` block adds an event listener to the `/fileedit`
+app which gets called when the preview is refreshed. That event
+contains 3 properties:
+
+- `previewMode`: a string describing the current preview mode: `wiki`
+  (which includes Fossil-native wiki and markdown), `text`,
+  `htmlInline`, `htmlIframe`. We should "probably" only highlight wiki
+  text, and thus the example above limits its work to that type of
+  preview. It won't work with `htmlIframe`, as that represents an
+  iframe element which contains a complete HTML document.
+- `element`: the DOM element in which the preview is rendered.
+- `mimetype`: the mimetype of the being-previewed content, as determined
+  by Fossil (by its file extension).
+
+The event listener callback shown above doesn't use the `mimetype`,
+but makes use of the other two. It fishes all `code` blocks out of
+the preview which explicitly have a CSS class named
+`language-`something, and then asks highlightjs to highlight them.
+
+## <a id="editor"></a> Integrating a Custom Editor Widget
+
+(These instructions also work for the `/wikiedit` page by replacing
+"fileedit" with "wikiedit" in any strings or symbol names!)
+
+It is possible to replace `/fileedit`'s basic text-editing widget (a
+`textarea` element) with a fancy 3rd-party editor widget by following
+these instructions...
+
+All JavaScript code which follows is assumed to be in a script tag
+similar to the one shown in the previous section:
+
+```javascript
+<script nonce="$<nonce>">
+if(window.fossil && fossil.page && fossil.page.name==='fileedit'){
+  // code specific to the fileedit page goes here
+}
+</script>
+```
+
+First, install proxy functions so that `fossil.page.fileContent()`
+can get and set your content:
+
+```
+fossil.page.setContentMethods(
+  function(){ return text-form content of your widget },
+  function(content){ set text-form content of your widget }
+};
+```
+
+Secondly, we need to alert the editor app when there are changes so
+that it can do things like store edits locally so that they are not
+lost on a page reload. How that is done is completely dependent on the
+3rd-party editor widget, but it generically looks something like:
+
+```
+myCustomWidget.on('eventName', ()=>fossil.page.notifyOfChange());
+```
+
+Lastly, if the 3rd-party editor does *not* hide or remove the native
+editor widget, and does not inject itself into the DOM on the caller's
+behalf, we can replace the native widget with the 3rd-party one with:
+
+```javascript
+fossil.page.replaceEditorWidget(yourNewWidgetElement);
+```
+
+That method must be passed a DOM element and may only be called once:
+it *removes itself* the first time it is called.
+
+That should be all there is to it. When `fossil.page` needs to get the
+being-edited content, it will call the installed content-getter
+function with no arguments, and when it sets the content (immediately
+after (re)loading a file or grabbing local edits), it will pass that
+content to the installed content-setter method. Those, in turn will
+trigger the installed proxies and fire any relevant events.
+
+Below is an example of Fossil skin footer content which plugs in the
+TinyMCE HTML editor into the `/wikiedit` page, but the process is
+identical for `/fileedit` (noting that `/fileedit` may need to be able
+to edit multiple types of files for which a special-purpose editor
+like TinyMCE may not be suitable). Note that any paths to CSS and JS
+resources of course need to be modified to suit one's own
+installation.
+
+```
+<!-- TinyMCE CSS and JS: -->
+<link href="$<home>/doc/ckout/skin.min.css" rel="stylesheet" type="text/css">
+<link href="$<home>/doc/ckout/content.min.css" rel="stylesheet" type="text/css">
+<script src='$<home>/doc/ckout/tinymce.min.js'></script>
+<script src='$<home>/doc/ckout/theme.min.js'></script>
+<script src='$<home>/doc/ckout/icons.min.js'></script>
+<!-- Integrate TinyMCE into /wikiedit: -->
+<script nonce="$<nonce>">
+if(window.fossil && window.fossil.page.name==='wikiedit'){
+  window.fossil.onPageLoad( function(){
+    const elemId = 'wikiedit-content-editor';
+    tinymce.init({selector: 'textarea#'+elemId});
+    const widget = tinymce.get(elemId);
+    fossil.page.setContentMethods(
+      function(){return widget.getContent()},
+      function(content){widget.setContent(content)}
+    );
+    widget.on('change', function(){
+      if(widget.isDirty()) fossil.page.notifyOfChange();
+    });
+  });
+}
+</script>
+```