From 03d3bdb8057e207ec0eaa07f19041641b6996c46 Mon Sep 17 00:00:00 2001
From: Yi Lei Feng <fengyilei98@hotmail.com>
Date: Mon, 14 Aug 2023 10:58:49 -0400
Subject: [PATCH] add documentation for plugin usage in NPM

---
 README.md    | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 package.json |  2 +-
 2 files changed, 79 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index a5160109..ecef1082 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,77 @@
 # RAMP Storylines (formerly StoryRAMP)
 
-This project is an implementation of [RAMP2 FGP Visualiser](https://github.com/fgpv-vpgf/fgpv-vpgf), [Highcharts](https://www.highcharts.com/), and a number of other libraries, with the goal to provide a standards and guidelines compliant alternative to ArcGIS StoryMap, suitable for use in the Government of Canada's web presence. 
+This project is an implementation of [RAMP2 FGP Visualiser](https://github.com/fgpv-vpgf/fgpv-vpgf), [Highcharts](https://www.highcharts.com/), and a number of other libraries, with the goal to provide a standards and guidelines compliant alternative to ArcGIS StoryMap, suitable for use in the Government of Canada's web presence.
+
+## Plugin Usage
+
+To use the Storylines plugin in your Vue 3 project, follow these steps:
+
+**1. Install package from npm:**
+
+```
+npm install ramp-storylines
+```
+
+**2. Install the plugin in your Vue app:**
+
+```
+import { createApp } from 'vue';
+import App from './app.vue';
+const app = createApp(App);
+
+import StorylinesViewer from 'ramp-storylines'
+app.use(StorylinesViewer);
+import 'ramp-storylines/dist/storylines-viewer.css';
+```
+
+**3. Import or merge `i18n` instance from the plugin:**
+
+```
+import { storylinesI18n } from 'ramp-storylines'
+// if there is no existing i18n instance in your app, add Storylines i18n when initializing Vue instance:
+app.use(storylinesI18n);
+
+// otherwise merge the storylines translations with existing i18n instance
+i18n.mergeLocaleMessage('en', storylinesI18n.messages.en);
+i18n.mergeLocaleMessage('fr', storylinesI18n.messages.fr);
+app.use(i18n);
+```
+
+**4. Use Storylines components in your Vue templates, here is a demo snippet for usage:**
+
+```
+<header class="gray-200 sticky top-0 h-16 leading-9 w-full z-50 border-b border-gray-500 bg-gray-200">
+    <div class="flex w-full sm:px-6 py-3 mx-auto">
+        <storylines-mobile-toc class="mobile-menu" :active-chapter-index="activeChapterIndex" :slides="config.slides" :plugin="true"/>
+        <div class="truncate">
+            <span class="font-semibold text-lg m-1">{{ config.title }}</span>
+        </div>
+    </div>
+</header>
+
+<storylines-intro :config="config.introSlide"></storylines-intro>
+
+<div class="w-full mx-auto" id="story">
+    <storylines-content :config="config" @step="updateActiveIndex" :lang="lang" :plugin="true" />
+</div>
+
+...
+
+config = ... (see following section)
+activeChapterIndex = -1;
+updateActiveIndex(idx: number): void {
+    this.activeChapterIndex = idx;
+}
+
+```
+
+Here is a [demo](https://ramp4-pcar4.github.io/story-ramp/main/#/en/00000000-0000-0000-0000-000000000000) of what a Storylines product would look like.
+
+**5. Creating Storylines config:**
+
+To create a Storylines config from scratch, please refer to the schema documnentation provided [here](https://github.com/ramp4-pcar4/story-ramp/blob/main/StoryRampSchema.json). A demo config can be found [here](https://github.com/ramp4-pcar4/story-ramp/blob/main/public/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000_en.json).
+
+Alternatively, the [storylines editor](https://github.com/ramp4-pcar4/storylines-editor) can be leveraged to help construct a complete configuration folder.
 
 ## Project setup
 
@@ -20,6 +91,12 @@ npm run serve
 npm run build
 ```
 
+### Build as a Vue plugin
+
+```
+npm run build-plugin
+```
+
 ### Customize configuration
 
 See [Configuration Reference](https://cli.vuejs.org/config/).
diff --git a/package.json b/package.json
index 25653500..457f736e 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
     "name": "ramp-storylines",
     "description": "A user-configurable story product featuring interactive maps, charts and dynamic multimedia content alongside text.",
-    "version": "3.0.4",
+    "version": "3.0.5",
     "private": false,
     "license": "MIT",
     "repository": "https://github.com/ramp4-pcar4/story-ramp",