Index: www/fileedit-page.md ================================================================== --- www/fileedit-page.md +++ www/fileedit-page.md @@ -9,11 +9,11 @@ Predictably, the ability to edit files in a repository from a web browser halfway around the world comes with several obligatory caveats and disclaimers... -## `/fileedit` Does *Nothing* by Default. +## `/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?cmd=fileedit-glob) repository setting to a comma- or newline-delimited list of globs representing a whitelist of @@ -20,11 +20,11 @@ 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. -## CSRF & HTTP Referrer Headers +## 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 @@ -53,16 +53,16 @@ [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 -## `/fileedit` **Works by Creating Commits** +## `/fileedit` **Works by Creating Commits** Thus any edits made via that page become a normal part of the repository. -## `/fileedit` is *Intended* for use with Embedded Docs +## `/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 @@ -75,11 +75,11 @@ 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. -## `/fileedit` **is Not a Replacement for a Checkout** +## `/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 @@ -108,11 +108,11 @@ whether or not to implement them subject to notable contributor debate. e.g. the ability to add new files or remove/rename older files. -## `/fileedit` **Stores Only Limited Local Edits While Working** +## `/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... @@ -142,23 +142,23 @@ If `/filepage` determines that no peristent storage is available a warning is displayed on the editor page. [html5storage]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API -## The Power is Yours, but... +## 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... ----- -# Tips and Tricks +# Tips and Tricks -## `fossil` Global-scope JS Object +## `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 @@ -169,11 +169,11 @@ 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... -## Integrating Syntax Highlighting +## 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/): @@ -223,11 +223,11 @@ The event listener callback shown above doesn't use the `mimetype`, but makes used 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. -## Integrating a Custom Editor Widget +## Integrating a Custom Editor Widget (These instructions also work for the `/wikiedit` page by eplacing "fileedit" with "wikiedit" in any strings or symbol names!) It is possible to replace `/filepage`'s basic text-editing widget (a