Skip to content

Commit 0d0bd84

Browse files
lovasoalovasoa
committed
better form documentation
1 parent 3bd58ba commit 0d0bd84

File tree

2 files changed

+101
-25
lines changed

2 files changed

+101
-25
lines changed

‎examples/official-site/examples/form.sql‎

Lines changed: 92 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,92 @@
1-
select
2-
'form' as component,
3-
'Save' as validate;
4-
select
5-
'username' as name;
6-
select
7-
'password' as name,
8-
'password' as type;
1+
select 'shell' as component, 'dark' as theme, '[View source on Github](https://github.com/sqlpage/SQLPage/blob/main/examples/official-site/examples/form.sql)' as footer;
2+
3+
SELECT 'form' AS component, 'Complete Input Types Reference' AS title, '/examples/show_variables.sql' as action;
4+
5+
SELECT 'header' AS type, 'Text Input Types' AS label;
6+
7+
SELECT 'username' AS name, 'text' AS type, 'Enter your username' AS placeholder,
8+
'**Text** - Default single-line text input. Use for short text like names, usernames, titles. Supports `minlength`, `maxlength`, `pattern` for validation.' AS description_md;
9+
10+
SELECT 'password' AS name, 'password' AS type, '^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]{8,}$' AS pattern,
11+
'**Password** - Masked text input that hides characters. Use for passwords and sensitive data. Combine with `pattern` attribute for password strength requirements.' AS description_md;
12+
13+
SELECT 'search_query' AS name, 'search' AS type, 'Search...' AS placeholder,
14+
'**Search** - Search input field, may display a clear button. Use for search boxes. Mobile browsers may show optimized keyboard.' AS description_md;
15+
16+
SELECT 'bio' AS name, 'textarea' AS type, 5 AS rows, 'Tell us about yourself...' AS placeholder,
17+
'**Textarea** (SQLPage custom) - Multi-line text input. Use for long text like comments, descriptions, articles. Set `rows` to control initial height.' AS description_md;
18+
19+
SELECT 'header' AS type, 'Numeric Input Types' AS label;
20+
21+
SELECT 'age' AS name, 'number' AS type, 0 AS min, 120 AS max, 1 AS step,
22+
'**Number** - Numeric input with up/down arrows. Use for quantities, ages, counts. Supports `min`, `max`, `step`. Mobile shows numeric keyboard.' AS description_md;
23+
24+
SELECT 'price' AS name, 'number' AS type, 0.01 AS step, '$' AS prefix,
25+
'**Number with decimals** - Set `step="0.01"` for currency. Use `prefix`/`suffix` for units. Great for prices, measurements, percentages.' AS description_md;
26+
27+
SELECT 'volume' AS name, 'range' AS type, 0 AS min, 100 AS max, 50 AS value, 1 AS step,
28+
'**Range** - Slider control for selecting a value. Use for volume, brightness, ratings, or any bounded numeric value where precision isn''t critical.' AS description_md;
29+
30+
SELECT 'header' AS type, 'Date and Time Types' AS label;
31+
32+
SELECT 'birth_date' AS name, 'date' AS type,
33+
'**Date** - Date picker (year, month, day). Use for birthdays, deadlines, event dates. Most browsers show a calendar widget. Supports `min` and `max` for date ranges.' AS description_md;
34+
35+
SELECT 'appointment_time' AS name, 'time' AS type,
36+
'**Time** - Time picker (hours and minutes). Use for appointment times, opening hours, alarms. Shows time selector in supported browsers.' AS description_md;
37+
38+
SELECT 'meeting_datetime' AS name, 'datetime-local' AS type,
39+
'**Datetime-local** - Date and time picker without timezone. Use for scheduling events, booking appointments, logging timestamps in local time.' AS description_md;
40+
41+
SELECT 'birth_month' AS name, 'month' AS type,
42+
'**Month** - Month and year picker. Use for credit card expiration dates, monthly reports, subscription periods.' AS description_md;
43+
44+
SELECT 'vacation_week' AS name, 'week' AS type,
45+
'**Week** - Week and year picker. Use for week-based scheduling, timesheet entry, weekly reports.' AS description_md;
46+
47+
SELECT 'header' AS type, 'Contact Information Types' AS label;
48+
49+
SELECT 'user_email' AS name, 'email' AS type, '[email protected]' AS placeholder,
50+
'**Email** - Email address input with built-in validation. Use for email fields. Browser validates format automatically. Mobile shows @ key on keyboard.' AS description_md;
51+
52+
SELECT 'phone' AS name, 'tel' AS type, '+1 (555) 123-4567' AS placeholder,
53+
'**Tel** - Telephone number input. Use for phone numbers. Mobile browsers show numeric keyboard with phone symbols. No automatic validation - use `pattern` if needed.' AS description_md;
54+
55+
SELECT 'website' AS name, 'url' AS type, 'https://example.com' AS placeholder,
56+
'**URL** - URL input with validation. Use for website addresses, links. Browser validates URL format. Mobile may show .com key on keyboard.' AS description_md;
57+
58+
SELECT 'header' AS type, 'Selection Types' AS label;
59+
60+
SELECT 'country' AS name, 'select' AS type,
61+
'[{"label": "United States", "value": "US"}, {"label": "Canada", "value": "CA"}, {"label": "United Kingdom", "value": "GB"}]' AS options,
62+
'**Select** (SQLPage custom) - Dropdown menu. Use for single choice from many options. Add `multiple` for multi-select. Use `searchable` for long lists. Set `dropdown` for enhanced UI.' AS description_md;
63+
64+
SELECT 'gender' AS name, 'radio' AS type, 'Male' AS value, 'Male' AS label,
65+
'**Radio** - Radio button for mutually exclusive choices. Create multiple rows with same `name` for a radio group. One option can be selected. Use for 2-5 options.' AS description_md;
66+
67+
SELECT 'gender' AS name, 'radio' AS type, 'Female' AS value, 'Female' AS label;
68+
69+
SELECT 'gender' AS name, 'radio' AS type, 'Other' AS value, 'Other' AS label;
70+
71+
SELECT 'interests' AS name, 'checkbox' AS type, 'Technology' AS value, 'Technology' AS label,
72+
'**Checkbox** - Checkbox for multiple selections. Each checkbox is independent. Use for yes/no questions or multiple selections from a list.' AS description_md;
73+
74+
SELECT 'terms' AS name, 'checkbox' AS type, TRUE AS required, 'I accept the terms and conditions' AS label,
75+
'**Checkbox (required)** - Use `required` to make acceptance mandatory. Common for terms of service, privacy policies, consent forms.' AS description_md;
76+
77+
SELECT 'notifications' AS name, 'switch' AS type, 'Enable email notifications' AS label, TRUE AS checked,
78+
'**Switch** (SQLPage custom) - Toggle switch, styled checkbox alternative. Use for on/off settings, feature toggles, preferences. More intuitive than checkboxes for boolean settings.' AS description_md;
79+
80+
SELECT 'header' AS type, 'File and Media Types' AS label;
81+
82+
SELECT 'profile_picture' AS name, 'file' AS type, 'image/*' AS accept,
83+
'**File** - File upload control. Use `accept` to limit file types (image/\*, .pdf, .doc). Use `multiple` to allow multiple files. Automatically sets form enctype to multipart/form-data.' AS description_md;
84+
85+
SELECT 'documents[]' AS name, 'Documents' as label, 'file' AS type, '.pdf,.doc,.docx' AS accept, TRUE AS multiple,
86+
'**File (multiple)** - Allow multiple file uploads with `multiple` attribute. Specify exact extensions or MIME types in `accept`.' AS description_md;
87+
88+
SELECT 'favorite_color' AS name, 'color' AS type, '#3b82f6' AS value,
89+
'**Color** - Color picker. Use for theme customization, design settings, highlighting preferences. Returns hex color code (#RRGGBB).' AS description_md;
90+
91+
SELECT 'user_id' AS name, 'hidden' AS type, '12345' AS value,
92+
'**Hidden** - Hidden input, not visible to users. Use for IDs, tokens, state information that needs to be submitted but not displayed or edited.' AS description_md;

‎examples/official-site/sqlpage/migrations/01_documentation.sql‎

Lines changed: 9 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -220,32 +220,24 @@ INSERT INTO component(name, icon, description) VALUES
220220
('form', 'cursor-text', '
221221
# Building forms in SQL
222222
223-
So, you have an SQL database, and would like to let users input data into it?
224-
The `form` component is what you are looking for.
225-
226-
## Collecting data from users to your database
227-
228223
The form component will display a series of input fields of various types, that can be filled in by the user.
229224
When the user submits the form, the data is posted to an SQL file specified in the `action` property.
230225
231226
## Handle Data with SQL
232227
233-
User-entered data is posted to an SQL file, that will handle the data,
234-
and will be able to insert it into the database, search for it, format it, etc.
228+
The receiving SQL page will be able to handle the data,
229+
and insert it into the database, use it to perform a search, format it, update existing data, etc.
235230
236-
For example, a value in a field named "x"
237-
can be referenced as `:x` in the SQL query of the target page.
231+
A value in a field named "x" will be available as `:x` in the SQL query of the target page.
238232
239233
## Examples
240234
241-
- **Data Entry Automation**: Forms for tasks like inventory management.
242-
- **Custom Report Builder**: Generate reports based on user-specified criteria.
243-
- **Database Management**: Update records or query data.
244-
- **Admin Panel**: Manage user roles and permissions.
245-
- **Data Analytics with SQL**: Collect data for analytics.
246-
- **SQL Query Parametrization**: Build and execute complex SQL queries that depend on user input.
247-
- **SQL CRUD Operations**: Perform Create, Read, Update, and Delete operations.
248-
- **Web SQL**: Integrate forms into web applications.
235+
- [A multi-step form](https://github.com/sqlpage/SQLPage/tree/main/examples/forms-with-multiple-steps), guiding the user through a process without overwhelming them with a large form.
236+
- [File upload form](https://github.com/sqlpage/SQLPage/tree/main/examples/image%20gallery%20with%20user%20uploads), letting users upload images to a gallery.
237+
- [Rich text editor](https://github.com/sqlpage/SQLPage/tree/main/examples/rich-text-editor), letting users write text with bold, italics, links, images, etc.
238+
- [Master-detail form](https://github.com/sqlpage/SQLPage/tree/main/examples/master-detail-forms), to edit a list of structured items.
239+
- [Form with a variable number of fields](https://github.com/sqlpage/SQLPage/tree/main/examples/forms%20with%20a%20variable%20number%20of%20fields), when the fields are not known in advance.
240+
- [Demo of all input types](/examples/form), showing all the input types supported by SQLPage.
249241
');
250242
INSERT INTO parameter(component, name, description_md, type, top_level, optional) SELECT 'form', * FROM (VALUES
251243
-- top level

0 commit comments

Comments
 (0)