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.
Note that the pinia
dependeny implies that you have mounted an app that uses pinia
before using Doric. For example:
// main.ts
import { createApp } from 'vue'
import { createPinia } from 'pinia'
import App from './App.vue'
const pinia = createPinia()
createApp(App).use(pinia).mount('#app')
npm install --save doric-framework
<script setup lang="ts">
// Required imports for Doric
import DoricFramework from 'doric-framework'
import "doric-framework/dist/style.css"
// Import a map of your widgets from index.ts at this path
import widgets from "@/components/doric-widgets/"
const workspace = [
[{
type: "passage-ref",
}, {
type: "dictionary",
}],
[{
type: "text-display",
}]
]
</script>
<template>
<DoricFramework :widgets="widgets" :workspace="workspace" />
</template>
Doric displays instance of widgets, which are Vue components. A minimal widget is defined as follows:
Composition API
<script setup>
import { useDoricOutput, useDoricInput } from 'doric-framework';
const setOsisRef = useDoricOutput("osisRef");
const osisRef = useDoricInput("osisRef");
</script>
<template>
<div>
<input type="text" v-model="osisRef.value" />
<button @click="setOsisRef(osisRef)">Set osisRef</button>
</div>
</template>
Options API
<template>
<div>
<input type="text" v-model="osisRef.value" />
<button @click="setOsisRef(osisRef)">Set osisRef</button>
</div>
</template>
<script>
import { useDoricOutput, useDoricInput } from 'doric-framework';
export default {
data() {
return {
// Define input methods
osisRef: useDoricInput("osisRef"),
}
},
setup() {
// Define output methods
return {
setOsisRef: useDoricOutput("osisRef"),
}
},
}
</script>
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.
// /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:
<!-- App.vue -->
<script>
import DoricFramework from 'doric-framework'
// If your Widget map is not in index.ts, you will need to specify it.
import widgets from "@/components/doric-widgets/"
...
</script>
<template>
<DoricFramework :widgets="widgets" />
</template>
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. |
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:
type WidgetInputState = {
widgetId: string;
key: string;
value: any;
};
To set initial state, your application may look something like this:
<script setup>
import DoricFramework, { pushWorkspaceState } from "doric-framework";
import widgets from "@/components/doric-widgets/";
const workspace = [
[{
type: "passage-ref",
}, {
type: "dictionary",
}],
[{
type: "text-display",
}]
]
// Set initial state
const onWorkspaceReady = () => {
pushWorkspaceState([
{
widgetId: "passage-ref",
key: "osisRef",
value: "Gen.1.1",
},
{
widgetId: "dictionary",
key: "selectedLemma",
value: "λογός",
},
]);
};
</script>
<template>
<DoricFramework
:widgets="widgets"
:workspace="workspace"
@onWorkspaceReady="onWorkspaceReady"
/>
</template>
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 <DoricFramework />
as the workspace
prop. This allows workspace state to be restored across sessions.
It may be imported alongside the DoricFramework
component as follows:
// App.vue
<script setup>
import DoricFramework, { exportWorkspace } from 'doric-framework'
</script>
Distributed under the MIT License. See LICENSE.txt
for more information.