Improve login component documentation and usability

lovasoa · lovasoa · commit cc95ae25dee3 · 2025-10-27T23:13:38.000+01:00
Add complete example with database schema, credential processing, and page protection. Update authentication migration to reference new login component. Enhance login template with default icons and autocomplete attributes. Make validate parameter optional with sensible default.
diff --git a/examples/official-site/sqlpage/migrations/07_authentication.sql b/examples/official-site/sqlpage/migrations/07_authentication.sql
@@ -14,7 +14,7 @@ you have two main options:
    - does not require any external service
    - gives you fine-grained control over 
      - which pages and actions are protected
-     - the look of the login form
+     - the look of the [login form](?component=login)
      - the duration of the session
      - the permissions of each user
 2. [**Single sign-on**](/sso)
@@ -128,12 +128,10 @@ Then, in all the pages that require authentication, you check if the cookie is p
 
 You can check if the user has sent the correct password in a form, and if not, redirect them to a login page.
 
-Create a login form in a file called `login.sql`:
+Create a login form in a file called `login.sql` that uses the [login component](?component=login):
 
 ```sql
-select ''form'' as component, ''Authentication'' as title, ''Log in'' as validate, ''create_session_token.sql'' as action;
-select ''Username'' as name, ''admin'' as placeholder;
-select ''Password'' as name, ''admin'' as placeholder, ''password'' as type;
+select ''login'' as component;
 ```
 
 And then, in `create_session_token.sql` :
diff --git a/examples/official-site/sqlpage/migrations/68_login.sql b/examples/official-site/sqlpage/migrations/68_login.sql
@@ -1,13 +1,15 @@
 INSERT INTO component(name, icon, description, introduced_in_version) VALUES
     ('login', 'password-user', '
 The login component is an authentication form with numerous customization options. 
-It offers the main functionalities for this type of form. 
-The user can enter their username and password. 
+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.
+
 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 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.
+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.
 
 A few things to know :
 - The form uses the POST method to transmit information to the destination page,
@@ -20,8 +22,8 @@ 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),
-    ('username','User account identifier.','TEXT',TRUE,FALSE),
-    ('password','User password.','TEXT',TRUE,FALSE),
+    ('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),
     ('password_icon','Icon to display on the left side of the input field, on the same line.','ICON',TRUE,TRUE),
     ('image','The URL of an centered image displayed before the title.','URL',TRUE,TRUE),
@@ -30,7 +32,7 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S
     ('remember_me_text','A text for the option allowing the user to request the preservation of their identity. If the text is empty, the option is not displayed.','TEXT',TRUE,TRUE),
     ('footer','A text placed at the bottom of the authentication form.','TEXT',TRUE,TRUE),
     ('footer_md','A markdown text placed at the bottom of the authentication form. Useful for creating links to other pages (creating a new account, contacting technical support, etc.).','TEXT',TRUE,TRUE),
-    ('validate','The text to display in the button at the bottom of the form that submits the values.','TEXT',TRUE,FALSE),
+    ('validate','The text to display in the button at the bottom of the form that submits the values.','TEXT',TRUE,TRUE),
     ('validate_color','The color of the button at the bottom of the form that submits the values. Omit this property to use the default color.','COLOR',TRUE,TRUE),
     ('validate_shape','The shape of the validation button.','TEXT',TRUE,TRUE),
     ('validate_outline','A color to outline the validation button.','COLOR',TRUE,TRUE),
@@ -41,10 +43,57 @@ INSERT INTO parameter(component, name, description, type, top_level, optional) S
 INSERT INTO example(component, description, properties)
 VALUES (
         'login',
-        'Using the main options of the login component',
-        JSON(
-            '[
-                {
+        '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('[{
                     "component": "login",
                     "action": "login.sql",
                     "image": "../assets/icon.webp",
@@ -58,7 +107,6 @@ VALUES (
                     "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"}]'));
diff --git a/sqlpage/templates/login.handlebars b/sqlpage/templates/login.handlebars
@@ -22,21 +22,17 @@
                 {{/if}}
                 <label class="form-label">{{username}}</label>    
                 <div class="input-icon mb-3">
-                    {{#if username_icon}}
-                        <span class="input-icon-addon">{{icon_img username_icon}}</span>
-                    {{/if}}
-                    <input type="text" name="username" id="username" value="" class="form-control" placeholder="{{username}}" required="required" autofocus/>
+                    <span class="input-icon-addon">{{icon_img (default username_icon 'user-circle')}}</span>
+                    <input type="text" name="username" id="username" value="" class="form-control" placeholder="{{username}}" required="required" autofocus autocomplete="username"/>
                 </div>
                 <label class="form-label">{{password}}
                     {{#if forgot_password_text}}
                         <span class="form-label-description"><a href="{{forgot_password_link}}">{{forgot_password_text}}</a></span> 
                     {{/if}}
                 </label>
                 <div class="input-icon mb-3">
-                    {{#if password_icon}}
-                        <span class="input-icon-addon">{{~icon_img password_icon~}}</span>
-                    {{/if}}
-                    <input type="password" name="password" id="password" value="" class="form-control" placeholder="{{password}}" required="required"/>
+		    <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}}
                     <label class="form-check">
@@ -53,7 +49,7 @@
                         {{#if validate_size}} btn-{{validate_size}} {{/if}}"
                         type="submit" 
                         name="submit"
-                        value="{{validate}}"/>
+                        value="{{default validate 'Login'}}"/>
                 </div>
                 {{#if (or footer footer_md)}}
                     <hr>
