Merge olivierauverlot/login: combine local defaults with error_message and improved docs

Author: lovasoa

examples/official-site/examples/authentication/create_session_token.sql

@@ -4,12 +4,12 @@ delete from user_sessions where created_at < datetime('now', '-1 day');
 -- check that the 
 SELECT 'authentication' AS component,
     'login.sql?failed' AS link, -- redirect to the login page on error
-    (SELECT password_hash FROM users WHERE username = :Username) AS password_hash, -- this is a hash of the password 'admin'
-    :Password AS password; -- this is the password that the user sent through our form in 'index.sql'
+    (SELECT password_hash FROM users WHERE username = :username) AS password_hash, -- this is a hash of the password 'admin'
+    :password AS password; -- this is the password that the user sent through our form in 'index.sql'
 
 -- if we haven't been redirected, then the password is correct
 -- create a new session
-insert into user_sessions (session_token, username) values (sqlpage.random_string(32), :Username)
+insert into user_sessions (session_token, username) values (sqlpage.random_string(32), :username)
 returning 'cookie' as component, 'session_token' as name, session_token as value;
 
 -- redirect to the authentication example home page

examples/official-site/examples/authentication/login.sql

@@ -1,18 +1,23 @@
 select 'dynamic' as component, properties FROM example WHERE component = 'shell' LIMIT 1;
 
-select 'form' as component, 'Authentication' as title, 'Log in' as validate, 'create_session_token.sql' as action;
-select 'Username' as name, 'user' as prefix_icon, 'admin' as placeholder;
-select 'Password' as name, 'lock' as prefix_icon, 'admin' as placeholder, 'password' as type;
-
-select 'alert' as component, 'danger' as color, 'Invalid username or password' as title where $failed is not null;
+select 
+    'login'                 as component,
+    'create_session_token.sql'             as action,
+    '/assets/icon.webp'   as image,
+    'Demo Login Form' as title,
+    'Username'              as username,
+    'Password'              as password,
+    case when $failed is not null then 'Invalid username or password. In this demo, you can log in with admin / admin.' end as error_message,
+    'In this demo, the username is "admin" and the password is "admin".' as footer_md,
+    'Sign in'               as validate;
 
 select 'text' as component, '
 
 # Authentication
 
 This is a simple example of an authentication form.
 It uses 
- - the [`form`](/documentation.sql?component=form#component) component to create a login form
+ - the [`login`](/documentation.sql?component=login#component) component to create a login form
  - the [`authentication`](/documentation.sql?component=authentication#component) component to check the user password
  - the [`cookie`](/documentation.sql?component=cookie#component) component to store a unique session token in the user browser
  - the [`redirect`](/documentation.sql?component=redirect#component) component to redirect the user to the login page if they are not logged in 

examples/official-site/sqlpage/migrations/68_login.sql

@@ -1,15 +1,13 @@
 INSERT INTO component(name, icon, description, introduced_in_version) VALUES
     ('login', 'password-user', '
 The login component is an authentication form with numerous customization options. 
-The user enters their username and password,
-and is then redirected to another page, where you can use the [authentication](?component=authentication) component
-to check the credentials.
-
+It offers the main functionalities for this type of form. 
+The user can enter their username and password. 
 There are many optional attributes such as the use of icons on input fields, the insertion of a link to a page to reset the password, an option for the application to maintain the user''s identity via a cookie. 
 It is also possible to set the title of the form, display the company logo, or customize the appearance of the form submission button.
 
-This component does not implement any logic. It simply collects the username and password to pass them to the code responsible for authentication.
-It should be used in conjunction with other components such as [authentication](component.sql?component=authentication) and [cookie](component.sql?component=cookie) to actually allow or deny access.
+This component should be used in conjunction with other components such as [authentication](component.sql?component=authentication) and [cookie](component.sql?component=cookie). 
+It does not implement any logic and simply collects the username and password to pass them to the code responsible for authentication.
 
 A few things to know :
 - The form uses the POST method to transmit information to the destination page,
@@ -22,6 +20,7 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S
     ('title','Title of the authentication form.','TEXT',TRUE,TRUE),
     ('enctype','Form data encoding.','TEXT',TRUE,TRUE),
     ('action','An optional link to a target page that will handle the results of the form. ','TEXT',TRUE,TRUE),
+    ('error_message','An error message to display above the form, typically shown after a failed login attempt.','TEXT',TRUE,TRUE),
     ('username','Label and placeholder for the user account identifier text field.','TEXT',TRUE,FALSE),
     ('password','Label and placeholder for the password field.','TEXT',TRUE,FALSE),
     ('username_icon','Icon to display on the left side of the input field, on the same line.','ICON',TRUE,TRUE),
@@ -43,57 +42,10 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S
 INSERT INTO example(component, description, properties)
 VALUES (
         'login',
-        'This example shows how to implement a complete custom login system in your SQLPage app.
-
-### Database schema
-
-`sqlpage/migrations/001_users.sql`
-
-```sql
-create table account (
-        username TEXT PRIMARY KEY,
-        password_hash TEXT NOT NULL
-);
-
-create table session (
-        id TEXT PRIMARY KEY,
-        username TEXT REFERENCES account(username)
-	-- you could add more fields for session expiration, session metadata tracking...
-);
-```
-
-### Process user credentials
-
-Create a file named `login.sql`:
-
-```sql
-SELECT ''authentication'' AS component,
-    ''/'' AS link, -- redirect the user to the homepage if the password is incorrect
-    (SELECT password_hash FROM account WHERE username = :username) AS password_hash,
-    :password AS password;
-
--- The code after this point is only executed if the user has sent the correct password
-
--- Generate a random session token
-INSERT INTO session (id, username)
-VALUES (sqlpage.random_string(32), :username)
-RETURNING ''cookie'' AS component, ''session_token'' AS name, id AS value,
-case when :remember is null then 3600*24*365 else 3600*4 end as max_age;
-
-select ''redirect'' as component, ''protected.sql'' as link; -- once logged in, redirect to the protected page
-```
-
-### Protect pages
-
-Start all protected pages with 
-
-```sql
-select ''redirect'' as component, ''/'' as link where not exists (select 1 from session where id=sqlpage.cookie(''session_token''));
-```
-
-### Login form on the home page
-',
-	JSON('[{
+        'Using the main options of the login component',
+        JSON(
+            '[
+                {
                     "component": "login",
                     "action": "login.sql",
                     "image": "../assets/icon.webp",
@@ -107,6 +59,8 @@ select ''redirect'' as component, ''/'' as link where not exists (select 1 from
                     "remember_me_text": "Remember me",
                     "footer_md": "Don''t have an account? [Register here](register.sql)",
                     "validate": "Sign in"
-	}]')
-),
+                }
+            ]'
+        )
+    ),
    ('login', 'Most basic login form', JSON('[{"component": "login"}]'));

sqlpage/templates/login.handlebars

@@ -13,13 +13,23 @@
                 {{/if}}
             >
                 {{#if image}}
-                    <div class="form-group d-flex justify-content-center align-items-center">
+                    <div class="form-group d-flex justify-content-center align-items-center mb-2">
                         <img src="{{image}}"/>
                     </div>
                 {{/if}}
                 {{#if title}}
                     <h1 class="text-center mb-3">{{title}}</h1>
                 {{/if}}
+                {{#if error_message}}
+                    <div class="alert alert-danger mb-3" role="alert">
+                        <div class="alert-icon">
+                            {{icon_img 'alert-circle'}}
+                        </div>
+                        <div class="overflow-auto w-100">
+                            {{error_message}}
+                        </div>
+                    </div>
+                {{/if}}
                 <label class="form-label">{{username}}</label>    
                 <div class="input-icon mb-3">
                     <span class="input-icon-addon">{{icon_img (default username_icon 'user-circle')}}</span>
@@ -31,7 +41,7 @@
                     {{/if}}
                 </label>
                 <div class="input-icon mb-3">
-		    <span class="input-icon-addon">{{~icon_img (default password_icon 'key')~}}</span>
+                    <span class="input-icon-addon">{{~icon_img (default password_icon 'key')~}}</span>
                     <input type="password" name="password" id="password" value="" class="form-control" placeholder="{{password}}" required="required" autocomplete="current-password" />
                 </div>
                 {{#if remember_me_text}}