From 93f8083352702d9e9040d23fa5d58e6095f21e5b Mon Sep 17 00:00:00 2001 From: Chavez Harris <74829200+codedbychavez@users.noreply.github.com> Date: Mon, 22 Jan 2024 07:30:57 -0300 Subject: [PATCH] Add Vue.js SDK to the docs (#349) * Add base documentation * Updated base draft * Update usage documentation and create schema-markup * Add footer links, sidebar link, update schema-markup and draft documentation * Uncomment schema markup reference * Add link to sample app and GitHub Repository * Update website/docs/sdk-reference/community/vue.md * Update website/sidebars.js Co-authored-by: adams85 <31276480+adams85@users.noreply.github.com> * Update website/docs/sdk-reference/community/vue.md Co-authored-by: adams85 <31276480+adams85@users.noreply.github.com> * Update website/docs/sdk-reference/community/vue.md Co-authored-by: adams85 <31276480+adams85@users.noreply.github.com> * Update website/docs/sdk-reference/community/vue.md Co-authored-by: adams85 <31276480+adams85@users.noreply.github.com> * add consistent formatting * Add link to the Vue.js SDK page on the overview page * Update website/docs/sdk-reference/overview.md Co-authored-by: Gergely Sinka <58779216+sigewuzhere@users.noreply.github.com> * Update website/docs/sdk-reference/community/vue.md Co-authored-by: Lajos Szoke <63732287+laliconfigcat@users.noreply.github.com> * Update website/docs/sdk-reference/community/vue.md Co-authored-by: Lajos Szoke <63732287+laliconfigcat@users.noreply.github.com> * Update website/docs/sdk-reference/community/vue.md Co-authored-by: Lajos Szoke <63732287+laliconfigcat@users.noreply.github.com> * Update website/docs/sdk-reference/community/vue.md Co-authored-by: Lajos Szoke <63732287+laliconfigcat@users.noreply.github.com> * Update website/docs/sdk-reference/community/vue.md Co-authored-by: Lajos Szoke <63732287+laliconfigcat@users.noreply.github.com> * Update website/docs/sdk-reference/community/vue.md Co-authored-by: Lajos Szoke <63732287+laliconfigcat@users.noreply.github.com> * Update website/docs/sdk-reference/overview.md Co-authored-by: Lajos Szoke <63732287+laliconfigcat@users.noreply.github.com> --------- Co-authored-by: adams85 <31276480+adams85@users.noreply.github.com> Co-authored-by: Gergely Sinka <58779216+sigewuzhere@users.noreply.github.com> Co-authored-by: Lajos Szoke <63732287+laliconfigcat@users.noreply.github.com> --- website/docs/sdk-reference/community/vue.md | 256 ++++++++++++++++++ website/docs/sdk-reference/overview.md | 5 + website/sidebars.js | 5 + website/src/pages/index.js | 1 + .../sdk-reference/community/vue.json | 53 ++++ 5 files changed, 320 insertions(+) create mode 100644 website/docs/sdk-reference/community/vue.md create mode 100644 website/src/schema-markup/sdk-reference/community/vue.json diff --git a/website/docs/sdk-reference/community/vue.md b/website/docs/sdk-reference/community/vue.md new file mode 100644 index 00000000..c7b8c1e2 --- /dev/null +++ b/website/docs/sdk-reference/community/vue.md @@ -0,0 +1,256 @@ +--- +id: vue +title: ConfigCat SDK for Vue.js +description: Unofficial Vue SDK for ConfigCat Feature Flags. Based on ConfigCat's JavaScript SDK. +--- + +export const VueSchema = require('@site/src/schema-markup/sdk-reference/community/vue.json'); + + + +:::caution +As this is a community-maintained package, ConfigCat can't guarantee its stability, and safety and can't provide official customer support. +::: + +ConfigCat SDK for Vue.js on GitHub + +## Getting Started + +### 1. Install the package + +_via [npm](https://www.npmjs.com/package/configcat-vue)_ + +```bash +npm i configcat-vue +``` + +### 2. Import and use the `ConfigCatPlugin` with your SDK Key + +In **main.ts**: + +```js +import { ConfigCatPlugin } from "configcat-vue"; +``` + +```js +app.use(ConfigCatPlugin, { + sdkKey: "YOUR-CONFIGCAT-SDK-KEY-GOES-HERE", // sdkKey is required +}); +``` + +### 3. Get your setting value + +This SDK includes a `FeatureWrapper` component. It enables users to control the visibility of specific parts within their Vue.js application (such as components or HTML elements) when the feature flag is enabled. + +In any `.vue` component file: + +```vue + +``` + +Pass the feature flag key as a prop: + +```js + +``` + +Optionally, the `FeatureWrapper` component also provides an `#else` and `#loading` template. Components or HTML elements can be included within these templates that would display when the feature flag is **turned off** or **loading** respectively. + +```js + + + + + +``` + +## Advanced Usage + +### Specifying a polling mode + +Polling modes are used to control how often ConfigCat's SDK client downloads the values of feature flags from ConfigCat's servers. The default polling mode is `AutoPoll`. Auto Polling fetches the latest feature flag values every 60 seconds by default. To change this, Specify a polling mode and set the polling interval (in seconds) via the `pollingIntervalInSeconds` property. + +Import: + +```js +import { PollingMode } from "configcat-vue"; +``` + +Add `pollingMode` to the `ConfigCatPlugin` options and set the polling interval via the `clientOptions` property: + +```js +app.use(ConfigCatPlugin, { + sdkKey: "YOUR-CONFIGCAT-SDKKEY-GOES-HERE", + pollingMode: PollingMode.AutoPoll, // Optional. Default is AutoPoll + clientOptions: { + pollIntervalSeconds: 5 // Optional. Specify the polling interval in seconds. The default is 60 seconds. + } +}); + +``` + +`pollingMode` can be set to: `PollingMode.AutoPoll`, `PollingMode.ManualPoll` and `PollingMode.LazyLoad` + +> See documentation [here](/advanced/caching/). + +### Using the plugin with a logger + +You may want to log the actions of the underlying ConfigCat SDK client. To do this, specify a logger in `clientOptions`: + +> See documentation [here](/sdk-reference/js/#logging). + +Add `createConsoleLogger`, and `LoggerLevel` to your import: + +```js +import { createConsoleLogger, LogLevel } from "configcat-vue"; +``` + +Create the logger with a specified log level: + +> See documentation [here](/sdk-reference/js/#setting-log-levels). + +Use the logger in `clientOptions`: + +```js +app.use(ConfigCatPlugin, { + sdkKey: "YOUR-CONFIGCAT-SDK-KEY-GOES-HERE", // // sdkKey is required + clientOptions: { // clientOptions is optional + // ... + logger: createConsoleLogger(LogLevel.Info), + } +}); +``` + +#### Available log levels + +| Level | Description | +| ----- | ------------------------------------------------------- | +| Off | Nothing gets logged. | +| Error | Only error level events are logged. | +| Warn | Default. Errors and Warnings are logged. | +| Info | Errors, Warnings and feature flag evaluation is logged. | +| Debug | All of the above plus debug info is logged. | + +### Specifying a User Object + +The [User Object](/advanced/user-object/) stores attributes of a user in your application. It works hand in hand with ConfigCat's [Targeting](/advanced/targeting/) rules for targeting specific users with feature flags. A User Object can be passed as a prop to the `FeatureWrapper` component. + +> See documentation [here](/advanced/user-object/). + +Define the User Object: + +```js + +``` + +Pass it to the `FeatureWrapper` component: + +```js + +``` + +### Listening to flag changes emitted from the FeatureWrapper component + +When a feature flag is toggled ON or OFF in the [ConfigCat dashboard](https://app.configcat.com) the `FeatureWrapper` component emits the updated feature flag value. How quickly the updated value is emitted depends on the polling interval set in the `clientOptions` property of the `ConfigCatPlugin`. + +Listen and handle changes using `@flag-value-changed`: + +```js + +``` + +```js + +``` + +### Using the underlying ConfigCat client + +This plugin exposes (provides) the underlying ConfigCat client. By injecting the provided client instance, you can use all the features it offers. + +> See documentation [here](/sdk-reference/js). + +One of the ways it can be used is by subscribing to events emitted by the ConfigCat client. + +Inject the ConfigCat client into your component: + +```js + +``` + +## Sample Application + +- Sample Vue.js App + +## Look under the hood + +- ConfigCat Vue.js SDK on GitHub +- ConfigCat Vue.js SDK on NPM diff --git a/website/docs/sdk-reference/overview.md b/website/docs/sdk-reference/overview.md index 969ab747..04b22f99 100644 --- a/website/docs/sdk-reference/overview.md +++ b/website/docs/sdk-reference/overview.md @@ -53,6 +53,11 @@ Check out our language specificGitHub repository of the ConfigCat Deno SDK. +## JavaScript (Vue.js) - Community maintained + +- [Documentation](/sdk-reference/community/vue) on how to connect your application. +- GitHub repository of the ConfigCat Vue.js SDK. + ## JavaScript (React) - [Documentation](/sdk-reference/react) on how to connect your application. diff --git a/website/sidebars.js b/website/sidebars.js index 922d8c4d..add44424 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -175,6 +175,11 @@ module.exports = { id: 'sdk-reference/community/deno', label: 'TypeScript (Deno)', }, + { + type: 'doc', + id: 'sdk-reference/community/vue', + label: 'JavaScript (Vue.js)', + }, ], }, ], diff --git a/website/src/pages/index.js b/website/src/pages/index.js index 20582b93..2c7e5db2 100644 --- a/website/src/pages/index.js +++ b/website/src/pages/index.js @@ -70,6 +70,7 @@ const features = [ { url: 'sdk-reference/android', title: 'Java (Android)' }, { url: 'sdk-reference/js', title: 'JavaScript' }, { url: 'sdk-reference/community/deno', title: 'JavaScript (Deno)' }, + { url: 'sdk-reference/community/vue', title: 'JavaScript (Vue.js)' }, { url: 'sdk-reference/react', title: 'JavaScript (React)' }, { url: 'sdk-reference/js-ssr', title: 'JavaScript (SSR)' }, { url: 'sdk-reference/kotlin', title: 'Kotlin Multiplatform' }, diff --git a/website/src/schema-markup/sdk-reference/community/vue.json b/website/src/schema-markup/sdk-reference/community/vue.json new file mode 100644 index 00000000..2e668971 --- /dev/null +++ b/website/src/schema-markup/sdk-reference/community/vue.json @@ -0,0 +1,53 @@ +{ + "@context": "https://schema.org/", + "@type": "HowTo", + "name": "How to use feature flags in Vue.js?", + "description": "How to use feature flags in Vue.js using ConfigCat Feature Flags.", + "image": "https://configcat.com/images/shared/home.png", + "totalTime": "PT10M", + "estimatedCost": { + "@type": "MonetaryAmount", + "currency": "USD", + "value": "0" + }, + "supply": { + "@type": "HowToSupply", + "name": "ConfigCat", + "image": "https://configcat.com/images/shared/home.png", + "url": "https://configcat.com" + }, + "tool": { + "@type": "HowToTool", + "name": "ConfigCat Feature Flags - https://configcat.com" + }, + "step": [ + { + "@type": "HowToStep", + "text": "Sign up for a free ConfigCat account", + "image": "https://configcat.com/images/shared/home.png", + "name": "Registration", + "url": "https://app.configcat.com/auth/signup" + }, + { + "@type": "HowToStep", + "text": "Install the package", + "image": "https://configcat.com/images/shared/home.png", + "name": "Installation", + "url": "https://configcat.com/docs/sdk-reference/community/vue/#1-install-the-package" + }, + { + "@type": "HowToStep", + "text": "Import and use the plugin", + "image": "https://configcat.com/images/shared/home.png", + "name": "Import and use", + "url": "https://configcat.com/docs/sdk-reference/community/vue/#2-import-and-use-the-configcatplugin-with-your-sdk-key" + }, + { + "@type": "HowToStep", + "text": "Get your setting value", + "image": "https://configcat.com/images/shared/home.png", + "name": "Evaluation", + "url": "https://configcat.com/docs/sdk-reference/community/vue/#3-get-your-setting-value" + } + ] +}