nuxt-strapi-blocks-renderer 0.0.5 → 1.0.0

package/README.md

@@ -1,6 +1,253 @@
 # Nuxt Strapi Blocks Renderer
 
-Renderer module for the Strapi CMS blocks text element.
+A fully customizable Nuxt module for rendering the 'blocks' text element from Strapi CMS.
+
+## Installation
+
+1. Install the npm package:
+
+    ```bash
+    npm install nuxt-strapi-blocks-renderer
+    ```
+
+2. Add the module to `nuxt.config.{ts|js}`:
+
+    ```typescript
+    modules: ['nuxt-strapi-blocks-renderer']
+    ```
+
+## Usage
+
+To render text, use the `StrapiBlocksText` component:
+
+```vue
+<StrapiBlocksText :nodes="blockNodes" />
+```
+
+In this example, the `blockNodes` are taken from the JSON response which Strapi provides when using the `blocks` text
+element:
+
+```vue
+<script setup lang="ts">
+    import type { BlockNode } from 'nuxt-strapi-blocks-renderer/dist/runtime/types';
+    import type { Restaurant } from '~/types';
+
+    const route = useRoute();
+    const { findOne } = useStrapi();
+
+    // Fetch restaurants data from Strapi
+    const response = await findOne<Restaurant>('restaurants', route.params.id);
+    
+    // Obtain blocks text nodes from description field
+    const blockNodes: BlockNode[] = response.data.attributes.description;
+</script>
+
+<template>
+    <StrapiBlocksText :nodes="blockNodes" />
+</template>
+```
+
+### Advanced Usage
+
+In situations where your project requires specific styling or behavior for certain HTML tags such as `<a>`, `<p>`,
+and others, you can override the default rendering components used by the Nuxt Strapi Blocks Renderer.
+This flexibility allows you to tailor the rendering to align with your project's unique design and functional needs.
+
+#### Global Component Registration
+
+First, ensure that your components are globally registered in your Nuxt app.
+This step is crucial for your custom components to be recognized and used by the renderer.
+
+In your Nuxt configuration (`nuxt.config.{js|ts}`), add:
+
+```typescript
+components: {
+    dirs: [
+        {
+            path: '~/components',
+        },
+    ],
+    global: true,
+},
+```
+
+#### Customizing the Paragraph Tag
+
+To customize the rendering of the paragraph (`<p>`) tag, you need to create a corresponding Vue component.
+The name of the component follows a predefined pattern: `'StrapiBlocksText' + [NodeName] + 'Node.vue'`.
+To override the default paragraph tag, we create a file called `StrapiBlocksTextParagraphNode.vue`.
+
+```vue
+<!-- components/StrapiBlocksTextParagraphNode.vue -->
+<template>
+    <p class="my-custom-class-for-p">
+        <slot />
+    </p>
+</template>
+```
+
+This component assigns a custom class `my-custom-class-for-p` to the paragraph tag, which can be styled as needed.
+
+#### Other Custom Tags
+
+You can apply similar customizations to all other HTML tags used by the renderer.
+
+##### Headings
+
+Custom heading tags (`<h1>`, `<h2>`, `<h3>`, etc.):
+
+```vue
+<!-- components/StrapiBlocksTextHeading1Node.vue -->
+<template>
+    <h1 class="my-custom-class-for-h1">
+        <slot />
+    </h1>
+</template>
+
+<!-- components/StrapiBlocksTextHeading2Node.vue -->
+<template>
+    <h2 class="my-custom-class-for-h2">
+        <slot />
+    </h2>
+</template>
+```
+
+This pattern also extends to the `h3`, `h4`, `h5` and `h6` tags.
+
+##### Lists
+
+Custom list tags (`<ol>`, `<ul>` and `<li>`):
+
+```vue
+<!-- components/StrapiBlocksTextOrderedListNode.vue -->
+<template>
+    <ol class="my-custom-class-for-ol">
+        <slot />
+    </ol>
+</template>
+
+<!-- components/StrapiBlocksTextUnorderedListNode.vue -->
+<template>
+    <ul class="my-custom-class-for-ul">
+        <slot />
+    </ul>
+</template>
+
+<!-- components/StrapiBlocksTextListItemInlineNode.vue -->
+<template>
+    <li class="my-custom-class-for-li">
+        <slot />
+    </li>
+</template>
+```
+
+##### Blockquotes and Codes
+
+Custom blockquote and code tags (`<blockquote>`, `<pre>`):
+
+```vue
+<!-- components/StrapiBlocksTextQuoteNode.vue -->
+<template>
+    <blockquote class="my-custom-class-for-blockquote">
+        <slot />
+    </blockquote>
+</template>
+
+<!-- components/StrapiBlocksTextCodeNode.vue -->
+<template>
+    <pre class="my-custom-class-for-pre">
+        <slot />
+    </pre>
+</template>
+```
+
+##### Inline text nodes
+
+Custom inline text nodes (`<strong>`, `<em>`, `<u>`, `<del>`, `<code>`):
+
+```vue
+<!-- components/StrapiBlocksTextBoldInlineNode.vue -->
+<template>
+    <strong class="my-custom-class-for-strong">
+        <slot />
+    </strong>
+</template>
+
+<!-- components/StrapiBlocksTextItalicInlineNode.vue -->
+<template>
+    <em class="my-custom-class-for-em">
+        <slot />
+    </em>
+</template>
+
+<!-- components/StrapiBlocksTextUnderlineInlineNode.vue -->
+<template>
+    <u class="my-custom-class-for-u">
+        <slot />
+    </u>
+</template>
+
+<!-- components/StrapiBlocksTextStrikethroughInlineNode.vue -->
+<template>
+    <del class="my-custom-class-for-del">
+        <slot />
+    </del>
+</template>
+
+<!-- components/StrapiBlocksTextCodeInlineNode.vue -->
+<template>
+    <code class="my-custom-class-for-code">
+        <slot />
+    </code>
+</template>
+```
+
+##### Links
+
+Custom link tag (`<a>`):
+
+```vue
+<!-- components/StrapiBlocksTextLinkInlineNode.vue -->
+<script setup lang="ts">
+    const props = defineProps<{
+        url: string;
+    }>();
+</script>
+
+<template>
+    <a :href="props.url" class="my-custom-class-for-a">
+        <slot />
+    </a>
+</template>
+```
+
+When rendering a link tag, the url gets passed as the `url` component property.
+
+##### Images
+
+Custom image tag (`<img>`):
+
+```vue
+<!-- components/StrapiBlocksTextImageNode.vue -->
+<script setup lang="ts">
+    const props = defineProps<{
+        image: any;
+    }>();
+</script>
+
+<template>
+    <img
+        class="my-custom-class-for-img"
+        :src="props.image.url"
+        :alt="props.image.alternativeText"
+        :width="props.image.width"
+        :height="props.image.height"
+    >
+</template>
+```
+
+When rendering an image tag, the image object gets passed as the `image` component property.
+You can also use different image components here, i.e. `NuxtImg` or others.
 
 ## Development
 
@@ -11,15 +258,18 @@ npm install
 # Generate type stubs
 npm run dev:prepare
 
-# Develop with the playground
+# Develop with the basic text components playground
 npm run dev
 
-# Build the playground
-npm run dev:build
+# Develop with the custom text components playground
+npm run dev:custom
 
 # Run ESLint
 npm run lint
 
+# Run Vitest
+npm run test
+
 # Release new version
 npm run release
 ```

package/dist/module.json

@@ -1,5 +1,5 @@
 {
   "name": "nuxt-strapi-blocks-renderer",
   "configKey": "strapiBlocksRenderer",
-  "version": "0.0.5"
+  "version": "1.0.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "nuxt-strapi-blocks-renderer",
-    "version": "0.0.5",
+    "version": "1.0.0",
     "description": "Renderer for the strapi blocks text element.",
     "license": "MIT",
     "type": "module",