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.

Dependencies

• pinia
• splitpanes
• vuedraggable

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')

Installation

npm install --save doric-framework

Usage

Basic Usage

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

Writing Widgets

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

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

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

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.

// /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>

API Reference

Doric Framework Props

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. |

Pushing State to the Workspace

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>

Exporting the Current Workspace

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>

License

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