craft-vue-sdk v1.1.0

Craft Vue SDK

This package is part of the Craft Node Transformer Plugin and serves as a helper for Vue applications. It enables quick access to Craft CMS data within your Vue components.

Installation

npm i -D craft-vue-sdk

Register the plugin on your application (usually in main.ts), add the baseUrl to your craft cms backend

import { CraftSdk } from 'craft-vue-sdk';
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

app.use(CraftSdk, { 
  baseUrl: 'http://127.0.0.1:55003', 
  debug: false, 
  registerComponents: true 
})

app.mount('#app') 

Usage

Add a catch all route

Set up a catch-all route in your Vue app.

2. Add a Mapping Object

Create a mapping object where you map the sectionHandle to a page and the fieldHandle to a Vue component. An example setup might look like this

  import PageHome from '~/templates/pages/home.vue';
  import PageNews from '~/templates/pages/news.vue';

  import BlockImageText from '~/templates/blocks/imageText.vue'
  import BlockHeadline from '~/templates/blocks/headline.vue'

  const mapping = { 
    pages: {
      'home': PageHome,
      'news': PageNews,
    },
    components: {
      'imageText': BlockImageText,
      'headline': BlockHeadline,
    }
  };

3. Fetch Data from Your Craft Query API Endpoint

Using the useCraftUrlBuilder composable you can build craft queries. .buildUrl('one'|'all') returns the generated url for the query. The preview token gets applied automaticly.

import { useCraftUrlBuilder } from 'craft-vue-sdk';

const queryEntryUrl = useCraftUrlBuilder('entries')
  .slug('home')
  .section('home')
  .buildUrl('one');

try {
  // Fetch to your craft query api endpoint
  const response = await fetch(queryEntryUrl);
  console.log(response)

  if (!response.ok) {
    throw new Error(`Failed to fetch data from ${queryEntryUrl}: ${response.statusText}`);
  }

  const data = await response.json();

  // Check if your data is there 
  console.log('Fetched data:', data);
} catch (error) {
  // Handle your error
  throw new Error(`Could not fetch data from ${queryEntryUrl}`);
}

4. Display the Page

Use the CraftPage component to render the fetched page content. Don’t forget to import it!

<template>
  <div>
    <CraftPage v-if="data" :config="mapping" :content="data" />
  </div>
</template>

5. Use CraftArea for Matrix Blocks

To render matrix blocks in your entry, use the CraftArea component. Here’s an example:

<script setup lang="ts">
  import { CraftArea } from 'craft-vue-sdk';
  const props = defineProps({
    title: {
      type: String,
      required: true,
    },
    contentbuilder: {
      type: Object,
      default: () => null,
    },
  })
</script>

<template>
  <div>
    <Headline size="h1" as="h1">{{ props.title }}</Headline>
    <CraftArea v-if="props.contentbuilder" :content="props.contentbuilder"/>
  </div>
</template>

Available Options in useCraftUrlBuilder

Each type of element has its own function for creating element queries, and they each have their own parameters you can set. All element types expose parameters for their custom fields. Right now we support the following elementTypes.

Addresses:

Usage: useCraftUrlBuilder('addresses')

Available Methods:

Example:

const queryUrl = useCraftUrlBuilder('addresses')
  .id(1)
  .limit(5)
  .status('active')
  .offset(2)
  .orderBy('name')
  .addressLine1('123 Main St')
  .locality('Springfield')
  .fullName('John Doe')
  .buildUrl('one');

Assets:

Usage: useCraftUrlBuilder('assets')

Available Methods:

Example:

const queryUrl = useCraftUrlBuilder('assets')
  .id(1)
  .limit(5)
  .status('active')
  .offset(2)
  .orderBy('name')
  .volume('images')
  .kind('png')
  .filename('example.png')
  .site('default')
  .siteId(1)
  .buildUrl('all');

Entries:

Usage: useCraftUrlBuilder('entries')

Available Methods:

Example:

const queryUrl = useCraftUrlBuilder('entries')
  .id(1)
  .limit(5)
  .status('active')
  .offset(2)
  .orderBy('name')
  .slug('home')
  .section('home')
  .postDate('2023-01-01')
  .site('default')
  .siteId(1)
  .buildUrl('one');

Users:

Usage: useCraftUrlBuilder('Users')

Available Methods:

Example:

const queryUrl = useCraftUrlBuilder('users')
  .id(1)
  .limit(5)
  .status('active')
  .offset(2)
  .orderBy('name')
  .group('admins')
  .email('admin@test.com')
  .fullName('Admin User')
  .hasPhoto(true)
  .buildUrl('all');