Custom Module - with HTML code - Step by Step

[koksikus]

I want to create a module in which I will display the user manual written in html.
I am missing a lot of information on how to do this.
How to make a list in the navigation panel as it appears in docs directus (icon text - link - and below the same). - Done!
How to make in the side bar, as in docs directus (I want an information icon to be displayed and that this panel can be closed). - Done!
In content, I want to have the html code I have pasted one, but after creating the module, I cannot select the finished text and copy it. - Done!
I have a question how to create new pages with navigation between them ... maybe here I will use Vue information, but the wings cut these two panels at the beginning of my way.... Where to find used classes?

Below is my code in module.vue:

import {useApi} from '@directus/extensions-sdk';

<template>
	<private-view title="User manual">
    <template #headline>Documentation</template>
      <template #title-outer:prepend>
        <v-button class="header-icon" rounded disabled icon secondary>
          <v-icon name="build" />
        </v-button>
    </template>

    <template #navigation>
      <v-list v-model="selection" nav :mandatory="false" scope="manuals-navigation">
          <v-list-item v-for="(item, i) in items"
            :key="i"
            router :to="item.to"
          >
          <v-list-item-icon> <v-icon :name="item.icon" /></v-list-item-icon>
          <v-list-item-content>
            <v-text-overflow :text="item.name" />
          </v-list-item-content>
        </v-list-item>
      </v-list>
    </template>

    <template #sidebar>
      <sidebar-detail icon="info_outline" :title="'Information'" close>
        <div v-md="'This is the PTM users guide module created by .....'" class="page-description"></div>
      </sidebar-detail>
    </template>

    <div class="docs-content selectable">
			<router-view />
		</div>
  </private-view>
</template>

<style lang="scss" scoped>
  .docs-content {
    padding: 0 var(--content-padding) var(--content-padding-bottom);
  }
</style>

<script lang="ts">
import Home from './Home.vue'
import Second from './Second.vue'

export default {
    data: () => ({
      selectedItem: 1,
      items: [
        { name: 'Home', to: '/user-manual/', icon: 'school', component: Home },
        { name: 'Second', to: '/user-manual/Second', icon: 'list_alt', component: Second }
      ],
    })
  }
</script>

[rijkvanzanten]

In content, I want to have the html code I have pasted one, but after creating the module, I cannot select the finished text and copy it.

This is because everything by default has user-select: none applied. You can unset that, or add a selectable class to the things you want to make copyable.

I have a question how to create new pages with navigation between them ... maybe here I will use Vue information, but the wings cut these two panels at the beginning of my way.... Where to find used classes?

The custom module definition index.js takes an array of routes. These routes are passed to vue-router, so that's how you'd add multiple routes to your custom module.

See https://docs.directus.io/extensions/modules.html#routes-array for more information on that

[rijkvanzanten]

The only visible error is link Page1 in the menu is still highlighted. It's probably about routes, I tried to change but it's only worse... (Probably the point is that the link Page1 coincides with the main address).

I think there's another vue-router trick about that. I believe you can add the exact prop to your router link to only have it be made active when the full route matches, rather than just the parent route: https://v3.router.vuejs.org/api/#exact

With the above solution, e.g. "blockquote" in html does not work. How to enter formatting?
Using WYSIWYG in the Directus database and then displaying it in the module will I keep the formatting?

Yes, but you have to render the contents using Vue's v-html. Otherwise it'll auto-escape the html tags for security. Do make sure that you trust the source that creates your html, or pass it through a sanitization library to strip out any insecure html when rendering it in your module.

When creating a module with an instruction manual using a collection idea should I only modify index.ts?

I'd imagine that you have a single route in your index.ts file that is /:id that then has a single vue component that will dynamically download the content for that page using the API. In pseudo code (haven't tested this, just as an example), you'd do something like:

<template>
  <!-- all the private view stuff should go around this too -->

  <div v-if="loading">Loading...</div>
  <div v-else v-html="pageContent" />
</template>

<script setup>
import { ref, watch } from 'vue';
import { useRoute } from 'vue-router';
import { useApi } from '@directus/extensions-sdk';

const route = useRoute();
const api = useApi();

const loading = ref(false);
const pageContent = ref();

const loadItem = async () => {
  try {
    const item = await api.get(`/items/your-content-collection/${route.params.id}`);
    pageContent.value = item.data.your_html_field;
  } finally {
    loading.value = false;
  }
});

watch(() => route.params.id, loadItem);
</script>

i'll leave the additional razzle dazzle (like error handling, loading states, designs, etc etc) up to you 😉

[koksikus]

Works great again!!

file module.vue:

import {useApi} from '@directus/extensions-sdk';

<template>
	<private-view title="User manual">
    <template #headline>Documentation</template>
      <template #title-outer:prepend>
        <v-button class="header-icon" rounded disabled icon secondary>
          <v-icon name="build" />
        </v-button>
    </template>

    <template #navigation>
      <v-list v-model="selection" nav :mandatory="false" scope="manuals-navigation">
          <v-list-item v-for="(item, i) in items"
            :key="i"
            router :to="item.to" exact
          >
          <v-list-item-icon> <v-icon :name="item.icon" /></v-list-item-icon>
          <v-list-item-content>
            <v-text-overflow :text="item.name" />
          </v-list-item-content>
        </v-list-item>
      </v-list>
    </template>

    <template #sidebar>
      <sidebar-detail icon="info_outline" :title="'Information'" close>
        <div v-md="'This is users guide module created by .....'" class="page-description"></div>
      </sidebar-detail>
    </template>

    <div class="docs-content selectable">
      <router-view></router-view>
		</div>
  </private-view>
</template>

<style lang="scss" scoped>
  .docs-content {
    padding: 0 var(--content-padding) var(--content-padding-bottom);
  }
</style>

<script lang="ts">
export default {
    data: () => ({
      items: [
        { name: 'Page1', to: '/user-manual', icon: 'school' },
        { name: 'Page2', to: '/user-manual/Page2', icon: 'list_alt' },
		    { name: 'Page3', to: '/user-manual/Page3', icon: 'list_alt' }
            ],
    })
  }
</script>

file page1.vue:

<template>
<div v-html="html">
</div>
</template>

<script>
export default {
  name: "Page1",
  data() {
    return{
      html:`
      here html code
`
    }
  }
};
</script>

file index.ts:

import {defineModule} from '@directus/extensions-sdk';
import Module from './components/module.vue';
import Page1 from './components/page1.vue';
import Page2 from './components/page2.vue';
import Page3 from './components/page3.vue';


export default defineModule ({
	id: 'user-manual',
	name: '$t:user-manual',
	icon: 'help_outline',
	
	routes: [
		{
		  path: '',
		component: Module,
		  children: [
			{
				path: '',
				component: Page1
			},
			{
				path: 'Page2',
				component: Page2,
			},
			{
				path: 'Page3',
				component: Page3,
			},
		  ],
		},
	  ],
});

file package.json:

{
  "name": "manuals",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
	  "test": "echo \"Error: no test specified\" && exit 1"
  },
  "directus:extension": {
  "type": "module",
  "path": "index.js",
  "source": "index.ts",
  "host": "9.17",
  "hidden": false
  }
  
}

I just have to work on the style of html code - not everything works in it like "blockquote"...

[koksikus]

Thank you Rijkvanzanten for the code. I have to work on it now. First I have to read a lot about vue etc :)

[koksikus]

First I have made collection:

[koksikus]

index.ts has this code:

import {defineModule} from '@directus/extensions-sdk';
import Module from './module.vue';

export default defineModule ({
	id: 'user-manual',
	name: '$t:user-manual',
	icon: 'help_outline',
	
	
	routes: [
		{
			path: '/:id',
			component: Module,
		},
	  ],
});

module.vue has this code:

<template>
	<private-view title="User manual">
    <template #headline>Documentation</template>
      <template #title-outer:prepend>
        <v-button class="header-icon" rounded disabled icon secondary>
          <v-icon name="build" />
        </v-button>
    </template>

    <template #navigation>
      <v-list v-model="selection" nav :mandatory="false" scope="manuals-navigation">
          <v-list-item v-for="(col, i) in collections"
            :key="col.collection"
            router :to="'/user-manual/'+col.menu" exact
          >
          <v-list-item-icon> <v-icon :name="col.icon" /></v-list-item-icon>
          <v-list-item-content>
            <v-text-overflow :text="col.menu" />
          </v-list-item-content>
        </v-list-item>
      </v-list>
    </template>

    <template #sidebar>
      <sidebar-detail icon="info_outline" :title="'Information'" close>
        <div v-md="'This is the PTM users guide module created by .....'" class="page-description"></div>
      </sidebar-detail>
    </template>

    <div class="docs-content selectable">
      <div v-if="loading">Loading...</div>
      <div v-else v-html="pageContent" />
      <v-button v-on:click="logToConsole">Log items in collection to console</v-button>  
	</div>
  </private-view>
</template>

<style lang="scss" scoped>
.docs-content {
	padding: 0 var(--content-padding) var(--content-padding-bottom);
}

.v-chip {
	--v-chip-background-color: var(--v-chip-background-color-hover);
	--v-chip-color: var(--v-chip-color-hover);

	margin-left: 12px;
	cursor: default !important;
}
</style>

<script setup>
import { ref, watch } from 'vue';
import { useRoute } from 'vue-router';
import { useApi } from '@directus/extensions-sdk';

const route = useRoute();
const api = useApi();

const loading = ref(false);
const pageContent = ref();

const loadItem = async () => {
  try {
    const item = await api.get(`/items/user_manual/${route.params.id}`);
    return pageContent = item.data.content;
  } finally {
    return loading.value = false;
  }
};
// Get a list of all items available in collection to use in menu
this.api.get('/items/user_manual?limit=-1').then((collection) => {
			this.collections = collection.data.data;
		});
watch(() => route.params.id, loadItem);
</script>

but when i try to compile the module i get the message: | Building Directus extension..."createCommentVNode" is imported from external module "vue" but never used in "src/module.vue?vue&type=script&setup=true&lang.js".
I can't find information about this anywhere. What causes this error?

[Silbad]

Hello, thanks for this. It helped me a lot ^^
Could you give me an example to add options in sidebar ?

[cube-dan]

Your example was a huge help @koksikus! Thanks for posting it.

[koksikus]

I'm glad I could help. Below is a ready module for displaying data from the collection. The collection must be "Help" and have fields: status (dropdown), title (input), menu_title (input), icon (icon), content (WYSIWYG). These fields are required. If the status is "published", the record will appear in the module.
By the way, I have to thank sks user for his help.

import { watch, resolveComponent, openBlock, createBlock, withCtx, createVNode, createElementBlock, Fragment, withDirectives, renderList, createElementVNode, resolveDirective } from 'vue';

var script = {
    inject: ['api'],
    data(){
        return { docs: [], index: {}, selected: {} }
    },
    props: {
        id: { type: String, required: true }
    },
    async mounted() {

        const { data, status } = await this.api.get(`/items/help`, {
            params: {
                limit: -1, filter: { status: 'published' }
            }
        });

        if(status !== 200) return;
        this.docs = data['data'];
        this.docs.map(doc => this.index[doc['id']] = doc);

        watch(
            () => this.id,
            (id)=> {
                if(!this.id) this.$router.push(`/help/${this.docs[0]['id']}`);
                else this.selected = this.index[id];
            },
            { immediate: true }
        );
    },
};

const _hoisted_1 = {
  class: "docs-content selectable",
  style: {"padding":"0 var(--content-padding) var(--content-padding-bottom)"}
};
const _hoisted_2 = ["innerHTML"];
const _hoisted_3 = { class: "page-description" };

function render(_ctx, _cache, $props, $setup, $data, $options) {
  const _component_v_icon = resolveComponent("v-icon");
  const _component_v_button = resolveComponent("v-button");
  const _component_v_list_item_icon = resolveComponent("v-list-item-icon");
  const _component_v_text_overflow = resolveComponent("v-text-overflow");
  const _component_v_list_item_content = resolveComponent("v-list-item-content");
  const _component_v_list_item = resolveComponent("v-list-item");
  const _component_v_list = resolveComponent("v-list");
  const _component_docs_wrapper = resolveComponent("docs-wrapper");
  const _component_private_view = resolveComponent("private-view");
  const _component_sidebar_detail = resolveComponent("sidebar-detail");
  const _directive_md = resolveDirective("md");

  return (openBlock(), createBlock(_component_private_view, {
    title: $data.selected['title']
  }, {
    "title-outer:prepend": withCtx(() => [
      createVNode(_component_v_button, {
        rounded: "",
        disabled: "",
        icon: ""
      }, {
        default: withCtx(() => [
          createVNode(_component_v_icon, {
            name: $data.selected['icon'] ?? 'info'
          }, null, 8 /* PROPS */, ["name"])
        ]),
        _: 1 /* STABLE */
      })
    ]),
    navigation: withCtx(() => [
      createVNode(_component_v_list, {
        nav: "",
        scope: "content-navigation",
        class: "content-navigation",
        tabindex: "-1",
        dense: true
      }, {
        default: withCtx(() => [
          (openBlock(true), createElementBlock(Fragment, null, renderList($data.docs, (doc) => {
            return (openBlock(), createBlock(_component_v_list_item, {
              to: `/help/${doc['id']}`,
              value: doc['menu_title']
            }, {
              default: withCtx(() => [
                createVNode(_component_v_list_item_icon, null, {
                  default: withCtx(() => [
                    createVNode(_component_v_icon, {
                      name: doc['icon'] ?? 'label',
                      color: doc['color'] ?? ''
                    }, null, 8 /* PROPS */, ["name", "color"])
                  ]),
                  _: 2 /* DYNAMIC */
                }, 1024 /* DYNAMIC_SLOTS */),
                createVNode(_component_v_list_item_content, null, {
                  default: withCtx(() => [
                    createVNode(_component_v_text_overflow, {
                      text: doc['menu_title']
                    }, null, 8 /* PROPS */, ["text"])
                  ]),
                  _: 2 /* DYNAMIC */
                }, 1024 /* DYNAMIC_SLOTS */)
              ]),
              _: 2 /* DYNAMIC */
            }, 1032 /* PROPS, DYNAMIC_SLOTS */, ["to", "value"]))
          }), 256 /* UNKEYED_FRAGMENT */))
        ]),
        _: 1 /* STABLE */
      })
    ]),
    sidebar: withCtx(() => [
      createVNode(_component_sidebar_detail, {
        icon: "info_outline",
        title: 'Information',
        close: ""
      }, {
        default: withCtx(() => [
          withDirectives(createElementVNode("div", _hoisted_3, null, 512 /* NEED_PATCH */), [
            [_directive_md, 'This is users guide module created by ....']
          ])
        ]),
        _: 1 /* STABLE */
      })
    ]),

    default: withCtx(() => [
      createElementVNode("div", _hoisted_1, [
        createVNode(_component_docs_wrapper, { frontmatter: "" }, {
          default: withCtx(() => [
            createElementVNode("div", {
              innerHTML: $data.selected['content'] || $data.selected['body']
            }, null, 8 /* PROPS */, _hoisted_2)
          ]),
          _: 1 /* STABLE */
        })
      ])
    ]),
    _: 1 /* STABLE */
  }, 8 /* PROPS */, ["title"]))
}

script.render = render;
script.__file = "src/module.vue";

var index = {
	id: 'help',
	name: 'Help',
	icon: 'help_outline',
	routes: [
		{
			path: '',
			component: script,
		},
		{
			path: ':id',
			component: script,
			props: (route) => {
				return {
					id: route.params.id,
				};
			},
		}
	],
};

export { index as default };

[cube-dan]

@koksikus,

Are you willing to share the pre directus-extension build version of the .vue/.ts files that generated the code you posted?

To be clear, I'm not asking for the whole modules /src folder, just the pre transpiled example like you posted here.