If you’ve found an error, spotted something missing, or feel a section could be clearer or better explained, we’d love to hear from you. Your feedback helps keep the documentation accurate and useful for everyone.
Please report issues or suggest improvements on GitHub. Community input is invaluable in making the docs stronger.
Not comfortable with GitHub? No problem — you can also get in touch with us directly via our contact form. We welcome all feedback.
Creating Forms
Trongate contains a wide assortment of in-built form helpers to assist with form building. Form helpers are a set of PHP functions designed to simplify the process of creating and managing HTML forms within your application.
With Trongate, all form helpers are available immediately and with no requirement to load anything. There is also no need to update any configuration files if you want to use Trongate's form helpers. In short, they just work "out of the box".
A comprehensive list of Trongate's form helper functions is available from the Trongate API Guide.
Opening A Form
The creation of an HTML form that posts data to an endpoint (URL) requires a form opening tag. A form opening tag typically contains:
- A method property
- A form location
In normal (vanilla) HTML, this could be written like so:
The above form opening tag has an action property with a value of 'tasks/submit'. This means that the form is going to submit an HTTP request to the URL tasks/submit.
The form opening tag (above) also has a method property with an assigned value of 'post'. This means that submission of the form will result in an HTTP POST request being made.
Trongate's Form Open Function
With Trongate's form_open() function, an opening form tag can easily be rendered from within a view file. For example:
Having this code inside a view file will result in the following HTML being rendered:
When using Trongate's form_open() function, it's a good practice to declare the form location from within a controller file and to then have the form location passed into the corresponding view file. For example:
When Trongate's view() method is invoked, the second argument (i.e., the $data array) is automatically extracted, making the following syntax possible:
Don't forget to use opening and closing PHP tags when adding PHP to a view file! For example:
Rendering Form Elements
Having produced a form opening tag, your next goal should be to render form elements such as form input fields. A full breakdown of all available form elements can be viewed here. In the meantime, and for brevity, here are some commonly used form helpers that can be used to generate form elements.
Input Fields
The form_input() helper function can be used to create an HTML form input element, for text input. For example:
In the code sample above, the first parameter represents the 'name' attribute, and the second is the default value. This means that the above code snippet would render a form input field that has been pre-populated with the username, 'John'.
The PHP code above would render the following HTML:
Form helpers automatically handle proper escaping. Therefore, do not combine form helpers with the out() function or manual escaping functions.
Textareas
The form_textarea() function mirrors form_input() in every way except that it creates a "textarea" element.
In the code sample above, the first parameter represents the 'name' attribute, and the second is the default value for the textarea. In the code snippet above, the default value has been set to an empty string. This would produce an empty textarea element, like so:
Dropdowns
The form_dropdown() helper function generates an HTML select (dropdown) element with multiple options. For example:
In the example above, the first parameter represents the 'name' attribute, the second is an associative array of options, and the third is the selected option.
Here's the HTML that would be rendered by the above code sample:
Checkboxes and Radio Buttons
The form_checkbox() and form_radio() helper functions are used to create checkbox and radio button elements, respectively. For example:
In the code above, the first parameter represents the 'name' attribute, the second is the value, and the third is a boolean indicating whether the element should be checked by default.
Here's the HTML code that would be produced from the form_checkbox() code snippet, as shown above:
Here's the HTML code that would be produced from the form_radio() code snippet, as shown above:
File Input
The form_file_select() helper function generates an HTML file input element for file uploads. For example:
In this example, the first parameter represents the 'name' attribute of the file input element.
Here's the HTML code that would be produced from the above code snippet:
Submit Button
The form_submit() helper function creates an HTML submit button for submitting forms. For example:
In the example above, the first parameter represents the 'name' attribute, and the second is the button's label text.
Here's the HTML code that would be produced from the above code snippet:
Closing the Form
The form_close() helper function is used to close an open form. It not only generates the closing form tag but also includes a hidden CSRF token field for enhanced security. For example:
Here's the HTML code that would be produced from the above code snippet:
Note: The [random_token] placeholder represents a dynamically generated CSRF token value for security purposes.
Trongate's inbuilt CSRF protection is activated when:
- The form_close() function has been used to render a form close tag
- The run(), within Trongate's Validation class has has been invoked
Always use form_close(), and validate submitted form fields using the run() method from Trongate's Validation class, to ensure proper form closure and CSRF protection. This is especially important for forms that handle sensitive data.
A full explanation of how Trongate's in-built CSRF protection works - under the hood - can be found in the Trongate MX Guide.
Form Attributes
Most of Trongate's form helper functions can accept an array of attributes to customize form elements:
This will generate an input field with the specified class and style attributes.
In PHP, there are several different types of syntax that can be used to initialize arrays. The following examples produce precisely the same output though with very different (though perfectly valid) PHP syntax:
Example 1
Example 2
Example 3
Defining Attributes Within Helpers
For brevity, you can also define an array of attributes from within a form helper function. For example,
All of the different types of coding styles shown above are valid.
Complete Form Example
Below is a complete example of how to create a form in Trongate. This example includes a controller method and a corresponding view file.
Controller Method
The controller method initializes the form data and passes it to the view file:
View File
The view file contains the HTML and PHP code to render the form:
This example demonstrates how to create a form for adding a new task. The form includes fields for the task title, description, and a checkbox to mark the task as complete. The form also includes a submit button and a cancel link.
The Benefits of Using Trongate's Form Helpers
Trongate's form helper functions offer several advantages over raw HTML:
- Automatic Security: Values are escaped using HTML entity encoding to prevent XSS vulnerabilities.
- Validation Integration: Seamless error highlighting and repopulation after form validation failures.
- CSRF Protection: Built-in CSRF token generation through the
form_close()function. - Consistent Syntax: PHP-based helpers reduce context switching between HTML and PHP.
- Reduced Boilerplate: Simplified creation of complex elements like dropdowns and checkboxes.
Example using form helper:
Equivalent raw HTML: