419 Group forms in the sidebar (#426)

* group forms in the sidebar

* create `SidebarGroup` component

* return form description in endpoint

* fix ts linter error

---------

Co-authored-by: Daniel Townsend <dan@dantownsend.co.uk>

Author: sinisaos

admin_ui/src/components/FormNav.vue

@@ -1,35 +1,97 @@
 <template>
-    <ul>
-        <li v-bind:key="formConfig.name" v-for="formConfig in formConfigs">
-            <router-link
-                :to="{ name: 'addForm', params: { formSlug: formConfig.slug } }"
-                class="subtle"
-            >
-                <font-awesome-icon icon="level-up-alt" class="rotated90" />
-                <span>{{ readable(formConfig.name) }}</span>
-            </router-link>
-        </li>
-    </ul>
+    <div>
+        <ul class="table_list">
+            <li v-for="form in formGroups.ungrouped" v-bind:key="form">
+                <router-link
+                    :to="{ name: 'addForm', params: { formSlug: form.slug } }"
+                    :title="form.description"
+                    class="subtle"
+                    ><font-awesome-icon icon="level-up-alt" class="rotated90" />
+                    <span>{{ form.name }}</span></router-link
+                >
+            </li>
+
+            <template v-for="(formNames, groupName) in formGroups.grouped">
+                <SidebarGroup
+                    :name="String(groupName)"
+                    :collapsed="hiddenGroups.indexOf(String(groupName)) != -1"
+                    @toggled="toggleGroup(String(groupName))"
+                />
+
+                <template v-if="hiddenGroups.indexOf(String(groupName)) == -1">
+                    <li v-for="form in formNames" v-bind:key="form">
+                        <router-link
+                            :to="{
+                                name: 'addForm',
+                                params: { formSlug: form.slug }
+                            }"
+                            :title="form.description"
+                            class="subtle"
+                            ><font-awesome-icon
+                                icon="level-up-alt"
+                                class="rotated90"
+                            />
+                            <span>{{ form.name }}</span></router-link
+                        >
+                    </li>
+                </template>
+            </template>
+        </ul>
+    </div>
 </template>
 
 <script lang="ts">
 import { defineComponent } from "vue"
-
-import { readable } from "@/utils"
+import SidebarGroup from "./SidebarGroup.vue"
 
 export default defineComponent({
+    components: { SidebarGroup },
+    data() {
+        return {
+            hiddenGroups: [] as string[]
+        }
+    },
     computed: {
-        formConfigs() {
-            return this.$store.state.formConfigs
+        formGroups() {
+            return this.$store.state.formGroups
         }
     },
-    setup() {
-        return {
-            readable
+    methods: {
+        toggleGroup(groupName: string) {
+            const hiddenGroups: string[] = this.hiddenGroups
+            const index = hiddenGroups.indexOf(groupName)
+            if (index == -1) {
+                hiddenGroups.push(groupName)
+            } else {
+                hiddenGroups.splice(index, 1)
+            }
+            this.hiddenGroups = hiddenGroups
         }
     },
     async mounted() {
         await this.$store.dispatch("fetchFormConfigs")
+        await this.$store.dispatch("fetchFormGroups")
     }
 })
 </script>
+
+<style scoped lang="less">
+li.group {
+    font-size: 0.7em;
+
+    a {
+        text-transform: uppercase;
+
+        span {
+            &.name {
+                padding-left: 0;
+            }
+
+            &.ellipsis {
+                flex-grow: 1;
+                text-align: right;
+            }
+        }
+    }
+}
+</style>

admin_ui/src/components/SidebarGroup.vue

@@ -0,0 +1,52 @@
+<template>
+    <li class="group">
+        <a
+            href="#"
+            class="subtle"
+            @click.prevent="$emit('toggled')"
+            title="Click to toggle children."
+        >
+            <font-awesome-icon icon="layer-group" />
+            <span class="name">{{ name }}</span>
+            <span class="ellipsis" v-if="collapsed">...</span>
+        </a>
+    </li>
+</template>
+
+<script setup lang="ts">
+import type { PropType } from "vue"
+
+defineProps({
+    name: {
+        type: String as PropType<string>,
+        required: true
+    },
+    collapsed: {
+        type: Boolean as PropType<boolean>,
+        required: true
+    }
+})
+
+defineEmits(["toggled"])
+</script>
+
+<style scoped lang="less">
+li.group {
+    font-size: 0.7em;
+
+    a {
+        text-transform: uppercase;
+
+        span {
+            &.name {
+                padding-left: 0;
+            }
+
+            &.ellipsis {
+                flex-grow: 1;
+                text-align: right;
+            }
+        }
+    }
+}
+</style>

admin_ui/src/components/TableNav.vue

@@ -8,22 +8,11 @@
             />
 
             <template v-for="(tableNames, groupName) in tableGroups.grouped">
-                <li class="group">
-                    <a
-                        href="#"
-                        class="subtle"
-                        @click.prevent="toggleGroup(String(groupName))"
-                        title="Click to toggle children."
-                    >
-                        <font-awesome-icon icon="layer-group" />
-                        <span class="name">{{ groupName }}</span>
-                        <span
-                            class="ellipsis"
-                            v-if="hiddenGroups.indexOf(String(groupName)) != -1"
-                            >...</span
-                        >
-                    </a>
-                </li>
+                <SidebarGroup
+                    :collapsed="hiddenGroups.indexOf(String(groupName)) != -1"
+                    :name="String(groupName)"
+                    @toggled="toggleGroup(String(groupName))"
+                />
 
                 <template v-if="hiddenGroups.indexOf(String(groupName)) == -1">
                     <TableNavItem
@@ -39,10 +28,12 @@
 
 <script lang="ts">
 import { defineComponent } from "vue"
+import SidebarGroup from "./SidebarGroup.vue"
 import TableNavItem from "./TableNavItem.vue"
 
 export default defineComponent({
     components: {
+        SidebarGroup,
         TableNavItem
     },
     data() {
@@ -75,24 +66,3 @@ export default defineComponent({
     }
 })
 </script>
-
-<style scoped lang="less">
-li.group {
-    font-size: 0.7em;
-
-    a {
-        text-transform: uppercase;
-
-        span {
-            &.name {
-                padding-left: 0;
-            }
-
-            &.ellipsis {
-                flex-grow: 1;
-                text-align: right;
-            }
-        }
-    }
-}
-</style>

admin_ui/src/store.ts

@@ -33,6 +33,7 @@ export default createStore({
         tableNames: [],
         tableGroups: {},
         formConfigs: [] as i.FormConfig[],
+        formGroups: {},
         user: undefined,
         loadingStatus: false,
         customLinks: {}
@@ -47,6 +48,9 @@ export default createStore({
         updateFormConfigs(state, value) {
             state.formConfigs = value
         },
+        updateFormGroups(state, value) {
+            state.formGroups = value
+        },
         updateCurrentTablename(state, value) {
             state.currentTableName = value
         },
@@ -105,6 +109,10 @@ export default createStore({
             const response = await axios.get(`${BASE_URL}forms/`)
             context.commit("updateFormConfigs", response.data)
         },
+        async fetchFormGroups(context) {
+            const response = await axios.get(`${BASE_URL}forms/grouped/`)
+            context.commit("updateFormGroups", response.data)
+        },
         async fetchFormConfig(context, formSlug: string) {
             const response = await axios.get(`${BASE_URL}forms/${formSlug}/`)
             return response

docs/source/custom_forms/examples/app.py

@@ -25,6 +25,7 @@ def calculator(request: Request, data: CalculatorModel):
     pydantic_model=CalculatorModel,
     endpoint=calculator,
     description=("Adds two numbers together."),
+    form_group="Text forms",
 )
 
 

piccolo_admin/endpoints.py

@@ -94,11 +94,23 @@ class GenerateFileURLResponseModel(BaseModel):
     file_url: str = Field(description="A URL which the file is accessible on.")
 
 
+class GroupItem(BaseModel):
+    name: str
+    slug: str
+
+
 class GroupedTableNamesResponseModel(BaseModel):
     grouped: t.Dict[str, t.List[str]] = Field(default_factory=list)
     ungrouped: t.List[str] = Field(default_factory=list)
 
 
+class GroupedFormsResponseModel(BaseModel):
+    grouped: t.Dict[str, t.List[FormConfigResponseModel]] = Field(
+        default_factory=list
+    )
+    ungrouped: t.List[FormConfigResponseModel] = Field(default_factory=list)
+
+
 @dataclass
 class TableConfig:
     """
@@ -340,6 +352,10 @@ class FormConfig:
     :param description:
         An optional description which is shown in the UI to explain to the user
         what the form is for.
+    :param form_group:
+        If specified, forms can be divided into groups in the form
+        menu. This is useful when you have many forms that you
+        can organize into groups for better visibility.
 
     Here's a full example:
 
@@ -364,7 +380,8 @@ def my_endpoint(request: Request, data: MyModel):
         config = FormConfig(
             name="My Form",
             pydantic_model=MyModel,
-            endpoint=my_endpoint
+            endpoint=my_endpoint,
+            form_group="Text forms",
         )
 
     """
@@ -378,11 +395,13 @@ def __init__(
             t.Union[FormResponse, t.Coroutine[None, None, FormResponse]],
         ],
         description: t.Optional[str] = None,
+        form_group: t.Optional[str] = None,
     ):
         self.name = name
         self.pydantic_model = pydantic_model
         self.endpoint = endpoint
         self.description = description
+        self.form_group = form_group
         self.slug = self.name.replace(" ", "-").lower()
 
 
@@ -622,6 +641,14 @@ def __init__(
             response_model=t.List[FormConfigResponseModel],
         )
 
+        private_app.add_api_route(
+            path="/forms/grouped/",
+            endpoint=self.get_grouped_forms,  # type: ignore
+            methods=["GET"],
+            response_model=GroupedFormsResponseModel,
+            tags=["Forms"],
+        )
+
         private_app.add_api_route(
             path="/forms/{form_slug:str}/",
             endpoint=self.get_single_form,  # type: ignore
@@ -937,6 +964,34 @@ def get_forms(self) -> t.List[FormConfigResponseModel]:
             for form in self.forms
         ]
 
+    def get_grouped_forms(self) -> GroupedFormsResponseModel:
+        """
+        Returns a list of custom forms registered with the admin, grouped using
+        `form_group`.
+        """
+        response = GroupedFormsResponseModel()
+        group_names = sorted(
+            {
+                v.form_group
+                for _, v in self.form_config_map.items()
+                if v.form_group
+            }
+        )
+        response.grouped = {i: [] for i in group_names}
+        for _, form_config in self.form_config_map.items():
+            form_group = form_config.form_group
+            form_config_response = FormConfigResponseModel(
+                name=form_config.name,
+                slug=form_config.slug,
+                description=form_config.description,
+            )
+            if form_group is None:
+                response.ungrouped.append(form_config_response)
+            else:
+                response.grouped[form_group].append(form_config_response)
+
+        return response
+
     def get_single_form(self, form_slug: str) -> FormConfigResponseModel:
         """
         Returns the FormConfig for the given form.

piccolo_admin/example/forms/csv.py

@@ -49,4 +49,5 @@ async def download_movies(
     pydantic_model=DownloadMoviesModel,
     endpoint=download_movies,
     description="Download a list of movies for the director as a CSV file.",
+    form_group="Download forms",
 )

piccolo_admin/example/forms/email.py

@@ -44,4 +44,5 @@ def booking_endpoint(request: Request, data: BookingModel) -> str:
     pydantic_model=BookingModel,
     endpoint=booking_endpoint,
     description="Make a booking for a customer.",
+    form_group="Text forms",
 )

piccolo_admin/example/forms/image.py

@@ -39,4 +39,5 @@ def download_schedule(
     pydantic_model=DownloadScheduleModel,
     endpoint=download_schedule,
     description=("Download the schedule for the day."),
+    form_group="Download forms",
 )