I have some suggestions for some documentation changes/additions. I must say, you have great documentation compared to other PHP apps I've seen, I just recently went through your tutorials to get my forms up and running. However, there were a few snags that I hit and had to resolve so I thought I would let you know about them in case you wanted to add them into the tutorial to make it more idiot-proof.
Sometimes it's better to have the help from an outside observer when creating documentation as it is seen differently from someone who doesn't know the code, so anything that is thought to be obvious by the code creator might not be so to the average user. Having created documentation for PHP code myself, I know this all too well.
------------------------------------------------------------
The first one is not that big of a deal but I'll mention it. In the "Adding a single page form with the API" tutorial on "Step 3: Putting through a test submission", you have the line:
Even though it does say "form page", it can cause a little confusion because both the form page and the thank you page have the ft_api_init_form_page() call in them. So putting more emphasis on putting it on the page that has the actual form code might help. Just a suggestion. I found myself wondering if I had the code in the right file during troubleshooting. (Actually, if I remember right, the test submission page in Form Tools had an even less detailed description on which file should get the line of code). But, like I said, this is kind of nit-picking, but I thought I would mention it.
------------------------------------------------------------
Next, in the tutorial, you mention that if you don't have a name= attribute on your submit button, that you need to add one. I would suggest making this point emphasized more. Maybe even put it in bold. My form submission was not working for a while because my name attribute on the submit button didn't match the setting in the Form Tools code. Again, not too major since you do have it in there already.
--------------------------------------------------------------
These next two are more important suggestions.
My form is on a PHP page that includes the main page content, including the form. My code is essentially mapped out like this:
page.php:
content.inc:
Your tutorial says to put the Form Tools code on the "page" with the form. So, naturally I put the code on top of content.inc. However, when asked by Form Tools for the URL to my form page, I gave it the URL to page.php since content.inc is never opened directly. These actions caused 2 separate problems to appear.
Configuring it that way caused the following situation: The form submission worked ok, but no redirection to the thank you page was taking place. After thinking about the code, I realized that the redirect could not take place because PHP can't send new page redirect headers after any content has already been sent to the browser. So, then concluded that I would have to put the Form Tools code at the top of page.php instead of content.inc. Assuming this would fix the problem, I then found that it was worse than before! Now I could not even get to my page. Instead a Form Tools error page would come up (I think it was error #305, but not sure) and I could not even access my page at all. So, after double checking all the code, I decided to take the directions literally and where it says "Form URL", I changed it to read /path/to/content.inc instead of /path/to/page.php. This fixed all problems and the form now works and so does the redirect.
The moral of the story: You might want to add in your documentation that the code must be placed at the VERY TOP before any output is sent to the browser (such as in include situations like mine) and also that the Form URL must be the path to the actual file that the form is on, not just a page that includes that file.
---------------------------------------------------------
Well, that's all I have for now. I just thought I would share my experiences in case you wanted to use them to update the docs.
Louis
Sometimes it's better to have the help from an outside observer when creating documentation as it is seen differently from someone who doesn't know the code, so anything that is thought to be obvious by the code creator might not be so to the average user. Having created documentation for PHP code myself, I know this all too well.
------------------------------------------------------------
The first one is not that big of a deal but I'll mention it. In the "Adding a single page form with the API" tutorial on "Step 3: Putting through a test submission", you have the line:
Quote: 1. $fields = ft_api_init_form_page(X, "initialize");
Copy that line and overwrite the corresponding line in your form page.
Even though it does say "form page", it can cause a little confusion because both the form page and the thank you page have the ft_api_init_form_page() call in them. So putting more emphasis on putting it on the page that has the actual form code might help. Just a suggestion. I found myself wondering if I had the code in the right file during troubleshooting. (Actually, if I remember right, the test submission page in Form Tools had an even less detailed description on which file should get the line of code). But, like I said, this is kind of nit-picking, but I thought I would mention it.
------------------------------------------------------------
Next, in the tutorial, you mention that if you don't have a name= attribute on your submit button, that you need to add one. I would suggest making this point emphasized more. Maybe even put it in bold. My form submission was not working for a while because my name attribute on the submit button didn't match the setting in the Form Tools code. Again, not too major since you do have it in there already.
--------------------------------------------------------------
These next two are more important suggestions.
My form is on a PHP page that includes the main page content, including the form. My code is essentially mapped out like this:
page.php:
PHP Code:
/*
HTML TAGS HERE - INCLUDING NAVBAR AND PAGE HEADER
<?php
*/
include('content.inc');
/*
?>
HTML TAGS HERE - PAGE FOOTER
*/
content.inc:
PHP Code:
/*
ALL HTML/PHP CONTENT FOR THE PAGE INCLUDING THE FORM HTML.
*/
Your tutorial says to put the Form Tools code on the "page" with the form. So, naturally I put the code on top of content.inc. However, when asked by Form Tools for the URL to my form page, I gave it the URL to page.php since content.inc is never opened directly. These actions caused 2 separate problems to appear.
Configuring it that way caused the following situation: The form submission worked ok, but no redirection to the thank you page was taking place. After thinking about the code, I realized that the redirect could not take place because PHP can't send new page redirect headers after any content has already been sent to the browser. So, then concluded that I would have to put the Form Tools code at the top of page.php instead of content.inc. Assuming this would fix the problem, I then found that it was worse than before! Now I could not even get to my page. Instead a Form Tools error page would come up (I think it was error #305, but not sure) and I could not even access my page at all. So, after double checking all the code, I decided to take the directions literally and where it says "Form URL", I changed it to read /path/to/content.inc instead of /path/to/page.php. This fixed all problems and the form now works and so does the redirect.
The moral of the story: You might want to add in your documentation that the code must be placed at the VERY TOP before any output is sent to the browser (such as in include situations like mine) and also that the Form URL must be the path to the actual file that the form is on, not just a page that includes that file.
---------------------------------------------------------
Well, that's all I have for now. I just thought I would share my experiences in case you wanted to use them to update the docs.
Louis
