Merge pull request #1753 from Platform-OS/user-module

Add User module tutorial

Author: simplykatsa

app/assets/images/get-started/user-management/basic-navigation.png

@@ -0,0 +1,99 @@
+---
+metadata:
+  title: Creating a User Account
+  description: Learn how to create a user account using the built-in registration flow of the platformOS User Module.
+converter: markdown
+---
+
+Now that the User Module is installed, the homepage is set up, and you are aware of the available endpoints, you can create your first account on your instance. The module provides the complete registration flow out of the box, so you do not need to build any forms or mutations at this stage. In this chapter, you will register a new user, explore how platformOS stores user credentials, and verify the newly created account using the `pos-cli GUI`.
+
+## Step 1: Open the Registration Page
+
+The User Module automatically exposes a **sign-up form** at the following URL:
+
+```
+/users/new
+```
+<br>
+
+Navigate to: `https://YOUR-INSTANCE.staging.oregon.platform-os.com/users/new`
+
+You should see a registration page. If Common Styling is configured correctly, the form will already appear clean and fully styled.
+
+## Step 2: Create an Account
+
+Fill in the form with:
+
+* a **valid email format** (does not have to be a real inbox), and
+* a **password** you will remember for upcoming steps.
+
+<img loading="lazy" src="{{ 'images/get-started/user-management/create-account.png' | asset_url }}" alt="Creating an account using the User Module">
+
+Submit the form.
+
+If the registration is successful:
+
+* a new account is created,
+* you have been redirected to the home page and you are automatically logged in,
+* but you **do not see any confirmation yet** because the layout has no navigation or user state indicators.
+
+We will add login/logout awareness later in the tutorial.
+
+{% include 'alert/tip', content: 'If you receive validation errors, correct the issues and try again. The User Module includes built-in validations for email format and password requirements.' %}
+
+## Step 3: Verify the User using the GUI
+
+To confirm that your account was created, use the admin GUI provided by `pos-cli`.
+
+Start the GUI:
+
+<pre class="command-line" data-user="user" data-host="host"><code class="language-bash">
+pos-cli gui serve staging
+</code></pre>
+
+This command starts a local admin interface at:
+
+```
+http://localhost:3333
+```
+
+Open it and select **Users** from the navigation. You should now see the user you just registered, along with the email address you provided.
+
+<img loading="lazy" src="{{ 'images/get-started/user-management/user-in-users.png' | asset_url }}" alt="Viewing the newly created user in the pos-cli GUI">
+
+## Step 4: Understand How User Credentials Are Stored
+
+platformOS does not store passwords in plain text. Instead, it uses **[Bcrypt](https://bcrypt-generator.com/)**, a one-way cryptographic hashing function. This ensures several security guarantees:
+
+* The original password **cannot** be recovered from the stored hash.
+* When a user logs in, the password they enter is **hashed again** using the same algorithm, and the hashes are compared.
+* If the hashes match, the user is authenticated — without the system ever knowing the real password.
+
+You can think of it like burning a piece of paper containing the password into ash. Once destroyed, the original password cannot be reconstructed.
+
+This hashing mechanism is built into the User Module. You do not need to configure anything manually.
+
+## Step 5: Users vs. Records in platformOS
+
+So far, you have worked mostly with **Records** (for example, in the Contact Us tutorial). A `record` is a flexible data object defined through your custom schema. A **User** is not a regular Record.
+
+### Why Users are separate from Records
+
+Users include several built-in fields and guarantees that Records do not provide:
+
+* **Email uniqueness**: The system ensures that no two users can register with the same email address.
+
+* **Secure password handling**: Passwords are never stored in plain text. Whatever value you submit in the `password` field is automatically hashed before being stored.
+
+This distinction is important. Users are not stored as regular Records because they include specialized fields, security considerations, and authentication behaviors.
+
+### Authentication features built into the User entity
+
+In addition to secure password storage, the User entity provides authentication features out of the box:
+
+* **Session-based authentication** using standard login/logout flows.
+* **Support for JWT (JSON Web Tokens)**, typically used by mobile or API-driven applications that require token-based authentication.
+
+{% include 'alert/tutorial', content: 'For a deeper understanding of how authentication works in platformOS, explore the <a href="/developer-guide/users/authentication" target="_blank">Authentication</a> guide. It covers password-based login, temporary tokens, JWT tokens, session management, and more.' %}
+
+{% render 'alert/next', content: 'Creating Navigation and Loading the Current Profile', url: '/get-started/user-management/create-navigation-current-profile' %}

app/assets/images/get-started/user-management/create-account.png

@@ -0,0 +1,194 @@
+---
+metadata:
+   title: Creating Navigation and Loading the Current Profile
+   description: Learn how to add navigation links and dynamically show Login and Logout options using the User Module.
+converter: markdown
+---
+
+A short recap: after installing the User Module, your instance automatically includes a full set of authentication pages such as Register, Log In, and Reset Password. These pages already work, but they are not linked from your application yet. To make them accessible for the users, you need to add navigation elements to your layout and adjust them so that they respond to the user’s login state.
+
+In this chapter, we will:
+
+* Add basic navigation links
+* Detect whether a user is logged in
+* Display Login or Logout accordingly
+* Display a simple greeting for authenticated users
+* Learn how the `current_profile` helper works and provides user information
+
+By the end of this chapter, your application will feel functional and interactive, reacting to whether the user is authenticated.
+
+## Step 1: Add Basic Navigation Links
+
+Open your main layout at: `app/views/layouts/application.liquid`
+
+Add a simple navigation block just above `{% raw %}{{ content_for_layout }}{% endraw %}`:
+
+#### app/views/layouts/application.liquid
+
+{% raw %}
+
+```liquid
+<nav>
+  <ul>
+    <li><a href="/">Home</a></li>
+    <li><a href="/sessions/new">Log in</a></li>
+  </ul>
+</nav>
+
+{{ content_for_layout }}
+```
+{% endraw %}
+
+This contains a Home and a Log in link. Save the your file and reload your instance. The navigation should appear at the top of the page:
+
+<img loading="lazy" src="{{ 'images/get-started/user-management/basic-navigation.png' | asset_url }}" alt="Basic navigation with Home and Login links">
+
+If you click *Log in*, nothing will change. Since you are already authenticated, the User Module redirects you back to the homepage. At this stage, the navigation is still static, so the links do not reflect the user’s actual state.
+
+In the next step, you will make the navigation dynamic so it displays the correct options for both guests and signed-in users.
+
+## Step 2: Loading the Current Profile in the Layout
+
+To conditionally show the correct navigation links, the layout needs access to the current user’s **profile**. The User Module provides a helper function designed specifically for this purpose. The following snippet comes from the **[Current Profile in Layouts](https://github.com/Platform-OS/pos-module-user?tab=readme-ov-file#current-profile-in-layouts)** section of the User Module documentation:
+
+{% raw %}
+
+```liquid
+{% liquid
+  if context.current_user
+    assign current_profile = context.exports.current_profile
+    unless current_profile
+      function current_profile = 'modules/user/helpers/current_profile'
+    endunless
+  endif
+%}
+```
+{% endraw %}
+
+Add this block above your navigation in `app/views/layouts/application.liquid`.
+
+### What this code does
+
+1. It checks whether `context.current_user` exists
+2. If it does, it loads the full user profile using the `current-profile` helper
+3. Makes it available as `current_profile` in your layout
+
+With this helper, you can show different navigation items depending on whether the user is authenticated.
+
+## Step 3: Using the `current_profile` helper
+
+Now that the authenticated user’s profile is available in the layout, you can update the navigation so that it responds to the login state.
+
+In this step, you will replace your existing `<nav>` block with a version that:
+
+* Shows a **Login** link when no user is logged in
+* Displays a **Welcome message with the user's email** and a **Logout** button when the user is authenticated
+
+### Update your navigation block
+
+Replace your earlier`<nav>` block with the following version, which displays different options for authenticated and unauthenticated users:
+
+#### app/views/layouts/application.liquid
+
+{% raw %}
+```liquid
+<nav>
+  <a href="/">Home</a>
+  <ul>
+    {% if current_profile %}
+      <li>Welcome, {{ current_profile.email }}</li>
+      <form method="post" action="/sessions">
+        <input type="hidden" name="authenticity_token" value="{{ context.authenticity_token }}">
+        <input type="hidden" name="_method" value="delete">
+        <button class="pos-button" type="submit">Logout</button>
+      </form>
+
+    {% else %}
+      <li><a href="/sessions/new">Login</a></li>
+    {% endif %}
+  </ul>
+</nav>
+```
+{% endraw %}
+
+### Full `application.liquid` Example
+
+Your entire layout file should now look similar to the following:
+
+#### app/views/layouts/application.liquid
+
+{% raw %}
+```liquid
+<!DOCTYPE html>
+<html class="pos-app">
+  <head>
+
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta content="authenticity_token" name="csrf-param">
+    <meta content="{{ form_authenticity_token }}" name="csrf-token">
+      {% comment %} default platformOS provided styles {% endcomment %}
+      {% render 'modules/common-styling/init' %}
+      <link rel="stylesheet" href="{{ 'modules/user/style/pos-user-form.css' | asset_url }}">
+      {% comment %} custom styles specific for this app, some overwrite the defaults {% endcomment %}
+      <link rel="stylesheet" href="{{ 'style/app.css' | asset_url }}">
+
+      <meta name="viewport" content="width=device-width,initial-scale=1,user-scalable=yes">
+
+      <script>
+        /* namespace */
+        if(typeof window.pos !== 'object'){
+          window.pos = {};
+          window.pos.modules = {};
+          window.pos.translations = {};
+        }
+      </script>
+
+    <title>Example User Management Application | platformOS</title>
+
+    <link rel="stylesheet" href="{{ 'styles/app.css' | asset_url }}">
+  </head>
+
+  <body>
+{% liquid
+ if context.current_user 
+   assign current_profile = context.exports.current_profile
+   unless current_profile
+     function current_profile = 'modules/user/helpers/current_profile'
+   endunless
+ endif
+%}
+<nav>
+  <a href="/">Home</a>
+  <ul>
+
+       {% if current_profile %}
+        <li>Welcome, {{ current_profile.email }}</li>
+        <form method="post" action="/sessions">
+          <input type="hidden" name="authenticity_token" value="{{ context.authenticity_token }}">
+          <input type="hidden" name="_method" value="delete">
+          <button class="pos-button" type="submit">Logout</button>
+        </form>
+      {% else %}
+        <li><a href="/sessions/new">Login</a></li>
+      {% endif %}
+    
+  </ul>
+</nav>
+
+    {{ content_for_layout }}
+
+{% liquid
+  render 'modules/common-styling/toasts'
+%}  
+
+    <script src="{{ 'scripts/app.js' | asset_url }}"></script>
+
+  </body>
+</html>
+ ```
+{% endraw %}
+
+Let's continue with testing the log in and log out flow.
+
+{% render 'alert/next', content: 'Testing the Login and Logout Flow', url: '/get-started/user-management/test-log-in-log-out' %}