Fossil SCM
Updates to the www/serverext.wiki document.
Commit
7f82b38088ca748e6959d8a1c016348b9bb2302c0fd5e541d5f625e98d215033
Parent
032cef1ded634a3…
1 file changed
+33
-5
+33
-5
| --- www/serverext.wiki | ||
| +++ www/serverext.wiki | ||
| @@ -32,11 +32,11 @@ | ||
| 32 | 32 | If the Fossil server is itself run as |
| 33 | 33 | [./server/any/cgi.md|CGI], then add a line to the |
| 34 | 34 | [./cgi.wiki#extroot|CGI script file] that says: |
| 35 | 35 | |
| 36 | 36 | <pre> |
| 37 | -extroot: <i>DIRECTORY</i> | |
| 37 | + extroot: <i>DIRECTORY</i> | |
| 38 | 38 | </pre> |
| 39 | 39 | |
| 40 | 40 | Or, if the Fossil server is being run using the |
| 41 | 41 | "[./server/any/none.md|fossil server]" or |
| 42 | 42 | "[./server/any/none.md|fossil ui]" or |
| @@ -45,18 +45,21 @@ | ||
| 45 | 45 | |
| 46 | 46 | The <i>DIRECTORY</i> is the DOCUMENT_ROOT for the CGI. |
| 47 | 47 | Files in the DOCUMENT_ROOT are accessed via URLs like this: |
| 48 | 48 | |
| 49 | 49 | <pre> |
| 50 | -https://example-project.org/ext/<i>FILENAME</i> | |
| 50 | + https://example-project.org/ext/<i>FILENAME</i> | |
| 51 | 51 | </pre> |
| 52 | 52 | |
| 53 | 53 | In other words, access files in DOCUMENT_ROOT by appending the filename |
| 54 | 54 | relative to DOCUMENT_ROOT to the [/help?cmd=/ext|/ext] |
| 55 | 55 | page of the Fossil server. |
| 56 | -Files that are readable but not executable are returned as static | |
| 57 | -content. Files that are executable are run as CGI. | |
| 56 | + | |
| 57 | + * Files that are readable but not executable are returned as static | |
| 58 | + content. | |
| 59 | + | |
| 60 | + * Files that are executable are run as CGI. | |
| 58 | 61 | |
| 59 | 62 | <h3>2.1 Example #1</h3> |
| 60 | 63 | |
| 61 | 64 | The source code repository for SQLite is a Fossil server that is run |
| 62 | 65 | as CGI. The URL for the source code repository is [https://sqlite.org/src]. |
| @@ -117,16 +120,41 @@ | ||
| 117 | 120 | of [https://www.tcl.tk|Tcl/Tk] and so he tends to gravitate toward Tcl-based |
| 118 | 121 | technologies like Wapp.) The fileup1 script is a demo program that lets |
| 119 | 122 | the user upload a file using a form, and then displays that file in the reply. |
| 120 | 123 | There is a link on the page that causes the fileup1 script to return a copy |
| 121 | 124 | of its own source-code, so you can see how it works. |
| 125 | + | |
| 126 | +<h3>2.3 Example #3</h3> | |
| 127 | + | |
| 128 | +For Fossil versions dated 2025-03-23 and later, the "--extpage FILENAME" | |
| 129 | +option to the [/help?cmd=ui|fossil ui] command is a short cut that treats | |
| 130 | +FILENAME as a CGI extension. When the ui command starts up a new web browser | |
| 131 | +pages, it points that page to the FILENAME extension. So if FILENAME is | |
| 132 | +a static content file (such as an HTML file or | |
| 133 | +[/md_rules|Markdown] or [/wiki_rules|Wiki] document), then the | |
| 134 | +rendered content of the file is displayed. Meanwhile, the user can be | |
| 135 | +editing the source text for that document in a separate window, and | |
| 136 | +periodically pressing "Reload" on the web browser to instantly view the | |
| 137 | +rendered results. | |
| 138 | + | |
| 139 | +For example, the author of this documentation page is running | |
| 140 | +"<tt>fossil ui --extpage www/serverext.wiki</tt>" while editing this | |
| 141 | +very paragraph, and presses Reload from time to time to view his | |
| 142 | +edits. | |
| 143 | + | |
| 144 | +A same idea applies when developing new CGI applications using a script | |
| 145 | +language (for example using [https://wapp.tcl.tk|Wapp]). Run the | |
| 146 | +command "<tt>fossil ui --extpage SCRIPT</tt>" where SCRIPT is the name | |
| 147 | +of the application script, while editing that script in a separate | |
| 148 | +window, then press Reload periodically on the web browser to test the | |
| 149 | +script. | |
| 122 | 150 | |
| 123 | 151 | <h2 id="cgi-inputs">3.0 CGI Inputs</h2> |
| 124 | 152 | |
| 125 | 153 | The /ext extension mechanism is an ordinary CGI interface. Parameters |
| 126 | 154 | are passed to the CGI program using environment variables. The following |
| 127 | -standard CGI environment variables are supported: | |
| 155 | +standard CGI environment variables are supplied: | |
| 128 | 156 | |
| 129 | 157 | * AUTH_TYPE |
| 130 | 158 | * AUTH_CONTENT |
| 131 | 159 | * CONTENT_LENGTH |
| 132 | 160 | * CONTENT_TYPE |
| 133 | 161 |
| --- www/serverext.wiki | |
| +++ www/serverext.wiki | |
| @@ -32,11 +32,11 @@ | |
| 32 | If the Fossil server is itself run as |
| 33 | [./server/any/cgi.md|CGI], then add a line to the |
| 34 | [./cgi.wiki#extroot|CGI script file] that says: |
| 35 | |
| 36 | <pre> |
| 37 | extroot: <i>DIRECTORY</i> |
| 38 | </pre> |
| 39 | |
| 40 | Or, if the Fossil server is being run using the |
| 41 | "[./server/any/none.md|fossil server]" or |
| 42 | "[./server/any/none.md|fossil ui]" or |
| @@ -45,18 +45,21 @@ | |
| 45 | |
| 46 | The <i>DIRECTORY</i> is the DOCUMENT_ROOT for the CGI. |
| 47 | Files in the DOCUMENT_ROOT are accessed via URLs like this: |
| 48 | |
| 49 | <pre> |
| 50 | https://example-project.org/ext/<i>FILENAME</i> |
| 51 | </pre> |
| 52 | |
| 53 | In other words, access files in DOCUMENT_ROOT by appending the filename |
| 54 | relative to DOCUMENT_ROOT to the [/help?cmd=/ext|/ext] |
| 55 | page of the Fossil server. |
| 56 | Files that are readable but not executable are returned as static |
| 57 | content. Files that are executable are run as CGI. |
| 58 | |
| 59 | <h3>2.1 Example #1</h3> |
| 60 | |
| 61 | The source code repository for SQLite is a Fossil server that is run |
| 62 | as CGI. The URL for the source code repository is [https://sqlite.org/src]. |
| @@ -117,16 +120,41 @@ | |
| 117 | of [https://www.tcl.tk|Tcl/Tk] and so he tends to gravitate toward Tcl-based |
| 118 | technologies like Wapp.) The fileup1 script is a demo program that lets |
| 119 | the user upload a file using a form, and then displays that file in the reply. |
| 120 | There is a link on the page that causes the fileup1 script to return a copy |
| 121 | of its own source-code, so you can see how it works. |
| 122 | |
| 123 | <h2 id="cgi-inputs">3.0 CGI Inputs</h2> |
| 124 | |
| 125 | The /ext extension mechanism is an ordinary CGI interface. Parameters |
| 126 | are passed to the CGI program using environment variables. The following |
| 127 | standard CGI environment variables are supported: |
| 128 | |
| 129 | * AUTH_TYPE |
| 130 | * AUTH_CONTENT |
| 131 | * CONTENT_LENGTH |
| 132 | * CONTENT_TYPE |
| 133 |
| --- www/serverext.wiki | |
| +++ www/serverext.wiki | |
| @@ -32,11 +32,11 @@ | |
| 32 | If the Fossil server is itself run as |
| 33 | [./server/any/cgi.md|CGI], then add a line to the |
| 34 | [./cgi.wiki#extroot|CGI script file] that says: |
| 35 | |
| 36 | <pre> |
| 37 | extroot: <i>DIRECTORY</i> |
| 38 | </pre> |
| 39 | |
| 40 | Or, if the Fossil server is being run using the |
| 41 | "[./server/any/none.md|fossil server]" or |
| 42 | "[./server/any/none.md|fossil ui]" or |
| @@ -45,18 +45,21 @@ | |
| 45 | |
| 46 | The <i>DIRECTORY</i> is the DOCUMENT_ROOT for the CGI. |
| 47 | Files in the DOCUMENT_ROOT are accessed via URLs like this: |
| 48 | |
| 49 | <pre> |
| 50 | https://example-project.org/ext/<i>FILENAME</i> |
| 51 | </pre> |
| 52 | |
| 53 | In other words, access files in DOCUMENT_ROOT by appending the filename |
| 54 | relative to DOCUMENT_ROOT to the [/help?cmd=/ext|/ext] |
| 55 | page of the Fossil server. |
| 56 | |
| 57 | * Files that are readable but not executable are returned as static |
| 58 | content. |
| 59 | |
| 60 | * Files that are executable are run as CGI. |
| 61 | |
| 62 | <h3>2.1 Example #1</h3> |
| 63 | |
| 64 | The source code repository for SQLite is a Fossil server that is run |
| 65 | as CGI. The URL for the source code repository is [https://sqlite.org/src]. |
| @@ -117,16 +120,41 @@ | |
| 120 | of [https://www.tcl.tk|Tcl/Tk] and so he tends to gravitate toward Tcl-based |
| 121 | technologies like Wapp.) The fileup1 script is a demo program that lets |
| 122 | the user upload a file using a form, and then displays that file in the reply. |
| 123 | There is a link on the page that causes the fileup1 script to return a copy |
| 124 | of its own source-code, so you can see how it works. |
| 125 | |
| 126 | <h3>2.3 Example #3</h3> |
| 127 | |
| 128 | For Fossil versions dated 2025-03-23 and later, the "--extpage FILENAME" |
| 129 | option to the [/help?cmd=ui|fossil ui] command is a short cut that treats |
| 130 | FILENAME as a CGI extension. When the ui command starts up a new web browser |
| 131 | pages, it points that page to the FILENAME extension. So if FILENAME is |
| 132 | a static content file (such as an HTML file or |
| 133 | [/md_rules|Markdown] or [/wiki_rules|Wiki] document), then the |
| 134 | rendered content of the file is displayed. Meanwhile, the user can be |
| 135 | editing the source text for that document in a separate window, and |
| 136 | periodically pressing "Reload" on the web browser to instantly view the |
| 137 | rendered results. |
| 138 | |
| 139 | For example, the author of this documentation page is running |
| 140 | "<tt>fossil ui --extpage www/serverext.wiki</tt>" while editing this |
| 141 | very paragraph, and presses Reload from time to time to view his |
| 142 | edits. |
| 143 | |
| 144 | A same idea applies when developing new CGI applications using a script |
| 145 | language (for example using [https://wapp.tcl.tk|Wapp]). Run the |
| 146 | command "<tt>fossil ui --extpage SCRIPT</tt>" where SCRIPT is the name |
| 147 | of the application script, while editing that script in a separate |
| 148 | window, then press Reload periodically on the web browser to test the |
| 149 | script. |
| 150 | |
| 151 | <h2 id="cgi-inputs">3.0 CGI Inputs</h2> |
| 152 | |
| 153 | The /ext extension mechanism is an ordinary CGI interface. Parameters |
| 154 | are passed to the CGI program using environment variables. The following |
| 155 | standard CGI environment variables are supplied: |
| 156 | |
| 157 | * AUTH_TYPE |
| 158 | * AUTH_CONTENT |
| 159 | * CONTENT_LENGTH |
| 160 | * CONTENT_TYPE |
| 161 |