mirror of
https://github.com/estruyf/vscode-front-matter.git
synced 2026-11-04 01:22:21 +01:00
Enhancement: New field type for 'list' or array of sub-collections. #139
Assignees
adam (Adam Wojcieszonek)
Clear assignees
adam (Adam Wojcieszonek)
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: adam/vscode-front-matter#139
Reference in new issue
Block a user
With 'Page Sections' or 'Blocks' in front matter data, there needs to be a way to define section/block templates and then manage a list/array of them in front matter.
To add, remove, change order of elements in the list and edit the front matter data in the block elements.
For an example see: https://forestry.io/blog/sawmill-layout-composer-for-hugo-and-forestry/#hugo-example
For a working example of this system in action see:
Website - https://psrfcu.org/
Repo - https://gitlab.com/psrfcu/psrfcu-2019/-/blob/master/content/_index.md
Thanks @bwklein for the suggestion! The repo link you shared ends up on a 404 page. Would you be able to check the URL again? Once I can see how you are using it, I can understand the logic a bit better.
Note, that with content files like this, there usually isn't any {{.Content}} in the body of the markdown file. Everything is defined in front matter variables to populate variables in the partials used to render the data into the page block.
It makes the site more like a traditional CMS where the information for the design components (blocks) is stored in the front matter data model and not all in markdown/html within the body of the content file.
Thank you for providing a sample! This makes it clear to me. As of what I can see this is specific to Forestry. I like the idea, but also think it's a bit abusing the front matter. Shortcodes would be a cleaner way and probably makes it better suitable for other SSGs.
Just to understand a couple of things. These page sections, where do you define these? I assume these are custom things you need to configure before they will be able to be used. Is that true?
Yes, essentially you make design elements or blocks in your partials directory. Then you have a layout type that reads through the front matter and for each 'page_section' it calls the appropriate 'block' and passes the data from that page_section array element into the partial. All of that would need to be setup first, to define what inputs are required for that block partial.
You also need to define the set of inputs for a particular block and use that for editing the data in the array of page_sections/blocks. In Forestry this is done with their Front Matter Templates, in Cloud Cannon this is done with array structures, see the attached file starting at line 80 for the Cloud Cannon array structures that match with the file I pasted above.
cloudcannon.toml.zip
This approach works great in the situation where you want to reuse design elements on different pages and the editor can move them around and fill in the required information for each block as they 'assemble' the page from top to bottom.
In the site I posted the file for above, there are 19 different blocks that someone could build a page out of.
You are correct shortcodes could work too, but would make it difficult to reopen the editor for the block to make changes to an existing shortcode, unless you had a parser that would read the shortcode string and populate the snippet insertion UI with the values from the shortcode string. It seems like it would be a bit easier to define an array field type and a mini 'content type' for each 'block' that could be added into the array.
I think of shortcodes as a simple way to insert a smaller design element (figure, table, video, tweet) into the body of a larger Markdown file. Where this 'blocks' system is a way of composing entire pages from top to bottom, where each layer in the stack has a specific set of inputs to that specific layer.
One thing to note is that shortcodes will NOT work within the content of a layer field. So you will see in my example file code that there are 'content_markdown' fields for some blocks. If you put a shortcode in there it won't render the shortcode result into the page, there will just be a shortcode string in the content of that block. You can 'markdownify' the content_markdown into HTML, but the shortcodes are ignored. There is an existing Hugo project issue to resolve this and allow for shortcodes in frontmatter text to be rendered.
@estruyf this has become a blocker for me. I can't use it on sites where I have arrays of data in Front Matter. Do you have any suggestions for a workaround, or ideas on how to implement this in FM?
@zivbk1 added it to the board for the next release. At the moment there is no workaround for it. Think it is best to start with #197
@zivbk1 does #197 get this supported as well? Or are there missing pieces still?
I think it is closer, but the missing piece is a field type in a template where you can choose from a set of defined data structures to add them into an array in the front matter. Do the examples above help or should I setup a more simple example/test for this feature?
My two cents - I use Forestry Blocks for a two client sites (Hugo) and one personal(Pelican) to allow the users a familiar front end to contribute content and build pages. Their "Blocks" feature is a game changer for changing pages. I thought about asking for this feature also, but I could not even think of how it would take advantage of the existing FM UI without a modal/dialog box and my Pelican sites don't use shortcodes, so I did not propose them.
If it can happen that would be cool if not I might just make project level snippets.
Project level snippets is going to be the next major improvement for Front Matter, this is certain
There needs to be a benefit of using these over what VS Code provides by default. We're thinking about:
One thing that would make it great, is to have a way to get easily update the snippets that are already defined in the content.
About the list field, I've been thinking of using the same data field schema (JSON schema) which is used in the new data view.
@estruyf yes that are nice features.
i am still not familiar with json and the scheme technics. Hopefully this project may clarify some aspects of using json and json schemes.
i am thinking of the Specifications that are announced on the Specification documents on the JSON Schema org.
Versioning and looking forward is nice, but if you are out of date it may be getting complicated to be up to date. telling it from a perspective of an unemployed who stucks learning after some issues.
Which schema is the right one? Should this be hardcoded somehow, or would/should be let over to the developer?
i am getting overhelmed trying to find ressources for a clear explanation for json schemes, it looks realy fluent. but, it is a nice solution, but for me not clear enough right now.
also yaml is explaining itself as a clear solution, binding both together with a clean solution might be helpfull.
yaml to json schema and json data, and also json schema and json data to yaml? decide :-) well i need some vacation :-)
@wemasoe the version of the JSON schema does only matter when you are going to create really complicated data types. If you only need a couple of data fields, the schema is "pretty" easy to understand. There is always a trade-off with each road picked or decision.
The same goes for YAML, it is easy to understand, but this is just the data representation. When you would create a YAML schema to define the data structure, it would also mean you need to think it through a bit and do some trial and error.
Another reason why JSON Schema has been taken is that VS Code its settings are JSON driven and this keeps it all aligned.
Future
If we get more contributors on board, or if I manage to make more time available, one of the ideas that are on the backlog is to create a content type/settings dashboard (#129). This could become a drag and drop kind functionality to create data types and content types. Which eventually might make it easier for any that is not familiar with it.
step by step, everything is going to be good
i have to say the vscode extension Front Matter is a nice project, again, again, again.
@estruyf does this help clarify the need or should I provide a better example?
I have begun setting up a Hugo starter that uses this method of page building. https://gitlab.com/zivbk1/hugostarter
You can see in that project that there are already 2 'blocks' that a person can use to build a page.
https://gitlab.com/zivbk1/hugostarter/-/tree/main/layouts/partials/blocks
You can see here the code that is used to take the frontmatter of a page and call the correct block partial into place from top to bottom of the page. https://gitlab.com/zivbk1/hugostarter/-/blob/main/layouts/_default/page.html
Finally, you can see in this file where both blocks are called into the page from the
page_sectionsarray.https://gitlab.com/zivbk1/hugostarter/-/blob/main/content/_index.md
Here is an example of the definition of that 'page' content type. Where there are two choices (for brevity) that can be 'added' into the
page_sectionsfront matter array of a 'page' content type.In this context, any 'icon' defined would be pulled from something like https://fonts.google.com/icons?selected=Material+Icons
After building that data structure, it seems like it would be nice to define choice arrays somewhere else in the config file that can be reused by referring to them by name. Like a background color and text color set of options that can be used in different choice fields to keep things DRY.
To add to my comment above. It would be nice to see the list of page sections in the UI in an expandable accordion or something like that, where the order of the array can be changed and then edited in the expanded accordion space below the heading or maybe an editing modal that opens for that specific data item in the array. It would also be good to identify what field in the block you want to show in the stacked list of page_sections, similar to "labelField" in the data file definition. This is where it would be nice to just show the icon and then the text for the "labelField".
A lot of what I am talking about seems very similar to how the data file editor works now. Maybe use a similar UI with the stack of sections similar to the array of data items in a data file, and a very similar order and editing UI for those sections.
Still work in progress, but this is what the new collection data field looks like:
Style changes + some fixes have been added. Just committed the first version of the new control.
In order to use it, you'll need to define the field in your content type as follows:
In the
frontMatter.data.types, you can define your data type to use for the collection.Can "dataType": "page_sections2" be set up as a list of data types that can be added into the Record set?
In most use cases there would be different 'blocks' or data structures that would be added to the list of records. Where in your example 'Record 1' would be one data type, 'Record 2' would be another, and so on.
Also, would there be an ability to reorder the list, to put Record 3 above Record 1?
This is some example frontmatter that I would want to make work.
Where the first 'block' or record in the array has a data structure that includes the fields,
block,heading_markdown,background_choice,text_choiceand a second data type that only contains the fieldblockset to the default value of 'content'.If it can be defined in a JSON schema, it will be possible, but having different data types, loaded in the data collection field is not “yet” possible.
Technically it’s possible, I first focused on the main collection functionality and getting the fields right
Been thinking, so if the dataType can contain multiple data types, we could for instance show first a dropdown that allows you to select the type. Once you choose the type, it will show the additional data type's fields.
In order for this to work, we need to have an
idfield that corresponds to the data type you picked. Otherwise, it would be guessing which one you took. In your case, it isblock, could we change it totype? That way it would be a bit more generic.FWIW - In my forestry setups I use
templateand it works, so I don't think using type will be an issue. A generic term is probably the best way to go.Thanks for the feedback! Have been coding during my flight. Will commit the changes later.
Changed it to data blocks and block types. When configuring, you can select one type or many. Once you pick many, you'll need select the type to use and add the data.
Hope it will make sense.
This makes perfect sense to me.
The field will need to be configured as follows:
or
I'm going to try it today! 🙂
I'm trying it out-ish, but I think I need a primer. :-(
@apowell656 you will need two things:
frontMatter.data.typessettingsblockfield definedfrontMatter.data.types - setting
frontMatter.taxonomy.contentTypes - setting
@estruyf that put me on the right track. I looked into the documentation to get me across the finish line, but I think I am missing something. Do I need to create a data.type for each "block"/template? I tried changing the template to block in the page_sections with the same result.
@apowell656 yes, you'll have to specify what your block looks like, otherwise, it is a bit hard to render the form.
To compare it to Forestry:
I am getting an "Error loading field" error when trying to use the 'choice' field type in a block the data type definition.
Also, is it possible to use the "default" and "hidden" properties for a particular field?
For example, to always set
blockType: heroin a page_section block.I don't want the editor to change that field and break the page.
NOTE: I get "Error loading field" now if I add these.
@zivbk1 that is because it is a JSON schema and the
typesneed to be valid JSON known types:string, number, boolean, object, array. Custom types are not "yet" supported. It is doable to create custom types, but it means that there need to be custom renderers created for each new type. We probably need image and DateTime support as well.In case of the choices, you can use the following:
It might be good to not show the 'blockType' field in a page_section at all. I can't think of a use case where someone would want to edit that. If you want to change the blockType, then just add another block to the list of the correct type and delete the current one that is the wrong type.
I was just about to ask for that. 😄
Basically, anything you can do in the frontmatter UI, you could do within a block editor. Same field types, UI and functions.
Yes, this is supported, but you should not be doing it for the
blockTypefield, as that is automatically done by the extension.So, once a block has been created, you would only be able to move it or delete it?
Okay, I like my tests. Final question is it possible to nest an array? I have a template that has nested paragraphs (about-section) I am mentally halfway paying attention D@&n Super Bowl.
That is indeed what is needed. Also thinking about another option to extend the
fieldfield type. Right now it supports to only specified sub-fields, but what if we extend the field to allow field-bundle choices.Maybe this
blockfield, would better become acollectionfield, like how I initially had it in mind. As it allows you to reuse the data types from your data files/folders.The
blockfield, becomes a field type that allows you to do the same as what is defined above, but instead of specifying a data type, you specify afield block.field blockwould be a new setting, that comes with an ID and fields (all the fields from Front Matter are supported).This might be the best option after all. I might have been overthinking it due to the discussion we had about the file data/folders previously.
I actually love this new direction and it is closer to what I originally had in mind too.
I really just want a way to define 'blocks' (a configured selection of fields) and then have a way of picking from the defined set of blocks and adding them into an array ('page_sections' as an example of the array/collection name).
Once in the array, I can edit, move its position in the collection and delete them from the collection.
Also, it would be nice to specify a field in the
field blockto use as the text for the item in the list of blocks that have been added to the array. So the 'Title' of thefield_blockmight be 'Hero Banner' as the label for selecting the correct block from the list. Then there is a 'heading' field in theblockthat you would like to see in the label for the block in the collection.This way you can determine which 'hero' in the
page_sectionscollection is the one that has the text you want to edit.Yes, you can edit the contents of the block, change the order in the collection and delete it. I just don't want to be able to modify the block identification field (whatever it is called). Because that field is used to determine the 'field_block' template to use and determine the Hugo partial to render that section in the page. All of the other fields in the block are editable.
All - would anyone be willing to share a sample of usage?
Here is a super basic demo. Where the main index page uses blocks.
https://gitlab.com/zivbk1/hugostarter
@apowell656 @zivbk1 the
blockfield will now be thejsonfield.In the example of @zivbk1 - https://gitlab.com/zivbk1/hugostarter/-/blob/main/frontmatter.json#L55-63
You'll have to change
typetojson, andblockTypetodataType.Currently, the new
blockfield is in development.@estruyf thank you. I'll update this demo project when blocks are ready. What use case do you anticipate for the json type?
@estruyf and @zivbk1 thanks for links. I have validated my JSON to use nested content (my fields without nested content are working well), but the result is the error
Error loading field1. The documentation is not fleshed out well enough to explain if I can do this fordata.types` is that the case.Just there in case you want to reuse the data types you already have defined. As it was already developed, I didn't want to remove it.
This has probably to do with an invalid JSON schema. Once the new
blockfield is ready, I hope it will make it easier.Also, for some UI/UX feedback. The gray input fields and the gray text on the buttons made me think at first that they we 'inactive' or 'read-only'. I would make the inputs have a gray border only and use white text for the buttons.
@zivbk1 working first on the functionality 😁
Ok, think the first version of the
blocktype is ready to be tested.Configuration
Once you did this configuration, it will render a similar experience to the
JSONdata collection field, but with the default field like you are used to.It is working!!! https://gitlab.com/zivbk1/hugostarter/-/commit/ee9eb4bf1087d88d0f187cfcaf1d355be9dea9fd
I think you can remove the words 'your' and 'value' from the selection field placeholder text.
Update coming in to fix the background colors of the inputs + placeholders
I have added a 'Kitchen Sink' field group ( https://gitlab.com/zivbk1/hugostarter/-/blob/main/frontmatter.json#L189 ) to test all of the field types and I am having some trouble with two of the types. This is the 'content' file for the test ( https://gitlab.com/zivbk1/hugostarter/-/blob/main/content/_index.md ).
'custom taxonomy' - 'feelings' ( https://gitlab.com/zivbk1/hugostarter/-/blob/main/frontmatter.json#L259 ) which shows a list of the feelings in the UI ( https://gitlab.com/zivbk1/hugostarter/-/blob/main/frontmatter.json#L215 ), but when I pick one it doesn't save it to the 'feeling' field in the file's front matter. It flashes for a moment and then nothing is selected or added to the file.
'fields' - 'photo' ( https://gitlab.com/zivbk1/hugostarter/-/blob/main/frontmatter.json#L220 ) which doesn't show up in the UI at all.
The support for 'fields' field is kind of working, I now see it in the UI and can edit the 'Title' text. But I am having some trouble with the image part. It opens up the media viewer and I can click the 'plus' icon to insert, but then the UI on the left flashes, closes the block I was editing and the image path is not added to the 'image' field. See this happen in the video below.
https://user-images.githubusercontent.com/12104446/153953117-5af9d536-85ea-4e65-a209-bb91517ea639.mp4
If I add the path to an 'image' field directly in the file front matter, I get an error about how the image cannot be loaded.
@apowell656
Why not just make that a single field that you can write markdown in and let the processor turn that into paragraphs in HTML for you?
@bwklein that sounds like a solve. Honestly, did not think of that and as I am typing I realize the oversight ;-).
@apowell656 one thing to be careful of in Hugo (if you are using it) is that currently shortcodes will not work in front matter content like that. There is an old issue in the Hugo project about it.
@apowell656 check this example out...
Source: https://gitlab.com/zivbk1/hugostarter/-/blob/main/content/_index.md#L19
Block Partial: https://gitlab.com/zivbk1/hugostarter/-/blob/main/layouts/partials/blocks/block-all.html#L9
@bwklein I think I may still have the same problem for other sections of my template for example:
Your proposal solves the
paragraphssection, but having a true repeatable field (example:authors) will be a problem, unless I break everything down into smaller components which is contradicting to DRY IMO.@apowell656 Are you using field groups for your social array? I think that you could also use the new json type for that too.
I'll try to assemble a quick demo of each option.
@bwklein I am not, but I am also trying to figure out where I will need to make changes without effecting my forestry sites (too much if possible), since it is more efficient for me to change sites in VSC. I have a few client sites done in Hugo, and the sites I own are Pelican with very similar structure and logic. I guess I am struggling to translate how FM will work in recreating the functionality in forestry.io.
@apowell656 so yes I think there is some work yet to do for nested field groups within field groups. Looks like @estruyf is working on supporting this already. I wasn't able to get it to work yet in my demo site, but that might also be due to not getting the config structure correct myself.
I also would probably setup a data file or markdown files to manage 'author' information in a single spot and then in a post front matter I would only use the author's id string. You can use that ID to then pull the necessary information from the markdown/data file for rendering into the template. This is more DRY than adding this information to every post/page/section, etc.
I have an example of this in a new 'blog' section that I am building for 'The Good Docs Project'.
Development Branch for the Blog - https://github.com/thegooddocsproject/website-hugo/tree/blog-test
Here is an example Author markdown file. We did this so authors would have their own page on the site with additional information they want to share. https://github.com/thegooddocsproject/website-hugo/blob/blog-test/content/en/authors/bryan_klein.md with the associated author page preview https://deploy-preview-68--gdp-hugo.netlify.app/authors/bryan_klein/
Here is an example of where the author ID (the author's filename), is used in the front matter of a post.
https://github.com/thegooddocsproject/website-hugo/blob/blog-test/content/en/blog/sixth.md
You could do that multiple author selection field with a 'Choices' field, using an id/title pair. Here is the preview of that post: https://deploy-preview-68--gdp-hugo.netlify.app/blog/sixth/
Here is the single template for a blog post that uses a couple of partials to render information related to the authors. https://github.com/thegooddocsproject/website-hugo/blob/blog-test/layouts/blog/single.html
Here is the partial where the list of author names and links to their pages are rendered https://github.com/thegooddocsproject/website-hugo/blob/blog-test/layouts/partials/_shared/author-info.html
Here is another partial where the blurb at the bottom of the post about the author is rendered. https://github.com/thegooddocsproject/website-hugo/blob/blog-test/layouts/partials/single-partials/author-follow.html
There are some other things like this going on in this site. You could do the same thing with author information in data files, but going with Markdown content pages was better for our use.
Image field should now be supported, next up are the taxonomy fields (tags, categories, custom).
Taxonomy field support has been added. Feel free to test it out and let me know which problems you might experience.
I'll test it... thank you!
@estruyf what is the best structure for repeated field sets like in 'social' array of this example. Should 'socal' be a block type with a field group or something else?
@estruyf
The path to the image is added to the front matter data, but the image isn't loading.
How I see it, is that
authorsis of type block, linked with a field group type ofauthor.authoritself contains a block fieldsocial, linked to asocialfield group.Haven't tested it yet to that extent.
Ok, that's what I tried, but with a single block field it wouldn't let me add an array of that one block type. Let me try again now since you have worked on taxonomies and those are working well for me.
Fix for this is coming up.
I tried the structure that you mentioned and I am getting an unexpected output from that in front matter data.
Authors field of type 'block' linked to 'author' field group:
https://gitlab.com/zivbk1/hugostarter/-/blob/main/frontmatter.json#L230
Author field group specification, with a 'social' field of type 'block' with a link to 'social' field group.
https://gitlab.com/zivbk1/hugostarter/-/blob/main/frontmatter.json#L291
Social field group with a single 'service name' field.
https://gitlab.com/zivbk1/hugostarter/-/blob/main/frontmatter.json#L309
Image preview is working now!!! 🎉
Trying it as well, the output looks ok, but the experience is not great. This will require some enhancements.
How are you getting the output to look right?
I have empty objects from higher level entities down in the lower level.
Took your example:
Content Type
Field Groups
As mentioned the UX needs to have some love in order to make it usable.
@estruyf ahh, so field groups will get me closer to what I need along with the block field. I will hopefully have time to test it tomorrow.
@bwklein the author information I use appears on the homepage only once at the bottom.
Added a couple of fixes + you can now save/cancel the data.
Save: closes the form
Cancel: resets the data back before you started editing
@estruyf it is working perfectly!!!! Thank you!
Can
labelFieldbe used for the text in the records list, with the name of the record type (author & social) being used as a fallback if labelField is not used?@zivbk1 can be done for sure!
At this point, I don't think this is a blocker anymore, I can start work on the 2 projects requiring Field Groups in frontmatter. Thank you for getting this done so quickly.
Great to hear! Let me know if there are things to optimize or if you find additional issues.
I've updated my demo project with support for this. https://gitlab.com/zivbk1/hugostarter
I am thinking of adding this into your examples for a Hugo site.
Label field support added 🚀
@estruyf , one word amazing! I have been able to rebuild my troublesome about-section. A couple of things, is it possible to add an image field to fieldGroup and add a default string to a field?
When I select an image the dialog closes or when I look at the current about-section, the image is not found (that could be because it is not in the media folder).
A workaround for the default string is to create a string with one choice and I tried to use a placeholder without success.
@apowell656 thanks! 🙏
Don't think I completely follow what you are asking for. Could you share some more details or screenshots?
About the default value, this is something the image field is not yet supporting. I'll create an issue for it to get that in as well.
The default values enhancement #255 is now included.
@estruyf my image issue may be related to an earlier comment dealing with images, but I have 'the image cannot be loaded' error for images referenced in the fieldGroup.
I believe my issue may is because they are in the asset folder of the theme and not in the media folder, but when I try to use an image from the media folder, the dialog box closes and just shows the rest of the block section. So I cannot test to see if an image works in the fieldGroup.
I am stuck in meetings until later tonight, so I won't be able to test until then, and thanks for adding the default value support.
This is all working well for me now.
Thank you @zivbk1 to verify this.