Merge pull request #382 from devforth/next

Next

Author: ivictbor

adapters/install-adapters.sh

@@ -1,5 +1,10 @@
 #!/usr/bin/env bash
-ADAPTERS="adminforth-completion-adapter-open-ai-chat-gpt adminforth-email-adapter-aws-ses adminforth-email-adapter-mailgun adminforth-google-oauth-adapter adminforth-github-oauth-adapter adminforth-facebook-oauth-adapter adminforth-keycloak-oauth-adapter adminforth-microsoft-oauth-adapter adminforth-twitch-oauth-adapter adminforth-image-generation-adapter-openai adminforth-storage-adapter-amazon-s3 adminforth-storage-adapter-local adminforth-image-vision-adapter-openai"
+ADAPTERS="adminforth-completion-adapter-open-ai-chat-gpt adminforth-email-adapter-aws-ses \
+adminforth-email-adapter-mailgun adminforth-google-oauth-adapter adminforth-github-oauth-adapter \
+adminforth-facebook-oauth-adapter adminforth-keycloak-oauth-adapter adminforth-microsoft-oauth-adapter \ 
+adminforth-twitch-oauth-adapter adminforth-image-generation-adapter-openai adminforth-storage-adapter-amazon-s3 \ 
+adminforth-storage-adapter-local adminforth-image-vision-adapter-openai adminforth-key-value-adapter-ram \
+adminforth-login-captcha-adapter-cloudflare adminforth-login-captcha-adapter-recaptcha"
 
 # for each
 install_adapter() {

adminforth/auth.ts

@@ -107,6 +107,13 @@ class AdminForthAuth implements IAdminForthAuth {
       httpOnly ? ' HttpOnly;' : ''
     } SameSite=Strict; Expires=${new Date(Date.now() + expiry).toUTCString() } `);
   }
+
+  getCustomCookie({ cookies, name }: {
+    cookies: {key: string, value: string}[], name: string
+  }): string | null {
+    const brandSlug = this.adminforth.config.customization.brandNameSlug;
+    return cookies.find((cookie) => cookie.key === `adminforth_${brandSlug}_${name}`)?.value || null;
+  }
 
   issueJWT(payload: Object, type: string, expiresIn: string = '24h'): string {
     // read ADMINFORH_SECRET from environment if not drop error

adminforth/documentation/docs/tutorial/03-Customization/01-branding.md

@@ -126,6 +126,27 @@ const admin = new AdminForth({
 });
 ```
 
+## Icon only sidebar 
+
+AdminForth supports a collapsible sidebar that can be toggled between a full-width view (showing labels) and an icon-only view (showing only icons).
+
+```ts title='./index.ts'
+
+const admin = new AdminForth({
+  ...
+  customization: {
+  //diff-add
+    iconOnlySidebar: {
+  //diff-add
+      enabled: true,  // Optional: Enable the collapsible icon-only sidebar feature
+  //diff-add
+      logo: '@@/logo.svg',  // Optional: Custom logo to display in icon-only mode
+  //diff-add
+    }, 
+  },
+  ...
+});
+```
 
 ## Square vs rounded buttons?
 

adminforth/documentation/docs/tutorial/03-Customization/04-hooks.md

@@ -40,7 +40,7 @@ If multiple hooks are defined (e.g. plugin might add own hook to `list.beforeDat
 
 When user opens edit page, AdminForth makes a request to the backend to get the initial data for the form.
 
-![Initial data for edit page flow](initial_edit_data_flow.png)
+![Initial data for edit page flow](get_resource_data.png)
 
 Practically you can use `show.afterDatasourceResponse` to modify or add some data before it is displayed on the edit page. 
 

adminforth/documentation/docs/tutorial/03-Customization/06-customPages.md

@@ -441,7 +441,8 @@ new AdminForth({
           file: '@@/pages/TwoFactorsSetup.vue',
           meta: { 
             title: 'Setup 2FA',  // meta title for this page
-            customLayout: true  // don't include default layout like menu/header
+              //diff-add
+            sidebarAndHeader: 'none'  // Layout options: 'none' (no sidebar/header), 'default' (full layout), 'preferIconOnly' (collapsed sidebar)
           }
         }
       }
@@ -450,6 +451,11 @@ new AdminForth({
 })
 ```
 
+> 💡 **Layout Options Explained:**
+> - `'none'`: Renders the page without AdminForth's default sidebar and header layout - perfect for standalone pages like setup wizards, or public (logged-out) pages (Terms-of-Service/PP/Contact form etc)
+> - `'default'`: Uses the full AdminForth layout with sidebar and header - ideal for pages that should feel integrated with the admin panel
+> - `'preferIconOnly'`: Uses the default layout but starts with a collapsed sidebar (even if icon-only sidebar is disabled in your configuration) - great for pages that need more screen space or already have some navigation
+
 This will register custom page with path `/setup2fa` and will not include it in the menu. 
 
 You can navigate user to this page using any router link, e.g.:
@@ -466,13 +472,13 @@ Add to your `<script setup>` section:
 import { Link } from '@/afcl';
 ```
 
-If you set `customLayout: true` in the `meta` object, it will not include default layout like sidebar and header, so you can create your own layout for this page. 
+If you set `sidebarAndHeader: 'none'` in the `meta` object, it will not include default layout like sidebar and header, so you can create your own layout for this page. 
 
 ### Disable redirects to login page (Public pages)
 
 Any route which has sidebar and header (e.g. default CRUD pages or menu item with `component`) uses internal AdminForth REST API to fetch menu items and user information, so it passes authentication check and if authentication cookie is not provided or has expired JWT user gets redirected to the login page.
 
-In case if you set `customLayout: true`, it will not call these APIs so user will not be automatically redirected to the login page in case of expired or not-provided authentication cookie. That feature allows you to implement public pages without authentication, e.g. Terms of Service, Privacy Policy and many others. In case if you need to check if user is logged in just call any custom API which has `admin.express.authorize` middleware. Obviously for public pages if they use any APIs you should create API endpoint WITHOUT `admin.express.authorize` middleware.
+In case if you set `sidebarAndHeader: 'none'`, it will not call these APIs so user will not be automatically redirected to the login page in case of expired or not-provided authentication cookie. That feature allows you to implement public pages without authentication, e.g. Terms of Service, Privacy Policy and many others. In case if you need to check if user is logged in just call any custom API which has `admin.express.authorize` middleware. Obviously for public pages if they use any APIs you should create API endpoint WITHOUT `admin.express.authorize` middleware.
 
 > Please note that AdminForth uses classic SPA Vue app, so even public pages will be rendered by JavaScript in the browser and not on the server side. If your public page should be indexed by search engines, you should use some SSR framework like Nuxt.js to create such pages. At the same time public pages can still be usefull if you don't focus on old-fashioned search engines (modern search engines can index SPA pages as well) or if indexing is not important for such pages at all (e.g. Terms of Service, Privacy Policy, Contact Us and many others).
 
@@ -491,7 +497,7 @@ You can add custom meta attributes to the page by passing `meta` object to the p
           file: '@@/pages/TwoFactorsSetup.vue',
           meta: { 
             title: 'Setup 2FA',  // meta title for this page
-            customLayout: true,  // don't include default layout like menu/header
+            sidebarAndHeader: 'none',   // don't include default layout like menu/header
     //diff-add
             myAttribute: 'a1'
           }
@@ -508,4 +514,56 @@ import { useRoute } from 'vue-router';
 const route = useRoute();
 
 console.log(route.meta.myAttribute);  // a1
-```
+```
+
+## Settings View 
+
+If you want to add a Settings section to your project:
+
+```ts title='./index.ts' 
+export const admin = new AdminForth({
+  baseUrl : ADMIN_BASE_URL,
+  auth: {
+    //diff-add
+    userMenuSettingsPages: [
+      //diff-add
+      {
+        //diff-add
+        pageLabel: 'Profile settings',
+        //diff-add
+        component: '@@/ProfileSettings.vue',
+        //diff-add
+        // Specify a slug if you want a custom URL path.
+        //diff-add
+        // For example, without a slug, the URL will be:
+        //diff-add
+        //   example.com/settings/profile-settings
+        //diff-add
+        // With a custom slug, you could have:
+        //diff-add
+        //   example.com/settings/users-settings
+        //diff-add
+        slug: "users-settings",
+        //diff-add
+        icon:"flowbite:user-solid"
+        //diff-add
+      },
+      //diff-add
+      {
+        //diff-add
+        pageLabel: 'Security',
+        //diff-add
+        component: "@@/MySecrets.vue",
+        //diff-add
+        icon: "flowbite:lock-solid"
+        //diff-add
+      }
+      //diff-add
+    ],
+  }
+});
+```
+
+After this, you will have a custom Settings section in the users menu:
+
+![alt text](SettingsView-1.png)

adminforth/documentation/docs/tutorial/03-Customization/08-pageInjections.md

@@ -554,4 +554,24 @@ new AdminForth({
 })
 ```
 
-If you hide the logo with `showBrandLogoInSidebar: false`, components injected via `sidebarTop` will take the whole line width.
+If you hide the logo with `showBrandLogoInSidebar: false`, components injected via `sidebarTop` will take the whole line width.
+
+## Custom scripts in head
+
+If you want to inject tags in your html head:
+
+```ts title='./index.ts'
+
+customization: {
+  ...
+  customHeadItems: [
+    {
+      tagName: 'script',
+      attributes: { async: 'true', defer: 'true' },
+      innerCode: "console.log('Hello from HTML head')"
+    }
+  ],
+...
+}
+
+```

adminforth/documentation/docs/tutorial/03-Customization/15-afcl.md

@@ -41,6 +41,68 @@ import { Button } from '@/afcl'
 
 loader prop would show loader when it's true.
 
+## Button Group
+### With active button
+<div class="split-screen" >
+
+```ts
+import { IconGridSolid, IconUserCircleSolid } from '@iconify-prerendered/vue-flowbite';
+import { ButtonGroup } from '@/afcl'
+
+const activeButton = ref('')
+
+    ...
+
+<ButtonGroup v-model="activeButton">  
+  <template #button:Profile>
+    <div class="flex px-4 py-2">
+      <IconUserCircleSolid class="w-5 h-5 me-2"/>
+      Profile
+    </div>
+  </template>
+  <template #button:Dashboard>
+    <div class="flex px-4 py-2">
+      <IconGridSolid class="w-5 h-5 me-2"/>
+      Board
+    </div>
+  </template>
+</ButtonGroup>
+```
+
+![AFCL Button-group](ButtonGroup1.png)
+
+</div>
+
+### With solid color
+
+<div class="split-screen" >
+
+```ts
+  import { ButtonGroup } from '@/afcl'
+  import { IconPlusOutline, IconCaretDownSolid } from '@iconify-prerendered/vue-flowbite';
+
+    ...
+
+    <ButtonGroup :solidColor="true">
+        <template #button:Profile>
+            <div class="flex px-4 py-2" @click="console.log("Add passkey got clicked")">
+                <IconPlusOutline class="w-5 h-5 me-2"/>
+                <p>Add Local Passkey</p>
+            </div>
+        </template>
+        <template #button:Dropdown>
+            <div id="dropdown-button" class="flex px-2 py-2" @click="console.log("Dropdown got clicked")">
+                <IconCaretDownSolid class="w-5 h-5"/>
+            </div>
+        </template>
+    </ButtonGroup>
+
+```
+
+![AFCL Button-group](ButtonGroup2.png)
+
+</div>
+
 
 ## Link
 
@@ -362,6 +424,54 @@ const enable = ref(false)
   </div>
 </div>
 
+## Card 
+
+### Custom card
+If you need custom card, you can make it without 
+<div class="split-screen">
+```ts
+<Card>
+  <p class="font-semibold text-gray-600 text-xl dark:text-gray-300">Total Profit</p>
+  <p class="text-green-500 font-bold mt-2">$100,000</p>
+</Card>
+```
+
+
+![AFCL Checkbox](Card3.png)
+
+</div>
+
+### Standart card
+<div class="split-screen">
+
+```ts
+import { Card } from '@/afcl'
+
+  ...
+
+  <Card
+    title="This is a large card"
+    description="Description text for large card. This is a large card. Very nice card. Big one. You can put here any content you want."
+  >
+  </Card>
+
+  <Card
+    size="md"
+    title="This is a medium card"
+    description="Description text for medium card. This is a medium card. Very nice card. Big one. You can put here any content you want."
+  >
+  </Card>
+
+  <Card
+    size="sm"
+    title="This is a small card"
+    description="Description text for small card. This is a small card. Very nice card. Big one. You can put here any content you want."
+  >
+  </Card>
+```
+![AFCL Checkbox](Card2.png)
+
+</div>
 
 ## Toggle
 
@@ -858,10 +968,49 @@ async function loadPageData(data) {
 //diff-add
   :data="loadPageData"
 
-  :pageSize="3"> </Table>
+  :pageSize="3"> 
+</Table>
 ```
 > 👆 The page size is used as the limit for pagination.
 
+### Table loading states
+
+For tables where you load data externally and pass them to `data` prop as array (including case with front-end pagination) you might want to show skeleton loaders in table externaly using `isLoading` props.
+
+For tables with server-side paganation which use async function in data prop you can listen for `@update:tableLoading` to get table internal loading state, in other words this event will let you know when server side function started and finished execution, so you might use it e.g. to disable some external filter buttons and so on.
+
+<div class="split-screen">
+
+```ts
+import { Table, Button } from "@/afcl"
+const isTableLoading = ref(false);
+const tableState = ref("loading");
+
+  ...
+
+  <Table
+    :columns="[
+      { label: 'Name', fieldName: 'name' },
+      { label: 'Age', fieldName: 'age' },
+      { label: 'Country', fieldName: 'country' },
+    ]"
+    :data="loadPageData" 
+    //diff-add
+    :isLoading="isTableLoading"
+    :pageSize="3"
+    //diff-add
+    @update:tableLoading="(loading) => loading === true ? tableState = 'loading' : tableState = 'loaded'"
+  >
+  </Table>
+
+  <p> Table state: {{ tableState }} </p>
+
+  <Button @click="isTableLoading.value=!isTableLoading.value"> Toggle loading state</Button>
+```
+  ![AFCL Table](TableLoading.png)
+
+</div>
+
 ## ProgressBar
 
 <div class="split-screen" >