Adding forms to pages -- clarifications for newbies

Support Forms & Blueprints
1

Hello,
A few clarifications on the form documentation, from a newbie who has struggled, in hope that it can prevent the struggle of other newbies:

  • The definition of a form goes in the “frontmatter” of a markdown page (the files with extension .md), that is the part at the top in between the “—”.

  • This frontmatter (and therefore the definition of the form) is written in YAML syntax… and in YAML, the structure defined by spaces is super important, so be sure to check that your formatting is correct or your form won’t be recognised.

  • If you want to use one form in multiple pages, you still have to place the definition of this form in between the “—” of a markdown file. And you have to make sure that this file is placed in a folder that is inside the “pages” folder, because that’s where all pages go.

For example, you could create a file called applejuice.md and put the following text inside:

---
forms:
    bibi:
        fields:
            -
                name: email
        buttons:
            -
                type: submit
---
 some other text if you want, but doesn't matter

which would define a shitty form called “bibi”! You would place this markdown file inside a folder called say “superjuice”, which would itself be inside the “pages” folder (note that you could also just place the definition of the bibi form in the frontmatter of one of your already existing pages, instead of creating a new one).

Then in the template that is used to render the pages where you want that form to be, you would include:

{% include “forms/form.html.twig” with {form: forms(‘bibi’)} %}

… and that’s it. grav checks all the markdown files that fit the pages structure, so it will find your form. Youhou!

(Note that my struggles may partly be related to the fact that I’m not using the admin plugin, but maybe I’m not the only one like that…)

2

Just a quick reply to mark it as solved, even though it’s all in the first post

3

@nicooo, Thank you for sharing your experience and suggestions.

In order to improve the documentation on forms, the following information would be handy:

  • Which page(s) of the documentation are you referring to?
  • The entry page of the documentation on adding a form to a page is Frontend Forms.
    Have you read that page and if so, which step in Create a simple single form is not clear and should be clarified?
  • If the ‘standard’ way of adding a form to a page doesn’t fit your needs, what is the specific usage of forms in your project that you are trying to implement and couldn’t find the proper documentation for?
  • Your explanation on Frontmatter, Yaml and the ‘/pages’ folder suggests you were not clear on that yourself. Did you read the introductory chapters of the documentation? Especially: 1. Basics/Basic Tutorial and 2. Content/Pages.

Thanks.

4

@anon76427325, Yes I read the documentation and it is quite ok. I mean reading it again, it says everything. It’s just that a total newbie like me needs things to be emphasised sometimes I guess. I will give some examples. Please don’t judge, it’s really not simple when you start from little knowledge.

So the documentation says:

To add a form to a page of your site, create a page […]

Here my issue was that for me a “page” is not a very precise term. I was trying to find out where this page should be.

Earlier in the documentation it was well said that

you need to be aware that all our user content, is stored in the user/pages/ folder of your Grav install

but still, I had done some modifications in the theme template and so I it wasn’t obvious to me that whenever the documentation talks about a page, it refers to the pages of your websites that are in the pages folder. It sounds a bit obvious now, I admit, but it wasn’t at that time.

[…] and set its Page File to “Form”. You can do it via the Admin Panel, or via filesystem directly by naming the page form.md .

This part made me unsure whether my issues could be related to the fact that my forms were not always in pages called form.md. And then this:

You can even provide the name of a form defined in other pages.

made me think that it was probably ok, but since it wasn’t working, I did spend a bit of time renaming my pages seeing if it was the issue.

Later it says

There is however a more powerful method of displaying forms that can take advantage of the new multi-forms support. With this method you actually pass a form: parameter to the Twig template specifying the form you wish to display:

{% include "forms/form.html.twig" with { form: forms('contact-form') } %}

So what I’ve discovered is that neither the page in which you want the form to be rendered, nor the page where the form is defined actually need to be named form.md. It would have helped me here if it was said that the names of pages (both ways where it’s defined and where it’s rendered) don’t matter when you call forms by their names or path (please tell me if I’m not correct).

and then it is said that

An alternative way to display a form is to reference the page route rather than the form name using an array, for example:

# Contact Form
{% include "forms/form.html.twig" with { form: forms( {route:'/forms/contact'} ) } %}

Here I was back into my issue of knowing where my forms should be, because it wasn’t obvious at all to me that ‘/forms/contact’ refers to ‘grav/user/pages/forms/contact’. I mean it’s a bit the same as my “where my page should be” issue. It makes total sense now, but at that time, I was struggling, placing the forms everywhere :rofl:, in the template folder, config folder, plugin folder, etc. cause there were some folders called “forms” here and there, so maybe it could be there :tipping_hand_man:.

Basically I think the documentation is quite good, and maybe close to very good, but when you’re a newbie, you need to hear things a few times in different ways, have recaps etc. because when you have issues, you try things where you feel the documentation is not toootally clear.

Finally for my YAML comment, yes I kinda knew the front matter was YAML synthax, cause well it is said before and I had even heard that in other contexts… and then the YAML bit of the documentation explains how it works, but it comes in the “advanced chapter”. I feel some emphasis earlier that one needs to be very careful about not messing up with the indentation would be useful. Also there’s no real mention that one should go and have a look at YAML chapter. You have to try clicking on the YAML hyperlink to realise that there’s a whole section about the YAML syntax (it’s already nice, don’t get me wrong, you did a really good job with this whole documentation, but for a newbie, a bit more emphasis would be useful). Also what is a bit confusing is that you have proper yaml files and also some yaml bits that can be in markdown files. A newbie may wonder if those are really the same YAML syntax exactly or not etc. At least I did.

Overall these are very small additions that are needed I think. Mostly recaps and emphasis, but for newbies they are super useful. By the way, I appreciate your reply. We can see that you care about it. It’s very nice. Thanks… and grav is great. I really like the website that it allows me to build at the moment and I feel I’m learning tons.

5

I had a response drafted a few days ago, but the more I read your post, the more it seemed that your descriptions were all pretty accurate and you understood fine!

One bit of your original clarification puzzled me but wasn’t incorrect. Creating a dummy form page seems unnecessary and muddied your example a little.

Add an issue to the docs repository if you think someone can use your feedback.

6

Nicooo, can you clarify your third bullet point:

If you want to use one form in multiple pages, you still have to place the definition of this form in between the “—” of a markdown file. And you have to make sure that this file is placed in a folder that is inside the “pages” folder, because that’s where all pages go.

Does this mean you have to copy/paste the same form definition in the header/frontmatter of every page where you want to see it? If that’s the case it’s not correct to say we’re using one form on multiple pages… we’re using multiple forms on multiple pages. Right? Can you help me understand this. Thanks.

7

So there is no way, even with the newest release of the Forms Plugin, to add a reusable form within a .md file somewhere in the theme folder? Or with some other method?
I find this really strange for Grav’s granular (and wonderful) processing engine.
TIA

8

@phmg701, I think @nicooo’s answer describes how it needs to be done by creating a page first.

Somehow I didn’t find this topic before I posted my own question. I think I’ll have to read more thoroughly Nicooo’s post and try to implement it some time when I get to Contacts page development :slight_smile: