I started learning about page/section/data models and I have a number of questions that aren’t covered in the docs:
How do you use a section model? The docs describe how to create one in depth, but to my surprise, I couldn’t actually find any statement explaining how to use one.
The docs do provide code snippets for page/section/data models, but it doesn’t explicitly state how to use them. For example, I have a section called header that should show up on every page at the top, and I tried to create a React component in my Next.js app using the code snippet in the docs. When I try to import that component and use it in my [[...page]].tsx file, I don’t see the section. However, if directly insert <BuilderComponent model="header" /> into [[...page]].tsx, it works. Not sure what’s the correct way to do this because the docs don’t say.
WRT the previous two points, I followed the site-wide ribbon section model tutorial where it says “add the section code to the top of your site.” But the code provided is for a component file, not something that you’d just stick into a preexisting file for a page (i.e., [[...page]].tsx). Making what we’re supposed to do explicit would be helpful .
Is there a way to insert page or section models into other pages or sections, either from within the visual editor or in code? I would expect so, but I can’t find it anywhere in the interface or in the docs. If not, the docs should explicitly state that it’s not possible and offer alternatives.
WRT the previous point, the docs set you up to think that it should be possible to compose sections and pages within each other. It explains under “Structuring your site with models” how some pages, like the home page, should use a page model, but other pages should be comprised of your code + section models. In the latter case, what is the container (i.e., the actual page, if not necessarily the page model–confused yet ?) that holds all of your code + section models? Given that you can use code components in the visual editor, I would expect that the blessed path is to register your code components and use those inside of a page alongside section models, which I would expect you to be able to drag and drop onto the page in the visual editor. Some explicit guidance here would be helpful.
What precisely is the purpose of the URL when creating a section model? @steve in his tutorial video on creating a site-wide ribbon simply says “this is going to show up on every page so we’ll use the root URL,” or something like that. The field description itself says “Enter a URL that this Builder content can be found for [sic] on-site for previewing and editing.” There’s a link that takes me to this page, which opens up a can of worms in my head: what does it mean to enable editing and previewing directly on my site? Does that mean that someone will be able to enter the URL that I put into the field and then they can edit my site? Why would I want to be able to edit my site directly on my site rather than by logging into Builder.io? How is this even possible? I can’t just put in https://www.google.com/my-builder-component into the editing URL field and expect that anything would show up other than a 404. Do I need to modify my DNS records to make this work? Etc.
Regarding points 1-5, I think that a lot of headache could be avoided if somewhere near the top of the “Content Models” page in the dev docs it simply states something like:
Data models can be accessed from within the visual editor or, if you’ve opted to integrate Builder with a preexisting app, your own codebase. Page and section models, while they are created and edited within the visual editor, can only be used from within code.
You can think of page and section models as the inverse of code components: instead of allowing you to use your code inside our visual editor, they allow you to use content created in our visual editor inside of your code.
If you’re not integrating Builder with a codebase, you don’t have to worry about page and section models. You can’t insert them from within the visual editor, they can only be added to your site through code.
^-- assuming that the above is true
Regarding point 6, I think I’m too confused to offer any advice, but I get the sense that I’ve missed something fundamental. Perhaps something really basic needs to be explained near the top of the docs, or perhaps I overlooked something.
P.S.: I hope my observations and questions don’t come off harsh. I’m loving Builder and learning about the platform, I just have a knack for getting tripped up on docs. I offer it in the spirit of friendly critique .
OK, I found the reason why the Next.js section model code snippet wasn’t working (see point 2 above). According Next.js’ docs:
getStaticProps can only be exported from a page. You can’t export it from non-page files.
I was copy/pasting the snippet into a component file, since that’s what the snippet looks like. So getStaticProps never fired and the HTML content for the section was never fetched, resulting in an empty-looking component. (The component was still mounted in the VDOM but it didn’t have any content.)
Using <BuilderComponent model="header" /> worked because it wasn’t setting the content to null. But then the problem is that it renders in the browser rather than at build-time. I’m guessing it fetches the content client side if you don’t give it content to render server side.
I would recommend updating the Next.js docs accordingly since the snippet provided implies that you should be creating a separate component file, which doesn’t work.
@ersin , just want to follow up here, are you stuck on any issues still? Sounds like you figured out the nextjs issue you ran into, and the other points read more like things we should update the docs with, correct?
As far as number 6 goes, I assume you are talking about the preview URL. That URL is required so Builder can show you a preview in the Builder editor of the content you are editing on your site. The way it works is that:
you add Builder to your codebase and integrate the section model on a particular page, or set of pages. Every time those pages load, Builder javascript is on those pages.
You set the preview url of that section model to be one of those pages.
When you open that section model in the Builder editor, we iframe the page you specified in the preview URL, and then the Builder app communicates with the Builder javascript present on your page to show you a preview of the content you are editing.
Does that help you? If so, I will make the updates to our docs to better explain this.
@korey yep, I think I’ve resolved my issues. Basically boiled down to the docs being a bit confusing, but I figured it out in the end .
As for number 6, thanks for your explanation. I confirmed as much with lots of experimentation. I think it’s another documentation issue.
The phrasing “Editing and previewing directly on your site” is very misleading, IMHO. It implies that when I go to my site (e.g., I enter “http://www.mysite.com” into my browser’s address bar), that I’ll be able to edit and preview my edits…well…directly on my site! But what you mean to say is that one can enable editing and previewing a given section within the context of whatever content is at the URL that one provides while still on Builder.io. IMO, that’s the opposite of “directly on your site,” you’re literally editing and previewing your site indirectly through Builder’s visual editor.
May I suggest rephrasing the help article’s title to something like “Editing and previewing pages and sections with content from your site,” and fleshing out that first paragraph to better explain the concept? Making it clear that you’re still editing within Builder’s visual editor, you’re just pulling in external styling and context strictly for the purposes of making the content that you’re editing look more like the final product.
As per my comments about documentation in the other thread, it’s also probably worthwhile to make explicit that this feature only makes sense in the context of external integration with a preexisting codebase.
Hey @ersin,
I’m just looking into builder and was excited to see my exact confusions I’m currently experiencing already asked in the forum Any chance you could elaborate on your findings? Points 1-5 are still not entirely clear to me…
My specific question is: Can I create an instance of a ‘page model’ and using the GUI builder drag in a ‘section model’?
My use case is that I would like to build a blog page template for showing single blog posts (which would include a header, footer, sidebar etc), and the main part of the page be filled dynamically (based on slug) of the corresponding blog post (section model).
This seems as standard as you can get in terms of creating a blog.
Ideally I’d avoid having to create an explicit blog/[slug].tsx in nextjs so that the ability to design/configure the page layout remains in the GUI.
Thanks!
Hey @Julian you absolutely can include any section model in any other page or section model within the Visual Editor with the use of Symbols! Symbols can be a specific model, but also any section model can be used as a symbol.
Simple select Symbol from the insert menu
And then once the symbol is on the page, you can select which Model to choose from. Here you would select your blog page section model
Btw, I posted that in October 2021. I liked Builder so much that I ended up working for them, improving their docs and putting together demos. Now I try to help in the forums, and I also started BuildQuick to help folks get set up and create their Builder sites.
Feel free to submit a project inquiry on BuildQuick’s site if you’d like to book some time, but otherwise, @TimG is spot on .
.
?) that holds all of your code + section models? Given that you can use code components in the visual editor, I would expect that the blessed path is to register your code components and use those inside of a page alongside section models, which I would expect you to be able to drag and drop onto the page in the visual editor. Some explicit guidance here would be helpful.
.
