@tamperan/zerocms-vue2 v0.0.3

Vue 2.x plugin for zeroCMS

zeroCMS is a headless/decoupled CMS focused on fast and easy editing, and straightforward integration into your development processes. Find out more at https://zerocms.dev

This package is a Vue 2.x plugin for integrating zeroCMS content in your Vue 2 app. If you're looking for other integrations (e.g. Vue 3!), check out the list at https://zerocms.dev/integrations

Note: This library is written in Typescript, and Typescript bindings are included. Many of the examples here are Javascript for simplicity, but full Typescript support is included.

Note #2: The rich text rendering components in this library use a Vue render function, so you do not need runtime-template-compiler in your app.

Get started

Install

npm i @tamperan/zerocms-vue2

Add to your existing Vue 2 app

import zerocms from '@tamperan/zerocms-vue2'

Vue.use(zerocms, {

  dev: false,
  region: 'us',
  repo: 'your_repo_slug',

  //target: '_',  - set this if you approve/publish to a specific Target for your UI
  locale: 'en', // fetch content in this locale
  
  onDocLinkClick: function(gslug) {
    //$vue.$router.push('/' + gslug);
    //$nuxt.$router.push('/' + gslug);
  }
});

Document link handling

In the example above, there is a callback onDocLinkClick. If your rich text content contains links to other docs then this callback will be called when the user clicks/taps on them.

You should implement this callback such that it appropriately directs the user to the right place. On a regular web site this normally means a route push.

However in an app, perhaps with embedded online help/docs, the appropriate action might instead be to open a <v-navigation-drawer> or similar to show the help in-line.

In either case, the server (and the author) are not concerned with URL structure - your UI is - so you can resolve the doc reference to an appropriate action or URL for your UI.

If your repo is configured to allow authors to create internal links from doc to doc, you must either implement this callback, or listen to the link events when using components to render content.

Rendering content

A basic example

The easiest way to render content in your app is to handle whole docs at a time.

For example, consider a Vue admin app that users zeroCMS to externalise its content so that Product/Support can tweak user-facing content at will, and to handle translations/localization.

The repo would typically have a doc type inline for inline text, and that doc type perhaps contains only a richtext element. One of the docs has slug homepage-welcome-message for, unsurprisingly, a welcome message for users!

You can embed that content easily into your Vue component like this:

<zerocms-doc type="inline" slug="homepage-welcome-message" @link="onDocLink"></zerocms-doc> 

Or this:

<zerocms-doc gslug="inline.homepage-welcome-message" @link="onDocLink"></zerocms-doc> 

You can use either of the above forms. Keeping type and slug separate can be easier for things like inline/embedded content. But using gslug can be easier if gslug is dynamic (e.g. as a result of being linked to).

The zerocms-doc component is an easy way to embed an entire doc into your Vue UI. Note that your authors can easily link from this welcome message into the app's help, docs, knowledgebase, etc - because your link event handler or onDocLinkClick callback can handle the appropriate action to then take.

The link event handler should accept a single property; the gslug of the doc being linked to. For example:

methods: {
    onDocLink(gslug) {
        // do things here
    }
}

Rendering a single element

Docs often contain multiple elements, e.g. a Title and some Content. To render only one, do the same but specify the element to render with the element prop:

<zerocms-doc type="inline" slug="homepage-welcome-message" element="title" @link="onDocLink"></zerocms-doc> 

Alternatively, if you already have a document object, you can use individual element components directly, e.g.:

<zerocms-plaintext :element="titleElement"></zerocms-plaintext>

Corresponding components exist for all the element types; e.g. zerocms-richtext, zerocms-image, etc.

Of course in this case you must provide the individual element object, not the whole doc.

Advanced topics

Structured data

This library wraps the underlying @tamperan/zerocms Javascript/Typescript library. You can access it directly if you wish, to retrieve docs and interrogate the data directly. This is more relevant for the data-oriented types such as bool and date.

For this, see the relevant docs directly at https://www.npmjs.com/package/@tamperan/zerocms

Customizing rendering

TODO

Other notes

Nuxt

This library works great with Nuxt.

To use with nuxt, put the above steps in a file in your plugins/ directory, and add a reference to it in the plugins section of nuxt.config.js.

You can find related instructions that will help here: https://debbie.codes/blog/nuxt-add-vue-plugins/

Also if you're using SSR, your app will need to provide node-fetch, as the Javascript Fetch API is not available on server-side Node.js