Ability to insert variables, similar to suggestions

[moltar]

Is your feature request related to a problem? Please describe.

Ability to insert pre-defined "variables" into the text.

E.g. user could type "today is {{ today }}" or "today is $today".

The editor would provide a list of suggested variables that are pre-defined.

The editor would also decorate these variables somehow once they are inserted.

The editor would allow to backspace and erase them.

Describe the solution you'd like

Similar to how suggestions work. But ability to use multiple characters, I guess. Like "{{" to begin suggestions.

Describe alternatives you've considered

N/A

Additional context

Integromat has a similar looking feature, but does not provide a suggest dropdown when typing. Can only use a mouse. http://take.ms/HSf3l

Zapier also has a similar one http://take.ms/NhODH

---

Thanks!

[moltar]

I think I have figured out a work-around:

https://codesandbox.io/embed/vue-template-y0o5z (see HelloWorld.vue)

Notably:

.mention::after {
  content: "}}";
}

and

          new Mention({
            matcher: {
              char: "{{"
            },

Seems to work!

If you have any better suggestions, please let me know.

If you think this is the best way, then please feel free to close this issue.

Thanks!

[asseti6]

@moltar this is completely possible similiar to how you are using the Mention class already by defining your own custom node and plugin or use the suggestions plugin already available. As a working example your node would look something like:

import { Node } from "tiptap";
import { replaceText } from "tiptap-commands";
import VariableSuggestionPlugin from "../plugins/CustomSuggestions";

export default class Variables extends Node {
  get name() {
    return "variable";
  }

  get defaultOptions() {
    return {
      matcher: {
        char: "%%",
        allowSpaces: false,
        startOfLine: false
      },
      variableClass: "variable",
      suggestionClass: "variable-suggestion"
    };
  }

  get schema() {
    return {
      attrs: {
        id: {},
        label: {}
      },
      group: "inline",
      inline: true,
      selectable: false,
      atom: true,
      toDOM: node => [
        "span",
        {
          class: this.options.variableClass,
          "data-variable-id": node.attrs.id
        },
        `${this.options.matcher.char}${node.attrs.label}`
      ],
      parseDOM: [
        {
          tag: "span[data-variable-id]",
          getAttrs: dom => {
            const id = dom.getAttribute("data-variable-id");
            const label = dom.innerText
              .split(this.options.matcher.char)
              .join("");
            return { id, label };
          }
        }
      ]
    };
  }

  commands({ schema }) {
    return attrs => replaceText(null, schema.nodes[this.name], attrs);
  }

  get plugins() {
    return [
      VariableSuggestionPlugin({
        command: ({ range, attrs, schema }) =>
          replaceText(range, schema.nodes[this.name], attrs),
        appendText: " ",
        matcher: this.options.matcher,
        items: this.options.items,
        onEnter: this.options.onEnter,
        onChange: this.options.onChange,
        onExit: this.options.onExit,
        onKeyDown: this.options.onKeyDown,
        onFilter: this.options.onFilter,
        suggestionClass: this.options.suggestionClass
      })
    ];
  }
}

Further if you want true variable previews you can find the tags in the html output and replace them (adding a tooltip with the original variable name) if you want to get a touch more complex. We have added a click event to that tooltip to allow it to be modified again by setting the replacement value to something a bit more complex. As an example of basic "variable preview":

this.editor.setContent(this.editor.getHTML().replace(new RegExp(`<span class=("|"([^"]*))variable("|([^"]*)").*?([^<]+)%%${variable.name}</span>`, "g"), variable.value));

For the Custom Plugin to support the class you could use the Mentions Suggestion Plugin as a base and slightly modify. Something to the following effect:

import { Plugin, PluginKey } from "prosemirror-state";
import { Decoration, DecorationSet } from "prosemirror-view";
import { insertText } from "tiptap-commands";

// Create a matcher that matches when a specific character is typed. Useful for @mentions and #tags.
function triggerCharacter({
  char = "%%",
  allowSpaces = false,
  startOfLine = false
}) {
  return $position => {
    // Matching expressions used for later
    const escapedChar = `\\${char}`;
    const suffix = new RegExp(`\\s${escapedChar}$`);
    const prefix = startOfLine ? "^" : "";
    const regexp = allowSpaces
      ? new RegExp(`${prefix}${escapedChar}.*?(?=\\s${escapedChar}|$)`, "gm")
      : new RegExp(`${prefix}(?:^)?${escapedChar}[^\\s${escapedChar}]*`, "gm");

    // Lookup the boundaries of the current node
    const textFrom = $position.before();
    const textTo = $position.end();
    const text = $position.doc.textBetween(textFrom, textTo, "\0", "\0");

    let match = regexp.exec(text);
    let position;

    while (match !== null) {
      // JavaScript doesn't have lookbehinds; this hacks a check that first character is " "
      // or the line beginning
      const matchPrefix = match.input.slice(
        Math.max(0, match.index - 1),
        match.index
      );

      if (/^[\s\0]?$/.test(matchPrefix)) {
        // The absolute position of the match in the document
        const from = match.index + $position.start();
        let to = from + match[0].length;

        // Edge case handling; if spaces are allowed and we're directly in between
        // two triggers
        if (allowSpaces && suffix.test(text.slice(to - 1, to + 1))) {
          match[0] += " ";
          to += 1;
        }

        // If the $position is located within the matched substring, return that range
        if (from < $position.pos && to >= $position.pos) {
          position = {
            range: {
              from,
              to
            },
            query: match[0].slice(char.length),
            text: match[0]
          };
        }
      }

      match = regexp.exec(text);
    }

    return position;
  };
}

export default function VariableSuggestionPlugin({
  matcher = {
    char: "%%",
    allowSpaces: false,
    startOfLine: false
  },
  appendText = null,
  suggestionClass = "suggestion",
  command = () => false,
  items = [],
  onEnter = () => false,
  onChange = () => false,
  onExit = () => false,
  onKeyDown = () => false,
  onFilter = (searchItems, query) => {
    if (!query) {
      return searchItems;
    }

    return searchItems.filter(item =>
      JSON.stringify(item)
        .toLowerCase()
        .includes(query.toLowerCase())
    );
  }
}) {
  return new Plugin({
    key: new PluginKey("custom-suggestions"),

    view() {
      return {
        update: (view, prevState) => {
          const prev = this.key.getState(prevState);
          const next = this.key.getState(view.state);

          // See how the state changed
          const moved =
            prev.active && next.active && prev.range.from !== next.range.from;
          const started = !prev.active && next.active;
          const stopped = prev.active && !next.active;
          const changed = !started && !stopped && prev.query !== next.query;
          const handleStart = started || moved;
          const handleChange = changed && !moved;
          const handleExit = stopped || moved;

          // Cancel when suggestion isn't active
          if (!handleStart && !handleChange && !handleExit) {
            return;
          }

          const state = handleExit ? prev : next;
          const decorationNode = document.querySelector(
            `[data-decoration-id="${state.decorationId}"]`
          );

          // build a virtual node for popper.js or tippy.js
          // this can be used for building popups without a DOM node
          const virtualNode = decorationNode
            ? {
                getBoundingClientRect() {
                  return decorationNode.getBoundingClientRect();
                },
                clientWidth: decorationNode.clientWidth,
                clientHeight: decorationNode.clientHeight
              }
            : null;

          const props = {
            view,
            range: state.range,
            query: state.query,
            text: state.text,
            decorationNode,
            virtualNode,
            items: onFilter(
              Array.isArray(items) ? items : items(),
              state.query
            ),
            command: ({ range, attrs }) => {
              command({
                range,
                attrs,
                schema: view.state.schema
              })(view.state, view.dispatch, view);

              if (appendText) {
                insertText(appendText)(view.state, view.dispatch, view);
              }
            }
          };

          // Trigger the hooks when necessary
          if (handleExit) {
            onExit(props);
          }

          if (handleChange) {
            onChange(props);
          }

          if (handleStart) {
            onEnter(props);
          }
        }
      };
    },

    state: {
      // Initialize the plugin's internal state.
      init() {
        return {
          active: false,
          range: {},
          query: null,
          text: null
        };
      },

      // Apply changes to the plugin state from a view transaction.
      apply(tr, prev) {
        const { selection } = tr;
        const next = { ...prev };

        // We can only be suggesting if there is no selection
        if (selection.from === selection.to) {
          // Reset active state if we just left the previous suggestion range
          if (
            selection.from < prev.range.from ||
            selection.from > prev.range.to
          ) {
            next.active = false;
          }

          // Try to match against where our cursor currently is
          const $position = selection.$from;
          const match = triggerCharacter(matcher)($position);
          const decorationId = (Math.random() + 1).toString(36).substr(2, 5);

          // If we found a match, update the current state to show it
          if (match) {
            next.active = true;
            next.decorationId = prev.decorationId
              ? prev.decorationId
              : decorationId;
            next.range = match.range;
            next.query = match.query;
            next.text = match.text;
          } else {
            next.active = false;
          }
        } else {
          next.active = false;
        }

        // Make sure to empty the range if suggestion is inactive
        if (!next.active) {
          next.decorationId = null;
          next.range = {};
          next.query = null;
          next.text = null;
        }

        return next;
      }
    },

    props: {
      // Call the keydown hook if suggestion is active.
      handleKeyDown(view, event) {
        const { active, range } = this.getState(view.state);

        if (!active) return false;

        return onKeyDown({ view, event, range });
      },

      // Setup decorator on the currently active suggestion.
      decorations(editorState) {
        const { active, range, decorationId } = this.getState(editorState);

        if (!active) return null;

        return DecorationSet.create(editorState.doc, [
          Decoration.inline(range.from, range.to, {
            nodeName: "span",
            class: suggestionClass,
            "data-decoration-id": decorationId
          })
        ]);
      }
    }
  });
}

Hope that gives you or anyone else some further direction.

[softwareguy74]

I have opened a feature request for something like this. I would like to also suggest this be extended to be able to drag and drop from an arbitrary source component (such as a TreeView node, for example) and drop into specific location in text and have it result in a predefined "Suggestion". This suggestion could then be rearranged by dragging it around with the mouse or deleted by clicking an "X" icon in it.

[asseti6]

@softwareguy74 suggestions in the above example can be set to draggable as is within the document. As for dragging from outside the editor itself, we currently support that in our application by having the dropped variable simply insert the proper text into the editor.

[douglasg14b]

Oh boy that's quite a bit!

Would be great to see this supported directly, so it can be simply configured.

[hendrikgaffo]

@asseti6 I have tried to get it working with your solution, but unfortunately without success. I know it has been quite a while since you replied to this issue, but could you give us a CodeSandbox or Repo URL with a working example? I would really appreciate it.

[bbbford]

Thanks for the guidance @asseti6 !

I have successfully implemented a variable solution where the user selects the variable by name, and tiptap displays the variable value inside of the document. The variable display within the document is reactive.

For those wanting to display the value in the document, I would suggest - rather than doing a replace as below:

this.editor.setContent(this.editor.getHTML().replace(new RegExp(<span class=("|"([^"]))variable("|([^"])").*?([^<]+)%%${variable.name}, "g"), variable.value));

Use your vuex store instead:

  // return a vue component
  // this can be an object or an imported component
  get view() {
    return {
      // there are some props available
      // `node` is a Prosemirror Node Object
      // `updateAttrs` is a function to update attributes defined in `schema`
      // `view` is the ProseMirror view instance
      // `options` is an array of your extension options
      // `selected` is a boolean which is true when selected
      // `editor` is a reference to the TipTap editor instance
      // `getPos` is a function to retrieve the start position of the node
      // `decorations` is an array of decorations around the node
      props: [ 'node', 'updateAttrs', 'view', 'options' ],
      computed: {
        label: {
          get() {
             // Get your label from vuex store here
          },
          set(label) {
            this.updateAttrs({
              label: label
            });
          }
        },
      },
      template: `
          <span :class="options.variableClass" :data-variable-id="node.attrs.id">{{label}}</span>
      `
    }

[hendrikgaffo]

@bbbford Very neat that you managed to get it working. Would you mind sharing a repo with us? That would be very, very helpful.

[hanspagel]

Thanks for the suggestion! And thanks for the code snippets. It’s added to the list of community extensions in #819 and we consider to add it to the core in tiptap v2 at some point. I’m closing this here for now. ✌️

[andrews05]

@hanspagel Is this still under consideration for v2 core?

[EthosLuke]

Does anyone have a working example using Livewire and/or AlpineJS?

[andrews05]

TinyMCE has an excellent Merge Tags feature: https://www.tiny.cloud/docs/tinymce/6/mergetags/
Note that the input/output works with the raw text form of the variable without requiring spans etc, so you don't have to do any transformations yourself like what @bbbford showed.
This is exactly what I'd want for TipTap - afaik it's not currently possible for an extension to achieve this?

[AlonMiz]

TinyMCE has an excellent Merge Tags feature: https://www.tiny.cloud/docs/tinymce/6/mergetags/ Note that the input/output works with the raw text form of the variable without requiring spans etc, so you don't have to do any transformations yourself like what @bbbford showed. This is exactly what I'd want for TipTap - afaik it's not currently possible for an extension to achieve this?

i have the exact same requirement as the mergetags. we would probably have to move to TinyMCE just for this. really liked tiptap though :/

[asseti6]

I am going to need this same feature again for a new project. I'll update the original code as a node extension along with @bbbford's improvements and share it with the community. @hanspagel what the best way to share that for review and for the community?

It will be towards the end of the month before I get to it.

[Acetyld]

@asseti6 any progres =) <3

[aehlke]

@hanspagel is there a way to recommend this for consideration again? thanks... sorry for the ping

[geekyayush]

Hey @asseti6 , sorry for pinging. Have you released the code for it?

[joaomirandas]

Hey folks,

I spend too much time creating this extension, thats an must have for a kind of application that i made to tiptap, after so many hours i decided to share what i've created. cheers 🚀

@talqui-oss/tiptap-extension-variable

[Haraldson]

@joaomirandas Getting atom nodes to appear in the editor content isn’t really that hard – did you solve how to define the data source/values and get the values reflected?

[Roberson-Andrade]

The best way I found to write variables and reflect the corresponding values was with node views.

Basically I extended the mention extension passing my React component (could be in vue also, check the docs):

export const VariablesExtension = MentionExtension.extend({
  addNodeView() {
    return ReactNodeViewRenderer(Variable);
  },
  parseHTML() {
    return [
      {
        tag: "variable-component",
      },
    ];
  },
  renderHTML({ HTMLAttributes }) {
    return ["variable-component", mergeAttributes(HTMLAttributes)];
  },
});

I also get the variables inside the VariableList to avoid using the items from suggestion utils extension:

export const VariablesList = forwardRef<
  ReturnType<NonNullable<SuggestionOptions["render"]>>,
  SuggestionProps<VariableOption>
>(({ command }, ref) => {
  const [selectedIndex, setSelectedIndex] = useState(0);
  const { data, isLoading } = useQuery({
    queryKey: ["variable-options"],
    queryFn: getVariables,
  });

// component code

Finally, through a ReactContext I provided the respective values for the variables and also controlled the parsing:

// Provider
export function VariablesContextProvider({
  children,
  parseVariables,
}: {
  children: React.ReactNode;
  parseVariables: boolean;
}) {
  const { data: values } = useQuery({
    queryKey: ["variable-values"],
    queryFn: getVariablesValues,
  });

  return (
    <VariablesContext.Provider value={{ values, parseVariables }}>
      {children}
    </VariablesContext.Provider>
  );

// VariableNode
export function Variable(props: NodeViewProps) {
  const { parseVariables, values } = useVariablesContext();
  return (
    <NodeViewWrapper className="inline w-fit">
      <span
        className={cn(
          "rounded bg-neutral-700 px-1 py-0.5 text-custom-primary-100"
        )}
      >
        {parseVariables
          ? values?.find((value) => value.id === props.node.attrs.id)?.value ??
            `variable not found`
          : `@${props.node.attrs.label}`}
      </span>
    </NodeViewWrapper>
  );
}

The result:
tiptap-variables.webm

Here is the working example, I hope it helps someone.

[phillipmohr]

As someone being new to TipTap I found this very hard to implement gave up. Would be awesome if this would become an official extension.

[aoleksyshyn-spscommerce]

Hello, has anyone successfully implemented extension for merge tags?

[Lau08]

This worked for me, thanks to all your ideas:

import { ReactRenderer } from "@tiptap/react";
import tippy from "tippy.js";
import { MentionList } from "./MentionList.jsx";

const getFilteredMentions = (query, listOfPromptVariables) => {
  return listOfPromptVariables
    .filter((item) => item.toLowerCase().startsWith(query.toLowerCase()))
    .slice(0, 5);
};

const suggestion = ({ listOfPromptVariables }) => ({
  char: "{{",
  allowedPrefixes: null,
  decorationClass: "variable-suggestion",
  items: ({ query }) => {
    return new Promise((resolve) => {
      setTimeout(() => {
        resolve(getFilteredMentions(query, listOfPromptVariables));
      }, 1000);
    });
  },

  render: () => {
    let reactRenderer;
    let popup;

    return {
      onStart: (props) => {
        reactRenderer = new ReactRenderer(MentionList, {
          props,
          editor: props.editor,
        });

        popup = tippy("body", {
          getReferenceClientRect: props.clientRect,
          appendTo: () => document.body,
          content: reactRenderer.element,
          showOnCreate: true,
          interactive: true,
          trigger: "manual",
          placement: "bottom-start",
        });
      },

      onUpdate(props) {
        reactRenderer.updateProps(props);

        popup[0].setProps({
          getReferenceClientRect: props.clientRect,
        });
      },

      onKeyDown(props) {
        if (props.event.key === "Escape") {
          popup[0].hide();

          return true;
        }

        return reactRenderer.ref?.onKeyDown(props);
      },

      onExit() {
        popup[0].destroy();
        reactRenderer.destroy();
      },
    };
  },
});

export default suggestion;

[Lau08]

import React, { useEffect } from "react";
import { useEditor, EditorContent } from "@tiptap/react";
import Document from "@tiptap/extension-document";
import Paragraph from "@tiptap/extension-paragraph";
import Text from "@tiptap/extension-text";
import Mention from "@tiptap/extension-mention";
import suggestion from "./EditorUtils/suggestion";

export default ({
  listOfPromptVariables,
  editorContent,
  onChangeContent,
}) => {
  const editorPrompt = useEditor({
    editorProps: {
      attributes: {
        class: "focus:outline-none",
      },
    },
    extensions: [
      Document,
      Paragraph,
      Text,
      Mention.configure({
        HTMLAttributes: {
          class: "variables",
        },
        suggestion: suggestion({ listOfPromptVariables }),
      }),
    ],
    content: editorContent,
    onUpdate: ({ editor }) => {
      const content = editor.getText();
      onChangeContent(content);
    },
  });

  useEffect(() => {
    if (!editorPrompt) return;
    let { from, to } = editor?.state?.selection;
    editorPrompt?.commands.setContent(editorContent, false, {
      preserveWhitespace: "full",
    });
    editorPrompt.commands.setTextSelection({ from, to });
  }, [editorPrompt, editorContent]);

  return (
    <EditorContent
      editor={editorPrompt}
      className="h-full"
    />
  );
};

[jon-spaeth]

Was able to generate something for this with v0.dev

It generated the tiptap plugin and everything. It uses {{variable_name}} to define variables

https://v0.dev/chat/b/4QZUpwA

[aoleksyshyn-spscommerce]

@Lau08 thanks for sharing your solution!
Could you please also share MentionList.jsx to see how it all works together?

[Lau08]

@Lau08 thanks for sharing your solution! Could you please also share MentionList.jsx to see how it all works together?

Here is the MentionList.jsx:

import React, {
  useState,
  useEffect,
  forwardRef,
  useImperativeHandle,
} from "react";

export const MentionList = forwardRef((props, ref) => {
  const [selectedIndex, setSelectedIndex] = useState(0);

  const selectItem = (index) => {
    const item = props.items[index];

    if (item) {
      props.command({ id: item + "}}" });
    }
  };

  const upHandler = () => {
    setSelectedIndex(
      (selectedIndex + props.items.length - 1) % props.items.length
    );
  };

  const downHandler = () => {
    setSelectedIndex((selectedIndex + 1) % props.items.length);
  };

  const enterHandler = () => {
    selectItem(selectedIndex);
  };

  useEffect(() => setSelectedIndex(0), [props.items]);

  useImperativeHandle(ref, () => ({
    onKeyDown: ({ event }) => {
      if (event.key === "ArrowUp") {
        upHandler();
        return true;
      }

      if (event.key === "ArrowDown") {
        downHandler();
        return true;
      }

      if (event.key === "Enter") {
        enterHandler();
        return true;
      }

      return false;
    },
  }));

  return (
    <>
      {props.items.length && (
        <div className="items">
          {props.items.map((item, index) => (
            <button
              className={`item ${index === selectedIndex ? "is-selected" : ""}`}
              key={index}
              onClick={() => selectItem(index)}
            >
              {item}
            </button>
          ))}
          : <></>
        </div>
      )}
    </>
  );
});

export default MentionList;