1466091789_mail This is a guide for creating a contact form using Code Jetter Framework. This also helps you to get familiar yourself with the framework. I will break this down to small steps and explain them all in details. But before diving into the code follow this guide if you have not installed Code Jetter yet. Otherwise let’s get started with the step 1 which addresses the requirements.

1. Requirements

First of all, we need to think what needs to be done or in other words what the requirements are. Basically there should be an HTML form to receive any messages from users and also back-end functions to store them into database. Additionally, there should be a list for the admin to manage the messages. To achieve this we need to create a new component called Contact in Code Jetter.

2. Adding The New Component

Basically, adding a new component to Code Jetter includes:
– A folder and sub-folders in CodeJetter/components. In this case contact folder and controllers, mappers, models and templates sub-folders
– Routes which should be specified in CodeJetter/Routes.php
– A controller to keep the application logic. In this case ContactController which has got functions such as index, newMessage, lisMessages, etc and is located in CodeJetter/components/contact/controllers
– A model to represent a data entity. In this case ContactMessage which is located in CodeJetter/components/contact/models
– A mapper to map raw data to the relevant model. In this case ContactMessageMapper which is located in CodeJetter/components/contact/mappers
– Templates that are used for presentations.

3. HTML Form

In order to display the HTML form first we need to specify a simple route with GET request in CodeJetter/Routes.php:

This route means that every GET request to YOUR APP URL/contact will be sent to index function in CodeJetter/components/contact/controllers/ContactController.php. Please note that in CodeJetter/Config.php, defaultAction and defaultRole are set to index and public respectively. In this case we stick to the default values and do not specify them again. So let’s add index to ContactController:

At this point, to check if you have done the steps correctly place the following code in index function, and check YOUR APP URL/contact in the browser:

If you see this message in the browser it means that routing works as expected. Now we need to prepare different elements of the view including page, language, component template and form handler objects. So the controller will be like this:

Each view must have a page object which is used for different page related properties such as title and meta tags. By passing access role to page constructor, meta tag is automatically set based on accessRolesRobot in the config. Also using a language object you can get the translations for different keys in this case requiredFields. Default language is set in the config and the language JSON files are located in core/language. Then as you see, component template object has been specified. Each view can have one to many component templates. A component template must have a template path and can contain data. This is used to pass data to the view in this case requiredFields. Lastly we need to create the template /components/contact/templates/contactForm.php:

As you see $this->getCurrentComponentTemplate()->getData(); is used to get data for the current template. Also since we are going to send AJAX requests, data-url='/contact/new' is added to the form tag and it is handled in CodeJetter/public/scripts/script.js. To check everything is fine load YOUR APP URL/contact in the browser again and the result should be the same as below:

contact form

4. Storing Messages In Database

To store a message upon submission we start with creating the ContactMessage model:

As you see ContactMessage class extends BaseModel class and has got name, email and message properties with all the getters and setters. Now let’s create the mapper that has got the following structure:

As you see ContactMessageMaper class extends BaseMapper class and because BaseMapper implements ICrud interface, ContactMessageMaper must have add function. Also each mapper name must be model name with Mapper suffix. To insert data into database first of all inputs need to be validated. This can be achieved using Code Jetter Validator class. To use it, expected inputs (Input objects that can have one to many ValidatorRules) and the user (external) inputs must be passed to the constructor. Finally validate function should be called on $validator object:

Finally, all the columns and values should be passed to insertOne which is located in BaseMapper and handles inserting to database using PDO:

So the final mapper will look like this:

We also need to create the MySQL table called cj_contact_messages to be able to store the messages. To do that run the following query in your Code Jetter database:

Please note that cj is the prefix that is specified in the config (tablePrefix). Also since the mapper name is named ContactMessageMapper Code Jetter expects to have a table named cj_contact_messages. If table name is something else you need to specify it in the config (mapperTableRelations). Please remember that each table must have createdAt, modifiedAt, live and archivedAt columns. Also updateModifiedAtContactMessages trigger is used to update modifiedAt when the row gets updated. Since MySQL table cannot have multiple timestamps in old versions (only in MySQL 5.6.+ multiple timestamps are allowed), the trigger is used for backwards compatibility.

Now that ContactMessage and ContactMessageMapper are ready we can specify a simple route with POST request in CodeJetter/Routes.php:

This route means that every POST request to YOUR APP URL/contact/new will be sent to newMessage function in CodeJetter/components/contact/controllers/ContactController.php. Well the last step is the controller and it should look like this:

As you see, we get the inputs using Request class in newMessage. Then they are passed to add function in ContactMessageMapper. Also you need to add successfulContactMessageSubmission to CodeJetter/core/language/en.json:

Finally, the output is sent to font-end using Response class.

5. Contact Messages Management

So far we have managed to display the contact form and store validated data in a MySQL database. Now we need to have a list in admin (private) area to give the admins ability to view and manage messages. The same as before we need to have some routes, functions in the controller and a template for this. So first of all add the following routes to the router:
simple GET route which is used to display the list

regex GET route which is also used to display the list specially with a pager

simple POST routes which are used to delete the messages

As you see there are some actions or actually functions that we need to create in ContactController:

listMessages contains a pager which is used to manage pagination of the list, headers that are used to set sortable and searchable list heads, request functions to handle search and sort features, and component template that has got a template: components/contact/templates/contactMessageList.php. Regarding the delete functions you may have noticed that all the jobs related to database are handled using mapper class. Luckily, BaseMapper can handle all the delete functions and you do not need to add anything to ContactMessageMapper. But you may ask the difference between delete and safeDelete. As you may have guessed, the first one permanently removes the record from database whereas the second one sets live from 1 to NULL and archivedAt in the table. So the last step is to create the template mentioned in listMessages:

In this template basically there is a loop that iterates through $messages. Also PHP Table Generator is used to generate the table which is easy to use. HtmlUtility is another good tool which is a built-in class and is used for different purposes such as generating confirmation modals or generating the checkboxes in this template.

So far your component directory should be the same as below:
Screen Shot 2016-06-17 at 8.36.14 AM

Form Security

In terms of security, there are multiple layers that make the contact form secure. First of all, the form is protected against CSRF attacks thanks to FormHandler class. Actually this handler generates a random token called globalCSRFToken which is verified on the server. Also as you saw, all the expected inputs are validated using the Validator class. In addition, using PDO the chance of SQL injection attacks is minimum. However, to increase the security you can implement CAPTCHA and client-side validation.

In summary, hope this was helpful to get yourself familiar with the Code Jetter Framework. You can find the code on GitHub and also you are more than welcome to contribute.