add an example for forms with a variable number of fields

See #38

Author: lovasoa

examples/forms with a variable number of fields/README.md

@@ -0,0 +1,40 @@
+# Handling forms with a variable number of fields
+
+This example shows how to handle forms with a number of fields
+that is not known in advance, but depends on the contents of the database.
+
+## The model
+
+We have a database with a table
+`products` that contains the products,
+a table `orders` that contains the orders,
+and a table `order_items` that contains the items of each order.
+
+We want to display a form to create a new order, with a field for each product.
+
+We cannot know in advance how many products there are,
+so we cannot write a simple insert statement for `orders_items`,
+like
+
+```sql
+INSERT INTO order_items (product_id, quantity)
+VALUES (:product_1, :product_1_quantity);
+```
+
+Instead, we use a single POST variable of type array to store the
+product IDs and quantities, like so:
+
+```sql
+SELECT 
+    'product_quantity[]'   AS name,
+    'Quantity of ' || name AS label
+FROM products
+```
+
+And then we parse the array in SQLite with the [JSON_EACH](https://www.sqlite.org/json1.html#jeach) function.
+
+## Screenshots
+
+![](./screenshots/home.png)
+![](./screenshots/order-form.png)
+![](./screenshots/order.png)

examples/forms with a variable number of fields/index.sql

@@ -0,0 +1,15 @@
+SELECT 'shell' AS component, 'Products' AS title;
+
+SELECT 'list' AS component, 'Products' AS title;
+SELECT 'Add a new product' AS title,
+    'red' AS color,
+    'new_product_form.sql' AS link,
+    TRUE AS active;
+SELECT 'Pass an order' AS title,
+    'blue' AS color,
+    'order_form.sql' AS link,
+    TRUE AS active;
+SELECT 
+    name AS title,
+    price || '€' AS description
+FROM products;

examples/forms with a variable number of fields/new_product_form.sql

@@ -0,0 +1,8 @@
+SELECT 'shell' AS component, 'New product' AS title;
+
+SELECT 'form' as component,
+    'New product' as title,
+    'Create product' as validate,
+    'new_product_insert.sql' as action;
+SELECT 'Name' as name;
+SELECT 'Price' as name, 'number' as type;

examples/forms with a variable number of fields/new_product_insert.sql

@@ -0,0 +1,6 @@
+INSERT INTO products (name, price)
+VALUES (:Name, :Price)
+RETURNING
+    'redirect' AS component,
+    'index.sql' AS link
+;

examples/forms with a variable number of fields/order_form.sql

@@ -0,0 +1,22 @@
+SELECT 'shell' AS component, 'Order' AS title;
+
+SELECT 'form' as component,
+    'Pass an order' as title,
+    'Order' as validate,
+    'order_insert.sql' as action;
+
+SELECT 'Name' as name, 'Your full name' AS placeholder;
+SELECT 'Email' as name, 'Your email address' AS placeholder;
+SELECT 'product_quantity[]' AS name,
+    'Quantity of "' || name || '"' AS label,
+    'Number of "' || name || '" you wish to order, for ' || price || ' € each.' AS description,
+    'number' AS type,
+    1 AS step,
+    0 as min,
+    0 as value
+FROM products
+ORDER BY id;
+
+-- We include the product ids in the form as hidden fields, so that we can use them for the insertion.
+SELECT 'product_id[]' AS name, '' AS label, 'hidden' AS type, id as value
+FROM products ORDER BY id;

examples/forms with a variable number of fields/order_insert.sql

@@ -0,0 +1,14 @@
+INSERT INTO orders(customer_name, customer_email) 
+VALUES (:Name, :Email);
+
+INSERT INTO order_items(order_id, quantity, product_id)
+SELECT
+    last_insert_rowid(), -- The id of the order we just inserted. Requires SQLPage v0.9.0 or later.
+    CAST(quantity.value AS INTEGER),
+    CAST(product.value AS INTEGER)
+FROM JSON_EACH(:product_quantity) quantity
+INNER JOIN JSON_EACH(:product_id) product USING (key)
+WHERE CAST(quantity.value AS INTEGER) > 0
+RETURNING
+    'orders.sql?id=' || order_id as link,
+    'redirect' as component;

examples/forms with a variable number of fields/orders.sql

@@ -0,0 +1,24 @@
+SELECT 'alert' as component,
+    'Thanks !' as title,
+    'analyze' as icon,
+    'teal' as color,
+    'Your order is being processed. You will head from us soon.' as description;
+SELECT 'index.sql' as link,
+    'Back to homepage' as title;
+
+SELECT 'list' AS component,
+    'Order summary' AS title;
+SELECT 
+    quantity || ' x ' || name AS title,
+    'Subtotal: ' || quantity || ' x ' || price || ' € = ' || (quantity * price) || ' €' AS description
+FROM order_items
+INNER JOIN products ON products.id = order_items.product_id
+WHERE order_id = $id;
+
+SELECT 
+    'Total: ' || SUM(quantity * price) || ' €' AS title,
+    'red' AS color,
+    TRUE AS active
+FROM order_items
+INNER JOIN products ON products.id = order_items.product_id
+WHERE order_id = $id;