• Stars
    star
    212
  • Rank 186,122 (Top 4 %)
  • Language
    TypeScript
  • License
    MIT License
  • Created about 1 year ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Define forms for filling data that you will be able to open from anywhere you can run JS

GitHub all releases Buy Me A Coffee ko-fi

Obsidian Modal Form Plugin

This plugin for Obsidian allows you to define forms that can be opened from anywhere you can run JavaScript, so you can combine it with other plugins like Templater or QuickAdd.

frontmmatter-demo.mov

Features

  • Forms open in a modal window and return you the values, so you can trigger it from:
    • Templater templates
    • QuickAdd captures
    • DataviewJS queries
    • Many other places...
  • Define forms using a simple JSON format
  • Create and manage a collection of forms, each identified by a unique name
  • User interface for creating new forms
  • Create new notes directly from the form using templates
    • Template editor has a nice UI for creating templates
  • Many input types
    • number
    • date
    • time
    • slider
    • toggle (true/false)
    • free text
    • text with autocompletion for note names (from a folder or root)
    • text with autocompletion from a dataview query (requires dataview plugin)
    • multiple choice input
    • select from a list
      • list of fixed values
      • list of notes from a folder

example form templates

Why this plugin?

Obsidian is a great tool for taking notes, but it is also a nice for managing data. However, when it's time to capture structured data it doesn't offer many conveniences. Some plugins like Templater or QuickAdd alleviate this problem with templates/automation that ease the creation of notes with a predefined structure, but then you have to fill the data manually. The mentioned plugins (Templater, QuickAdd) have some little convenience inputs, but they have certain tradeoffs/problems:

  • they are limited to inputting a single value at a time
  • they don't have labels or detailed descriptions about the field you are filling
  • you can't skip fields, you will always be prompted for all of them one by one

All of the mentioned tools are great at their job and unleash super convenient workflows. For that reason, rather than offering an alternative, this plugin is designed as a complement to them, offering some basic building blocks that you can integrate with your existing templates and workflows.

Friends of modal form

  • Templater to open modals from templates
  • QuickAdd to quickly capture data from a modal
  • dataview to provide values for auto-completion

Scope of this plugin

This plugin is intentionally narrow in scope. As mentioned in the previous section, it is designed as a building block, so you can integrate it with other plugins and workflows. The only features that I will consider adding will be ones about improving the form itself.

Usage

Call the form from JavaScript

Since the main usage of this plugin is opening forms and getting back their data let's start with that. If you want to learn how to create forms, skip to the next section define a form.

The plugin exposes an API that can be accessed from any JavaScript code that has access to the global app object. So, in order to get the API you can do:

const modalForm = app.plugins.plugins.modalforms.api;

From here you can call any of the main methods of the API, openForm which allows you to open a form by name and get back the data. Let's see an example:

const modalForm = app.plugins.plugins.modalforms.api;
const result = await modalForm.openForm("example-form");

The result is a special type of object that contains the data of the form. It also has some convenient methods to help you process the returned data. One of them is asFrontmatterString, which returns the data as a string that can be used in a frontmatter block. Let's see an example using Templater:

Usage with Templater

---
<%*
const modalForm = app.plugins.plugins.modalforms.api;
const result = await modalForm.openForm('example-form');
tR += result.asFrontmatterString();
-%>
---

When you insert this template in a note, it will open the form, and once you submit it, it will insert the data in the note as a frontmatter block.

Usage with QuickAdd

In order to open a form from QuickAdd capture, you need to create a capture and activate the capture format, then in the format text-area you must create a code block with the language defined as js quickadd and copy the code below:

```js quickadd
	const modalForm = app.plugins.plugins.modalforms.api;
	const result = await modalForm.openForm('example-form');
	return result.asDataviewProperties();
```

Here you have an example screenshot of how it should look like: quick capture example

Providing Default Values When Opening a Form

When opening a form you can provide default values for the form fields. This can be done by passing an object to the openForm or limitedForm methods as part of the FormOptions parameter. This object should have the same structure as the form definition, with each key corresponding to a field name and its value being the default value for that field.

Here's an example:

const values = {
    title: "My Default Title",
    description: "This is a default description.",
};

const modalForm = app.plugins.plugins.modalforms.api;
const result = await modalForm.openForm("example-form", { values: values });

In this example, the form will open with the title field pre-filled with My Default Title and the description field pre-filled with This is a default description..

Note: If a field in the default values object does not exist in the form definition, it will be ignored.

FormResult Methods

When you open a form, you get back a FormResult object. This object contains the data of the form and some methods to help you process it. This FormResult object returned by the openForm method has several methods that can be used to process the form data. Here is a brief description of each method:

asFrontmatterString()

This method returns the form data as a string that can be used in a frontmatter block. It formats the data in YAML syntax. Here is an example of how to use it:

asDataviewProperties()

This method returns the form data as a string of dataview properties. Each key-value pair in the form data is converted into a string in the format key:: value. Here is an example of how to use it:

getData()

This method returns a copy of the form data. It can be used when you need to manipulate the form data without affecting the original data.

asString(template: string)

This method returns the form data formatted as a string matching the provided template. The template is a string that can contain placeholders in the format {{key}}, which will be replaced with the corresponding value from the form data. Here is an example of how to use it in a templater template:

<%*
const modalForm = app.plugins.plugins.modalforms.api;
const result = await modalForm.openForm('example-form');
tR += result.asString('{{Name}} is {{age}} years old and his/her favorite food is {{favorite_meal}}. Family status: {{is_family}}');
-%>

Advanced usage

For more advanced usage of the FormResult methods please refer to the specific documentation of FormResult here

Define a form

Create a new form

Creating a new form is easy, you just need to open the manage forms view, either by clicking on the ribbon icon or by using the command palette (Obsidian modal form: New form). Once there, click on the + button and you will be presented with a form to create a named form definition. The form is self-explanatory, but here are some key points you need to keep in mind:

  • The name must be unique, and it will be used to identify the form when you open it from JavaScript, case-sensitive
  • The title is what you will see as a header in the modal window when you open the form
  • You will not be able to save the form unless all the fields are valid (which means they have a name and a type)

form editor/creator

Dataview integration

dataview

Inline forms

The plugin also supports inline forms, which are forms that are defined when you call the openForm method. This is useful when you want to create a form that is only used in one place and it is simple enough. However, note the format is a bit verbose for typing it manually and it is error-prone, so unless it is a very small form, you will most likely prefer to use a named form.

Here is an example of how to use it:

const modalForm = app.plugins.plugins.modalforms.api;
const result = await modalForm.openForm({
    title: "Example form",
    fields: [
        {
            name: "name",
            label: "Name",
            description: "Your name",
            input: { type: "text" },
        },
        {
            name: "age",
            label: "Age",
            description: "Your age",
            input: { type: "number" },
        },
        {
            name: "favorite_meal",
            label: "Favorite meal",
            description: "Your favorite meal",
            input: { type: "text" },
        },
        {
            name: "is_family",
            label: "Is family",
            type: "toggle",
            description: "Are you family?",
            required: true,
            input: { type: "toggle" },
        },
    ],
});

You can make it smaller by removing some of the optional fields like description or label, but I really encourage you to define them all.

Tips and tricks

Installing the plugin

You can install the plugin directly from the Obsidian plugin store or through BRAT

Installing with BRAT

  1. Install the BRAT plugin (GitHub page) and enable it.
  2. Open the command palette and run the command BRAT: Add a beta plugin for testing.
  3. Enter https://github.com/danielo515/obsidian-modal-form into the modal and press the Add Plugin button.
  4. Return to the settings and navigate to the Community plugins tab.
  5. Enable the plugin.

Manually installing the plugin

  • Copy over main.js, styles.css, manifest.json to your vault VaultFolder/.obsidian/plugins/modalForm/.

How to develop

  • Clone this repo.
  • Make sure your NodeJS is at least v16 (node --version).
  • npm i or yarn to install dependencies.
  • npm run dev to start compilation in watch mode.

Releasing new releases

  • run npm version patch, npm version minor, or npm version major after updating minAppVersion manually in manifest.json.
  • Upload the files manifest.json, main.js, styles.css as binary attachments. Note: The manifest.json file must be in two places, first the root path of your repository and also in the release.
  • Publish the release.

The command npm version whatever will bump version in manifest.json and package.json, and add the entry for the new version to versions.json

Publish docs

We use mkdocs to generate the documentation. To publish the docs, run:

./build-docs.sh

More Repositories

1

TW5-auto-publish2gh-pages

Host your tiddlywikis in GitHub pages without any git knowledge or installing any software
Shell
102
star
2

haxe-nvim

Configure NeoVim in Haxe!!! Lua externs for the neovim lua API
Haxe
32
star
3

TW5-contextPlugin

A plugin to allow preview with word highlight within searches but not limited to that
HTML
21
star
4

tiddlypouch

JavaScript
20
star
5

TW5-EncryptTiddlerPlugin

A widget that adds the hability to encrypt single tiddlers
JavaScript
18
star
6

haxe-nvim-example-plugin

Lua
13
star
7

generator-tw5-plugin

Create new plugins for tiddlywiki 5 easily
JavaScript
11
star
8

TW5-2click2edit

Plugin that adds the ability to edit tiddlers by double clicking on its body.
Shell
9
star
9

openhasp-designer

TypeScript
8
star
10

babel-fp-plugins

A playground to find the best babel-plugins for functional programming
JavaScript
7
star
11

photoprism_face_recognition

Python
7
star
12

JSONTools

A web app that provides a visual interface to interact with collections of javascript objects
JavaScript
6
star
13

TiddlyDrive

Plugin that syncs with Google apps compatible script
JavaScript
5
star
14

reason-ls

Build a simple command line utility in reason/Ocaml
Reason
5
star
15

TW5-AutoTag

JavaScript
5
star
16

tw5-pouchdb

Pouchdb library ready to be embedded into tiddlywiki
JavaScript
4
star
17

generator-hapi-swagger-es6

Yeoman generator for modern hapi servers with automatic documentation
JavaScript
4
star
18

dotfiles

My personal dotifles, whatevher that means
Lua
4
star
19

report-builder

Complex JSON reports made easy
JavaScript
4
star
20

tree-sitter-reason

JavaScript
4
star
21

gulp-tw

JavaScript
4
star
22

object-translate

Easily turn objects into other objects. Easy and composable
JavaScript
4
star
23

packages

A monorepo for managing easier all my npm packages
JavaScript
3
star
24

TW5-KeyboardSnippets

Adding functionalitys to the TW5 text widgets for faster editing such as simple key snippets
HTML
3
star
25

node-debugging-in-docker

Small exercise to learn how to debug node-js docker images. It is on Spanish
JavaScript
3
star
26

ElectronicProjectsSpreadsheet

OCaml
2
star
27

vscode-node-snippets

My favorite node snippets packed as a plugin for convenience
JavaScript
2
star
28

hammerspoon-hx

Haxe
2
star
29

TW5-searchNreplace

Search and Replace plugin for Tiddlywiki5 (tiddlywiki.com)
HTML
1
star
30

tiddlywiki5-Plugins-infoToolbar

A plugin to add extra functionality to the info toolbar within each tiddler
Shell
1
star
31

nodejs-benchmarks

A framework for easy benchmarking NodeJs code
HTML
1
star
32

old-tiddlywiki5-importPlugin

Plugin as workaround to give user more control while importing TW files
JavaScript
1
star
33

TW5-TagSearch

A plugin that lets you search based on tags in a visual way
JavaScript
1
star
34

curso-javascript-avanzado-elgc

Repositorio con los ejemplos que iremos viendo en el curso del canal
JavaScript
1
star
35

transducers

1
star
36

TW5-revealNoOffset

A small modification of the reveal widget of tiddlywiki
JavaScript
1
star
37

Columnator

Join columns of data using templates
AutoHotkey
1
star
38

Tasker-JScripts

HTML
1
star
39

ergodox-configurator

A non official layout configurator for the ergodox. It may support more layouts on the future
HTML
1
star
40

import-tools

a plugin to add more functionality to the current tiddlywiki importing mechanism
JavaScript
1
star
41

TW5-sample-plugin

A skeleton plugin to use as template for creating new plugins.
HTML
1
star
42

OctoWiki

An online application to edit your github hosted TiddlyWikis
JavaScript
1
star