In the context of Concrete5, ProForms is a custom object type. Forms are Attribute Sets. And Questions are Attributes.
One of the main differences between ProForms Questions and Forms and other Attribute sets, is that ProForms allows you to attach Questions to more than one Form. This is a great feature that means you can have one question, for example “name”, that is shown in several forms. Same question, same handle, same akID, shown on multiple Forms and Form Submissions.
Custom Question/Attribute Types are extremely versatile and flexible, and there are a few finer points to ProForms that vary from typical AttributeTypes that should be considered.
$restrictDuplicates
By Default, only the standard C5 Text attribute can be defined to disallow duplicate entries. In other words, if the text question/attribute is added and set to not allow duplicates, when a form is submitted in the front end, the system will check for any previous entries containing the same value.
Custom QuestionTypes however, can define the $restrictDuplicates var in the QuestionType Controller file to present the option when creating/editing a question using that QuestionType to not allow duplicates. (Do not allow duplicate entries) Otherwise, this field is hidden to prevent confusion.
Again, $restrictDuplicates does not itself enforce non-duplicate data, it only allows the QuestionType to be set to do so.
To include $restrictDuplicates, simply add “public $restrictDuplicates = true;” just inside your QuestionType Class definition.
To actually enforce the restriction, edit the Question and make sure that “Do not allow duplicate entries” is checked and save.
$is_multipart
Some Question Types my have the need to utilize multipart form data for file uploading. In such cases, ProForms reverts to normal form submit() rather than AJAX. Currently, AJAX libraries do not generally support multipart forms. There are libraries that do...however for jQuery compatibility and the sake of leaner Code base, we are opting not to do so.
Any Question Type you wish to force multipart form data must have the $is_multipart = 1; designated. This lets proForms know to submit the form normally and that there is multi-part form data needed.
See the signature Question Type controller for an example.
$reviewStatus
In some cases you may have a default need to never show a label or answer for a given question type do to the fact that the given Question Type primarily depends on it's respective closer() method. (such as css container)
Adding <?php var $reviewStatus = 0; ?> to your question type controller will tell ProForms that said question type is functional only, and not for review purposes.
'_display' naming
In specific cases, such as the text display, and hr display, you may have a need to always display a question, but never show it's label, and never have a need to review it.
Appending '_display' to your Question Type handle will force the display in the front end form minus it's label.
Question Types with this requirement should also have $reviewStatus=0; defined within it's respective QuestionTypeController if it is desired to not be viewable in the form review process.
$hideLabel
If you have question types that will render a field, but not have a label, you can set that question types label to automatically be set to hidden .
For exmple, all the hidden question types like hidden page attribute, hidden user attribute...ect, render data for you to use/review in your form submissions but are hidden to the end user, thus you will likely not need to see any label for that field.
To add hideLabel, you simply add $hideLabel=1; to the question type controller file.
closer() method
ProForms utilizes a post-op attribute form for uses such as wrappers and containers that “wrap” around any given grouping of Questions.
Typically, as ProForms loops through each Question, it will print the form() method and/or corresponding form.php file for that Question Type.
Within the loop for the build of the form however, an additional form output can be utilized that prints outside of each form input’s bootstrap clearfix and input styling.
By including a closer() method and/or closer.php file in your Question Type, you can then place data and or styling for your forms without the worry of your div’s or containers being “broken” by subsequent out-of-order divs.
display() method
In some cases, such as the Validated Media Question Type, we want to display an actionable popup to view media instead of simply the media’s return values.
For example, the ProForms entry review pane checks for a display() method and/or file. In the case of the Validated Media Question Type, without a display method, the Question Type would return file ID’s as it would revert to getValue(). 1,5,12 ....ect.
Utilizing the display() method however, we simply built a nice popup display of video and images to review uploaded media items.
help_text() method
You can add the help_text() method to any Question Type and the return HTML formatted text will then be displayed in the "?" help icon show in the Question Add/Edit form within ProForms in the upper right corner of the edit pane.
Question Conditions
Question Conditions offer new flexibility in how you create form inputs. With Conditions you can add conditional inputs to your forms based on the inputs of other questions.
Example: you have a select question with a handle of "select_options" with one of the options being "other". You then create a text question type and set the "Only available under condition:" and set the if handle to "select_options", the modifier to "=", and the value to "other".
Now when a user filles out the form and selects "other", the text field you set up will load in via AJAX!
Using the "stepped form" Question Type
The stepped form question type can cause some adverse effects if not arranged correctly. Both the css container question type and the stepped form question type work in the same way, however, do to heavy javascript functionality, the stepped form must be arranged correctly when setting up. Failing to do so will cause layout and field functionality issues.
Using the "Publish" Question Type
Only two caveats need be mentioned for the Publish Question Type. If you would like to pass a Question Type to a Pages Title & Descritpion, your destination attribute name should be cName & cDescription respectively.
One other note is matching a Question Type to a content block. In this case your destination attribute handle should be "block[blockname][block_template]". So in the case of the content block - "block[content][blog_post]"
It should be noted that at this time, only the content block is supported.
AJAX Validation
C5 attributes already have a validateForm method. ProForms extends this method to set a class variable “$this->error” with an error message. As an example, the below shows how the phone question type validates:
[code]
public function validateForm($phone) {
if(!preg_match("/^[0-9]{3}-[0-9]{3}-[0-9]{4}$/", $phone)) {
// $phone is not valid
$this->error = t('Your phone number is not in the correct format!');
return false;
}
// $phone is valid
return true;
}
[/code]
ProForms front end AJAX validation automatically checks for the method validateForm, and then for $this->error.
Internal Use Only Forms
Internal forms allow you to associate actions and data to a form submission without the need to display those options in the front end form itself.
By default, ProForms installs one internal form called “Internal”.
Any Form can be designated for internal use only. This simply means that the form is not for front end display or use.
It also means that each internal form will be displayed as an additional tab when reviewing form submissions, and that the “(internal)” designator will be added to the end form name when reviewing questions in the Manage Questions area.
To add or update any form to be for internal use only, simply click on “Manage Forms” in either the application menu or the Manage Form button shown in the Manage Questions area.
An example of this type of use, is if you have managers on your team that need to review an entry and perhaps add notes to a text area QuestionType that has been added to a designated internal form.
Or in the case of the included and powerful “publish” QuestionType, the manager could review a form entry, and if all is well, check the publish option and save the form to then “push” that form to a page.
Adding ProForms Forms
The basic workflow for ProForms is as follows:
Reviewing Form Responses
By default, when you view a form submission, the question/answer pairs are displayed in value/text mode.
You can get creative with how this information is displayed by including a display.php file in your attribute_type folder as well as the display() method in that attributes’ controller.
You can also place the submitted form answers into edit mode. This allows you to review all form questions as label/input’s, and offers the ability to edit any of the data.
It should be noted that Internal Questions will always be displayed in label/input mode for editing, and do not have a text/value display mode.
Response List Headings
Any question can be relegated as a response "header". If any question is set to be a results header, when narrowing your search results to a specific form, that question will be included in the header list. If no specific form is chosen, the results header list will follow the normal search heading preferences.