prismicio
[RFC] Build Custom Types (Page Templates) locally
What is this? We've begun the process to bring the power of building Custom Types locally using slice-machine-ui, as is already possible with Slices. This will enable this use of content relationships & integration fields with Slice Machine
This has given us a unique opportunity to rethink what the most important aspects of creating Custom Types are. We would love your feedback about what you see as the best parts of this process, and what you would change or add if you could.
Let us know:
- What do you add to the static zone? Should it be easier to declare a static zone?
- Do you use groups?
- Do you like the name Custom Types, Pages Templates, or something else? What makes the most sense?
- How should we handle menus?
Give us any and all feedback/feature requests in regard to how we should build the builder 🙂
Opinions What do you think?
I attended the live webinar on 2021-03-31, some notes you all asked me to put over here:
-
In webflow, a repetitive section between page templates is called a 'symbol'. It's basically the same idea you are trying to do with a persistent slice. It might be good to look at their UI for insight into how this works for your slice machine design.
-
Prismic tags need work. Right now they are just one <> many relationships and don't create nodes of their own, and they don't work with slice machine. I often need the relationships to be many <> many in tagging situations. Use case is I have a news item, and want to tag by locations. Both are content-types and need many <> many relationship. Right now I have to build location as a content type. If your tags were more powerful, I could build them using prismic tags. Queries would be much simpler
-
How do you envision component testing and slice machine working together? Something like Jest. It would be good to have a demo or documentation of 'the way' this should be set up.
-
Variations are cool but content editors aren't always good at making these choices. Seems a little dangerous to put that in the hands of editors. I would think some new roles need to get created inside of the system to make sure only certain editors can use the variations.
I really like in what direction Prismic is going 👍 Some thoughts about «Page Templates» and Slice Machine.
- I think it's important to be careful about naming Custom Types too specifically. Having hard-coded categories would exclude many use cases that are now covered (since nobody tells you what a custom type is). I'm thinking of data models like products, authors, events which are in themselves not a page. My idea would be, to allow a user to create their own Custom Type Category. This would allow me to create a category called «Page Templates» if needed but also it would be flexible enough to be used as a data model. This flexibility is one of the biggest reasons why I switched from Wordpress to Prismic.
- Instead of having specific SEO Fields, why not implement more field-options. Like validation for min/max lengths, allowed characters etc... This again would keep Prismic more flexible than its competitors.
- The same goes for the menu. I'd much prefer to have a menu field (which allows more nesting), which I can add to a custom Custom Type. I don't want to be locked into using the Menu type since there might be other use-cases (like a menu in the footer custom type etc.)
- Please don't forget about the Custom Type editor outside of Slice Machine. Some projects don't need to have the JSON next to components. For simple projects, it's much more straightforward to model data in the browser.
I see how predefined Custom Types would speed up development. My idea is to present the user with templates for Custom types. These templates could include «Page templates», «Navigation» etc. but are in themselves completely customizable. I'm looking forward to use the new features!
I think this is a great addition to slice-machine. It was oddly compartmentalized before to have only have slices locally, as you had to go back into Prismic to make the slices available on the custom types. This will improve workflow for devs as we can basically control everything we need to outside of Prismic.
Static Zone Absolutely super useful on pretty much every page I create. We declare fields in here that are necessary for the page.
SEO Fields There was mention of creating a default set of SEO fields, and I think that would be great. It's something we add to nearly every page, and having validation and requirements for these fields is equally important. I do think having it as an optional addition to a custom type is important. Something I personally appreciate about a custom type is the blank slate you get when creating a new one. There are some content models we create that need nothing more than the exact static fields we specify, and that is nice for editors from a user perspective, because they aren't presented with fields that are not necessary. I don't know if I like the SEO component as a tab at the top. I currently have it this way for a few projects, and it's often neglected or missed from editors. Possibly something that appears as a nice Facebook/Twitter card in the right-hand column?
Groups Groups are nice, and are definitely useful for set repeating content. It would be more useful if we could use them within repeaters, as I think that would cover a lot of use cases that developers have when trying to build a layout that needs repeating content within repeating content. Nesting can get messy, so maybe a depth limit? I do think adding a multi-select dropdown could help accommodate users who do need a group field in a more concise way. Currently if you want to pick multiple options from a dropdown, you have to create a group with a dropdown tag, and that can get pretty lengthy.
Name As for the name, Custom types does feel off. I think it's primarily the word custom as essentially everything we're creating is in a way, custom. Templates is commonly used by other CMSs that bake the data into HTML, so in this case that doesn't really fit in my option. What we're really doing here is designing a content model.
Menus Defining a place for us to model a navigation structure would be superb. Navigation have a wide variety of content, and structure, similar to how slices work. I would love to see a similar workflow to slices, where we can define the fields that an editor can then build a navigation structure from. So for instance, we as the developer would define the depth the navigation could have, and what fields are required for each layer. For example, a top level could simply be a link, where as links under that could be broken out into sections with a label, or even a photo.
Menu concerns One concern with this approach is, how far do you carry it? Do you have the same structure for a mobile nav, or does it need something custom? Do we need something for footers? As long as these are optional, I think they're great additions. If they are not used, there probably shouldn't be a tab in Prismic to navigate there as it can cause confusion for a client/editor as to why their navigation tab is empty.
Mockup / UI I would love to be able to see the mockup of that (Phil ?) showed in the meetup. Obviously it's still a work in progress, but I do think visually from what I remember a group would ideally have a visual difference from the static and repeatable zones. In the future, do you see the mockup and UI design being carried over to the writing room? It might get a bit clunky to have a different UI for developers, and a completely separate UI for the writing room.
Storybook The storybook screenshot feature of a custom type seems like a game-changer. It will definitely help editors select the proper template without having to use their imagination and hope they pick the correct one. How do we pick what content shows in the screenshot if the page is primarily slices? Do we get an option of selecting a default?
Overall I think this will be a game-changer for development workflow, and it really does enable us to work locally. Awesome work!
I think I might be in the minority here and this might be the wrong place to put this feedback but I want all the features of locally built types/slices but I don't want to have to use the slice machine UI.
I was the avail poster in the video thread, so with that context let me go through some thoughts.
- I think the idea of having the type/slice shape live in version control is a really good idea, it gives a bit of upgrade capability out of the box but doesn't solve for everything, more on that later.
- I really do think that the shape of data shouldn't be JSON but something more akin to how you describe types in Prisma, using the graphql schema as your base allows you to build in type safety by default.
- I'm not exactly sure what the slice machine UI gets a developer as any editing, designing, and iteration will likely happen in storybook anyway. You're only structuring the content in slice machine, I don't need a GUI for that.
What I really want is a way to describe relationships between types easily as well as what basic types those shapes are made up of. Below is an example of a close to real-world use case for our team at Avail.
type Button {
label String
link Url
}
type FeatureSection {
content RichText
}
type Hero {
image Url
title RichText @limit(h1, h2)
cta Button
}
page HomePage {
id Int @id @autoincrement
hero Hero
features FeatureSection[] // Group of feature sections.
}
page LandingPage {
id Int @id @autoincrement
sections Slices @options(Hero, FeatureSection)
}
I think for extra version and upgrade security you could include things like @error, and @deprecated, as well as have new types extend old types.
I'm imagining the above proposal would be synced periodically with a prismic repo. This could be done through the CLI and easily part of a CI/CD pipeline using github actions.
@pkrawc - check out keystone.js, it does almost exactly what you're looking for.
@jserrao Thanks that's a good recommendation. I would like to continue to use prismic as the writer's room though, so hoping that same functionality can make its way into their tooling.
@pkrawc - yeah, I like the SaaS nature of Prismic for client work, but I like the schema definition in Keystone better as a developer. A fusion of the two would be ideal.
@pkrawc I mentioned this in the comments on the stream, and also had a thought about it on twitter when Hugo gave an example of the pris-types => https://pris-types.vercel.app/live
It has a sort of similar layout to what you are describing, but could technically be a starting point for introducing a single point of entry into the custom types and slice models.
In a way, because it is building the values from what has been defined, similar to Prisma, then it can be validated client side before being pushed to the API and also it would give the whole type hints.
But then that is actually what is placed in source control. As an aside, if a project needs to have backwards compatibility, that data can be exported to the appropriate JSON schema that would be useful for others. Such as a normal way of creating a custom slice as it is currently.
Maybe it isn't exactly the same as the page LandingPage {...} format. But could be an approach the Prismic team could do or could be bootstrapped as an in-between thing 🤷♂️.
It does seem to still depend a little on the slicemachine part to write to disk and also have screenshots. Maybe that could be extracted as separate stand alone functionality?
Some great points above, that cover most of my thoughts. I'll echo a few of my considerations below:
- I agree with @david-noe & @kolbykruger that Content Models is a better fitting name than Custom Types. I strongly disagree with Pages as the label, as content is commonly digested across multiple locations (homepage highlights, content landing page, content internal page, etc.). It should be categorised by its concern, and not usage.
- There is a strong case for templating SEO sensible defaults and best practices for devs/content editors, although this should be easily dismissible for scenarios not requiring this. As considered above by @kolbykruger, some visual indication or prompt upon Publishing should remind content editors if these fields are recommended/required. Basic validation for recommended character length, etc. would be nice, but this might stretch the Prismic offering in to a different arena?
- Menus are such an interesting problem. I think the baseline UX should be as simple as grouping a single depth of units of
url,title. However it should have the flexibility to accommodate advanced structures for mega-menu designs: with structures likeurl,background-image,icon,title,subtitle,blurb, with child and grandchildren relationships (each with their own models). - I share the sentiment with @pkrawc that the SM UI could be surplus, assuming that data structures can be intuitively authored with a concise syntax. Like @jserrao, I've had good initial experiences with Keystone Next.
I strongly disagree with Pages as the label, as content is commonly digested across multiple locations (homepage highlights, content landing page, content internal page, etc.). It should be categorized by its concern and not usage.
I think Page is as much a label for context as it is for usage. In atomic design, you have levels that are really just defined by how reusable they are, which I think applies here. Page is similar to Template in that jargon which is a pattern that can as a whole be repeatable, but can't be easily consumed by other components/types.
@darrenbarklie
Hey all, thanks so much for all the awesome feedback.
I’m coming back from my holidays, and it's so nice to see your enthusiasm and commitment to building this. There is a bunch of topics here, and I'll try to tackle them all.
Naming of Custom Types & Page Templates
We don't want to rename all custom types to page templates. What we saw is that there is different uses cases for custom types today. You use custom types for Page templates (page models), navigation, data models (product, author, category) Depending on the use case, we could have a tailor-made editing experience if we know what the specific use case for a specific data model or custom type is. We identified two main ones at the moment. For example, if you declare that you're willing to create a new model to manage a Page template, we could
- Include by default SEO management with social cards
- Include a way to manage URLs
- Generate a page template in your code rendering the slice zone and the selected slices
- Generate stories & mocks If you're willing to create a new nav, we could customize the Editing experience to manage a Menu that Is completely different than the one to edit a page
Manage the other models like a generic custom type until we detect other specific use cases.
Using the Slicemachine UI to build the model & more generally, the purpose of the SliceMachine UI
Today, our thinking process leads us towards using the custom type builder as the main way to define content models. We can generate mocks, generate stories, version the code with the models, and provide good documentation & screenshot for free are only doable if you have this builder locally. What are the main problems that are you seeing going this way? Is it the migration path?
Variations and roles
We didn't plan yet to introduce roles for variations. Is it a need that you faced previously with slices (like allowing only some editors to use specific slices)? In which case would you want to create a slice variation that cannot be used?
Thanks a lot for your feedback again and let me know if something is unclear.
I agree with @kolbykruger that "Template" sounds like it's related to HTML, whereas "Model" sounds like it's related to JSON.
In addition to Pages and Menus, I'd also like to suggest another Document Supertype: Taxonomies.
Taxonomies would supersede the native tagging system. When you define a Taxonomy type (such as "Author," "Tag," or "Category") Prismic would recognize it and turn it into a filter in the document list.
When you add a "Taxonomy" field to your Page Model, you could specify "single" for a select field or "allow multiple" for a multi-select.
By combining the best of both worlds from the native tagging system and custom tagging system, this would improve the UX in many ways.
Unlike the native tagging system:
- You can create a model for your tags.
- You can create multiple kinds of taxonomies.
Unlike custom tagging systems:
- You could use taxonomies to filter in the document screen.
- The document list would no longer be cluttered with tags, authors, etc. (They could appear under a "Taxonomies" tab.)
- You would get proper behavior in the editor. (Currently, if you want to add multiple tags, you need to nest a Content Relationship in a Group, which is not a proper multi-select, and allows you to add the same tag multiple times.)
Custom types can now be built within Slice Machine (since quite some time!) 🎉
