From 1ef2ff2c55d9c409b1a573550cd65369add66063 Mon Sep 17 00:00:00 2001
From: Alexander Baryshnikov <dev@baryshnikov.net>
Date: Mon, 1 Jun 2020 21:46:22 +0800
Subject: [PATCH] docs: add info about static serving and add blog example

---
 docs/_layouts/default.html |  3 ++
 docs/examples/blog.md      | 90 ++++++++++++++++++++++++++++++++++++++
 docs/manifest.md           |  1 +
 docs/static.md             | 20 +++++++++
 ui                         |  2 +-
 5 files changed, 115 insertions(+), 1 deletion(-)
 create mode 100644 docs/examples/blog.md
 create mode 100644 docs/static.md
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
index c60be2d..cbc1019 100644
--- a/docs/_layouts/default.html
+++ b/docs/_layouts/default.html
@@ -55,6 +55,9 @@ <h3>Features & docs</h3>
             <li><a href="/scheduler">Scheduler</a></li>
             <li><a href="/security">Security</a></li>
         </ul>
+        <ul>
+            <li><a href="/static">Static files</a></li>
+        </ul>
         <h3>API</h3>
         <ul>
             <li><a href="/api/lambda_api">Lambda</a></li>
diff --git a/docs/examples/blog.md b/docs/examples/blog.md
new file mode 100644
index 0000000..69e85cf
--- /dev/null
+++ b/docs/examples/blog.md
@@ -0,0 +1,90 @@
+## Example
+
+This is basic public comment board example: 
+
+* anyone can post comment with any name
+* only last N post will be displayed
+* comments stored in SQLite
+
+**Do not use the example in production!** Comments board without authorization it's a bad, very bad idea.
+However, the example should be safe for XSS attacks due to user data escaping.
+
+* Create new project based on python template (UI-> Dashboard -> Python)
+* Click files, then click on app.py file. Copy following content:
+
+```python
+import os
+import sqlite3
+import html
+
+# how many last comments to show
+last_num = 20
+# db location
+db_name = 'comments.db'
+# define out database schema
+schema = '''
+CREATE TABLE IF NOT EXISTS comment(
+    id      INT PRIMARY KEY,
+    name    VARCHAR(100) NOT NULL,
+    comment VARCHAR(255) NOT NULL
+)
+'''
+# html template
+html_template = '''<html><body>
+<div>
+<form method="post" enctype="application/x-www-form-urlencoded">
+<input type="text" placeholder="your name" name="name" maxlength="100"/><br/>
+<textarea placeholder="comment" maxlength="255" name="comment"></textarea><br/>
+<button type="submit">send</button>
+</form>
+</div>
+{comments}
+</body></html>'''
+
+# form values
+name = os.getenv('NAME')  
+comment = os.getenv('COMMENT') 
+
+# connect to local database
+with sqlite3.connect(db_name) as conn:
+    cur = conn.cursor()
+    cur.execute(schema)
+    cur.execute('INSERT INTO comment (name, comment) VALUES (?, ?)', (name, comment))
+    conn.commit()
+    latest = cur.execute(f'SELECT id, name, comment FROM comment ORDER BY id DESC LIMIT {last_num}')
+    # re-render main page comment block
+    blocks = []
+    for (id, name, comment) in latest:
+        blocks.append(f'<div id="{id}"><p>From: <b>{html.escape(name)}</b></p><p>{html.escape(comment)}</p></div><hr/>')
+    page = html_template.replace('{comments}', "\n".join(blocks))
+    with open('static/index.html', 'wt') as f:
+        f.write(page)
+```
+
+* In UI create directory `static`, click on it, create file `index.html` and put following content:
+
+```html
+<html><body>
+<div>
+<form method="post" enctype="application/x-www-form-urlencoded">
+<input type="text" placeholder="your name" name="name" maxlength="100"/><br/>
+<textarea placeholder="comment" maxlength="255" name="comment"></textarea><br/>
+<button type="submit">send</button>
+</form>
+</div>
+</body></html>
+```
+
+* Setup mapping for form values: click on Mapping tab and add:
+  * output headers: `Content-Type: text/html` 
+  * query params should be mapped as: comment to `COMMENT` and name to `NAME`
+  * set static dir to `static`
+  * click 'save'
+
+![image](https://user-images.githubusercontent.com/6597086/83414645-6e1db100-a450-11ea-9ded-2e5d93ac00f7.png)
+
+
+Done!
+
+Now open URL from overview section by browser and try to post something.
+
diff --git a/docs/manifest.md b/docs/manifest.md
index b90910b..8a836e7 100644
--- a/docs/manifest.md
+++ b/docs/manifest.md
@@ -44,6 +44,7 @@ Example: for python with virtualenv with main script `app.py` it will look like:
 * **public** (optional, boolean): if false, check all requests against `tokens`
 * **aliases** (optional, array of string): aliases/links for the lambda, useful to make permanent URL, [see aliases doc](aliases.md)
 * **cron** (option, array of `Cron`): scheduled actions
+* **static** (optional, string): path to directory inside lambda to serve static files; if defined the GET and HEAD methods will not be available for handler
 
 ### Cron
 
diff --git a/docs/static.md b/docs/static.md
new file mode 100644
index 0000000..6b1d32c
--- /dev/null
+++ b/docs/static.md
@@ -0,0 +1,20 @@
+# Static files
+
+Static files can be served by `GET` request from the specified folder.
+Using static serving together with lambda allows you to create dynamic service with UI (like blog or comments).
+
+To enable the feature, set in [manifest](manifest.md) field `static` to relative path to the directory with static files
+ (must be subfolder of lambda directory). 
+
+If the feature enabled the GET and HEAD methods will not be available for handler (lambda).
+Same security restrictions applied to static files as to lambda (security checks performed before file handling).
+
+UI:
+
+1. Click to already create app
+2. Select mapping, enter static directory name, relative to the application root, or clean ir to remove
+3. Click save
+
+Related examples:
+
+* [blog](examples/blog.md)
\ No newline at end of file
diff --git a/ui b/ui
index c3c075a..a703201 160000
--- a/ui
+++ b/ui
@@ -1 +1 @@
-Subproject commit c3c075a954d5faa66f560cb016061d3f0f8dd7b3
+Subproject commit a70320163cc8c05f964765b3f913f009678bbb54
