Table of Contents

- About the Project
- Description
- Dependencies
- Installation
- Usage
- Basic Usage
- Writing Widgets
- Passing Widgets to Doric
- API Reference
- Doric Framework Props
- Exporting the Current Workspace
- License

About the Project

Description

Doric Framework is a column-based widget UI framework for Vue 3. It displays custom widgets in a workspace, allowing users to drag and drop widgets into columns and rearrange them.

(back to top)

Dependencies

- pinia
- splitpanes
- vuedraggable

Note that the pinia dependeny implies that you have mounted an app that uses pinia before using Doric. For example:

``ts
// main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'

const pinia = createPinia()
createApp(App).use(pinia).mount('#app')
`

(back to top)

Installation

`sh
npm install --save doric-framework
`

(back to top)

Usage

Basic Usage

`vue



`

(back to top)

Writing Widgets

Doric displays instance of widgets, which are Vue components. A minimal widget is defined as follows:

(back to top)

Passing Widgets to Doric

Doric expects a list of widgets to be passed to it. This list is a map of widget types to default labels and widget components. It is typical to import all the widgets in a single file and pass them to Doric.

`ts
// /src/components/doric-widgets/index.ts
import MyFirstWidget from "@/components/doric-widgets/MyFirstWidget.vue";
import MySecondWidget from "@/components/doric-widgets/MySecondWidget.vue";

export default {
"my-first-widget": {
defaultLabel: "My First Widget",
widget: MyFirstWidget,
},
"my-second-widget": {
defaultLabel: "My Second Widget",
widget: MySecondWidget,
},
};
`

These widgets can then be passed to Doric as follows:

`vue




`

(back to top)

API Reference

$3

The DoricFramework component accepts the following props:

| Prop | Type | Description |
| --- | --- | --- |
| widgets | WidgetComponentMap | A map of widget types to default labels and widget components (see example above). |
| workspace | Workspace | A list of columns, each of which is a list of widgets. A minimal Widget is an object that includes a type, which is a key in the WidgetComponentMap. |
| locked | boolean | Whether the workspace is locked. |
| @setSharedParams | Function | A callback function that is emitted whenever a widget's input value changes and it is marked as shared. |
| @onWorkspaceReady | Function | A callback function that is emitted after the workspace property has been changed and the new workspace is ready. Useful for setting initial state. |

$3

Doric exports the pushWorkspaceState function for pushing state to the current workspace. The main use of pushWorkspaceState is to set initial values (e.g., from localstorage or a url), but state may also come from outside Doric in realtime applications. pushWorkspaceState expects a WidgetInputState[]. WidgetInputState is an object with three fields:

`ts
type WidgetInputState = {
widgetId: string;
key: string;
value: any;
};
`

To set initial state, your application may look something like this:

`vue



`

$3

The doric-framework package provides an exportWorkspace function. This function serializes the current workspace into a minimal Workspace—i.e., a Widget[][] that includes the position of widgets in columns as well as their non-falsy input values, subscription, sharing states. Thus, the return type of exportWorkspace may be passed into as the workspace prop. This allows workspace state to be restored across sessions.

It may be imported alongside the DoricFramework component as follows:

`vue
// App.vue

`

(back to top)

License

Distributed under the MIT License. See LICENSE.txt` for more information.

(back to top)