npm package: @tamperan/zerocms-vue2
Description: Vue 2.x plugin for zeroCMS
Author: Tamperan
Latest version: 0.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

```shell
npm i @tamperan/zerocms-vue2
```

### Add to your existing Vue 2 app

```javascript
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:

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

Or this:

```vue
<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:

```js
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:

```vue
<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.:

```vue
<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