Enhancement: Modal UI for Snippet Data Entry

[bwklein]

There is support for something like this for media snippets.

"frontMatter.dashboard.mediaSnippet": [
    "{{< caption \"{mediaUrl}\" \"{description}\" >}}"
  ],

This request is to extend this feature and define a template/UI for filling in variables that editors can use to define the values inserted into the snippet. It would be nice if the same syntax used for defining a taxonomy Content Type was used to define the structure/content of the UI for the snippet. Then you would need to map the inputs in the UI to placeholder variables in the snippet string/text. In the example above, {mediaUrl} and {description} would be placeholder variables that would be replaced by the input to string fields that the editor typed into the UI.

[estruyf]

If I understand you correctly, you want to have more metadata options or additional fields available for your media files. When inserting a snippet, it will ask you to fill in the missing field data. Is that correct?

There is already a dialog for adding the title, description, caption of your media. Would you want to extend this, and be able to add your own fields to it? Or would you see it a something separate, like data you add only when inserting the image into your contents?

[bwklein]

I apologize, I wasn't very clear. This is a more generic feature, that works with any shortcode snippet, to provide functionality similar to what you are already doing with media snippet insertion. Except I would be able to define the fields for data entry by the editor and would use that input to insert into the placeholder/variables of the snippet string.

[estruyf]

No reason to apologize! Just want to make sure we are on the same page. So, I'll try to rephrase this again.

You want generic snippets that you can use to insert in your content. When you add these, you want to be able to specify the field its content from a modal dialog.

If that would be the case, what would be the advantage over defining snippets in VS Code?

[bwklein]

The advantage is that I could offer the editor a UI that provides them with the choices available for particular fields, some help text, and all possible shortcode input options. It would act in a similar way to the media snippet does now, to help people pick an image file, enter some text for a caption, etc. Except these snippet templates would be built around the inputs to any shortcode I might want a user to add into the content.

[bwklein]

As an example, I have a custom figure snippet, where I allow the user to enter some additional inputs to the shortcode for styling, alignment, etc. I would want to make the 3 alignment options a 'choice' field in the UI template. I might also offer a 'size' for the image with "small", "medium", "large" and "full width" set of choices for that input. Then a 'Tailwind Classes' input string to add some additional styling classes to the image or figure elements too.
This is similar to why you have made a UI for editing front matter fields in the first place. To make it easy for editors to add the right kind of data into the file, making it easy to add new file based on a template, with all the right stuff in the front matter, based on that content type.
This is basically extending the concept for front matter into UI for shortcodes.

[estruyf]

Sold.

So what if there would be a dashboard like the media dashboard, to give an overview of all your shortcodes/snippets. Like the media insert, you could add a snippet. You select it from the dashboard and provide the fields. I can see that using myself as well.

[estruyf]

Only need to think of a way to make it easier to create those snippets, fields, and placeholders.

[bwklein]

Yeah, something like you do now with Media, or maybe a selection list with a Name and short description to click on or a simple dropdown list with the name of each snippet.

I think that a developer would build the shortcode file in the layout and define by name or position what inputs they expect coming into it.
They would then define a structure similar to a content type now, with a set of input name, field type, type options and title for the label. The 'name' is the same as the placeholder string in the snippet for replacement with the value entered into the UI.
Finally, they would define the snippet string, where there is a placeholder for each named input in a format that is easy to parse/replace with the entered value.

Then, all defined snippets are listed (somehow) to the editor, when one is selected the UI pops up with the defined inputs for that snippet, the user types, selects, toggles, all the things in the UI and clicks "Insert Snippet" and in the cursor position of the file they are editing the snippet string is inserted with the placeholders replaced by entered values.

It's a thing of beauty. :D

[zivbk1]

@estruyf this seems to be a perfect use case of the new field groups feature. You could define a field group for a snippet along with a string that includes named placeholders for where the field group data is inserted into the string. Then when the snippet input is confirmed it inserts the snippet string into the document at the cursor location.

[estruyf]

Right now I took the VS Code approach but started to think it might be better to go for a templating engine like https://mustache.github.io

Snippets look like this at the moment:

"frontMatter.content.snippets": {
    "Highlight (single)": {
      "description": "Creates a code highlighting box",
      "body": [
        "{{< highlight ${type|html,css,typescript|} \"linenos=table,noclasses=false\" >}}",
        "  ${FM_TEXT_selection:FM_SELECTED_TEXT}",
        "{{< / highlight >}}"
      ]
    }
  }

It is simple to use, but maybe a bit too simple that it becomes complex when including other field types. Thinking of changing the placeholder logic as follows:

"frontMatter.content.snippets": {
  "Highlight (single)": {
    "description": "Creates a code highlighting box",
    "body": [
      "{{< highlight {{type}} \"linenos=table,noclasses=false\" >}}",
      "  {{selection}}",
      "{{< / highlight >}}"
    ],
	  "fields": [
      {
        "name": "type",
        "label": "Type",
        "type": "select",
        "options": ["html","css","typescript"],
        "default": "html"
      },
      {
        "name": "selection",
        "label": "Selection",
        "type": "text",
        "default": "FM_SELECTED_TEXT"
      }
	  ]
  }
}

By default, the placeholders/variables found in the text will be shown just as input fields when not defined in the fields property. Think this change makes it more future proof and later on we can integrate it with the group fields as well.

[bwklein]

I really like the second proposal for placeholder logic, seems pretty clean.

[estruyf]

Snippet properties:

• Description
• Body
• Fields
• Opening tags (optional - default: [[)
• Closing tags (optional - default: ]])

Opening and closing tags are optional and would be useful for snippet using a similar syntax. Like for instance Hugo also uses {{ and }} for their templates.

[bwklein]

Here is an example of some Svelte components I would be using.

< YT v={watchID} >

< Figure image={imageURL} caption={caption} title={title} >

Where the placeholders are in curly braces.

Would you need to specify the opening and closing tags? Since they would already be in the body?

[estruyf]

Yes, they would become:

< YT v={[[watchID]]} >

< Figure image={[[imageURL]]} caption={[[caption]]} title={[[title]]} >

[bwklein]

Ok, so I don't actually need the curly braces, so would I write them as follows?

< YT v=[[watchID]] >

< Figure image=[[imageURL]] caption=[[caption]] title=[[title]] >

[estruyf]

Oh, yeah, thought you {} were required, but if that is not the case, you can remove these.

[estruyf]

Logic has been updated, the docs as well: https://beta.frontmatter.codes/docs/snippets

[zivbk1]

Is there a good method to pick a Snippet to insert into the text when editing markdown?

[estruyf]

Two ways:

• At the top right, you will have the snippet action in the WYSIWYG controls

• Via the command palette: Insert a snippet into your content

You can also configure the last one to a keyboard binding to access it quicker.

[bwklein]

Wonderful!