Adding testimonial form example #24
Conversation
| @@ -0,0 +1,15 @@ | |||
| <div class="container mx-auto mx-2"> | |||
There was a problem hiding this comment.
While I'm not sure how many people would actually use this template, maybe it is worth cherry-picking the necessary Tailwind CSS and packaging it up for delivery in the ui/src/index.scss file.
| @@ -0,0 +1,15 @@ | |||
| # Forms example - Testimonial | |||
| This is an example of using a form submission to automatically create a piece type in your Apostrophe 3 project. | |||
There was a problem hiding this comment.
I have to admit that even though this is a very clear sentence, it took me a couple of read-throughs to really understand what this example did. Do you think you can expand this introduction just a little? Something along the lines of, "The form module can be an easy way to collect information from front-end users. This example demonstrates how to take that information and use it to automatically populate the fields of an existing piece type in your Apostrophe 3 project."
| # Forms example - Testimonial | ||
| This is an example of using a form submission to automatically create a piece type in your Apostrophe 3 project. | ||
| ## Installation | ||
| * Copy the `modules/@apostrophe/form` folder into your project |
There was a problem hiding this comment.
Depending on how experienced people are with their code editor, moving folders about in their project can be a little daunting. There is a web site, that allows you to download individual folders from GitHub as zip files. Maybe we could add such a link for each folder to be downloaded. We should just add a small description of what will happen when you click on the link so that people aren't surprised.
| * `form/index.js` adds the async function `createTestimonial`, which is called on form submission. This calls the `testimonial.addTestimony()` function to create our new testimonial piece. | ||
| ## The testimonial piece | ||
| ### `index.js` | ||
| The fields `names`, `emailaddress`, `phonenumber`, `testimonial` and `helpneeded` need to be matched by fields in the created form. When the form is submitted, that data is passed to `addTestimony`, these fields build our new piece. There are two extra fields in the `testimonial` piece type: |
There was a problem hiding this comment.
I would say something like: "We will automatically fill five string type fields in the testimony piece type. Each of these fields need to be in the form you present to the user. They are .... You should choose the input types to match the expected input in your form. When the form is submitted, ..."
| * `photo` - we want to be able to add a photograph of the person submitting the testimonial, but we don't want to expose our site to file uploads on this first implementation. | ||
| * `active` - this is a flag that defaults to false when the testimonial is created. When approved by an editor or admin, changing this flag to true will allow the testimonial to appear in the display component. | ||
|
|
||
| Finally in this piece, we have the `latest` component which returns a list of the active testimonials. |
There was a problem hiding this comment.
Maybe you could include a short snippet of code that shows how to use the component?
There was a problem hiding this comment.
Hi @bulldoguk,
Thanks for submitting this! I'm really sorry that it has been overlooked for so long. I think it is a valuable contribution to help people use the form module in new ways. Having said that, I think some people will get a little lost in your README. There are also some places where the code doesn't conform to our internal linting. I feel a little hypocritical pointing this out because the base form module has a few errors that I will be submitting a PR to fix!
So, first step. Could you please ensure you have installed all the repo dependencies to get the .eslintrc of the apostrophe module. Then run npm run lint. This will produce a list of errors and warnings. Can you fix all of these that occur in your new files? I will take care of them in the base form repo.
Next, I am making some suggestions to improve the README.md file. These are suggestions and are open to discussion. Please make changes and/or reply back to each of my comments. I am also thinking that we will want to make some changes to the base form README in order for people to find your wonderful example!
Finally, we will need to update the CHANGELOG to indicate that this is being added into the repo.
Thanks!!!!!
Bob
trying again with this example form setup - this time on the correct repo!