Advanced Forms Documentation

1. Introduction

The Advanced Forms add-on is a very popular add-on in the XenForo community with a lot of settings. This documentation will try to assist you in setting up forms.



1.1 What is a form?

According to Merriam-Webster's Online Dictionary:

a printed or typed document with blank spaces for insertion of required or requested information

Click to expand...

As an example the registration on every XF site is done by using the registration form. It asks us for our user name, email and password. We enter those details and send it.



In our case as XF owners we might be in a situation where we want to create custom online forms for our guests and members. Maybe you are looking for new moderators and you want them to apply for this position. And for that you set up a form with questions you want to be answered. Or maybe before people post "I need help" threads, you want them to answer some questions to have a better communication as the answers would provide useful information.




1.2 Front-End example of this addon

2. Where to find all the options of Advanced Forms?

This only tells you where to find all the options of this addon. So you can quickly check all places. This does not explain the settings yet.

Like all add-ons you find the essential settings in the Admin Control Panel (ACP). To enter the ACP you need to be an admin of the site. You will find on top left the access to the ACP by clicking on Admin:



Alternatively you can access the ACP by entering this url https://YOURSITE.com/admin.php. Replace YOURSITE.com with your own domain name.




2.1 Settings (ACP->Advanced Forms)

Once you are in the ACP and you have already installed the add-on:



A new segment will appear. You can find the majority of the settings in the left sidebar under "Advanced Forms" segment:






2.2 User group permissions (ACP -> Groups & permissions -> User groups -> x user group)



If you click on any of the user groups and scroll down, you will find the Advanced Forms permissions.






2.3 Widget (ACP ->Appearance -> Widgets -> Add widget)

If you add a widget



You will see the "Form list" widget.

3. Understanding the architecture of Advanced Forms


3.1 Types, Forms, Questions

There are basically 3 kind of entities to configure in order to have a form ready to be used.



We will dive into those 3 things with more depth after this when we dissect each thing. Right now what you need to understand is how the addon works.



1) You don't need to create a type. The type entity is optional and it is mostly there to categorize your forms. I prefer to use them to group my forms.

2) Basically you just create a form first and configure the options around it. Each single form will have its own options. So different forms might have different options. It depends on your unique requirements. In most cases check out all the options of the forms entity and have vaguely an idea what you want to do. Create a form and later you can come back to this after you created your questions to tweak some settings.

3) Create questions for your forms. Each form can have different questions and outcome. Your questions will influence the options of the forms.

4) You set up usergroup permissions.

5) You set up the widget if you want it.




3.2 Description texts for types, forms and question settings

The next paragraphs are about types, forms and questions.
Pretty much every setting for types, forms and questions has a description text under the setting.

They explain already what the setting is meant to be. When you are looking at these options, please read them to understand them . I will add additional explanations to them but most are obviously easy to understand.

Example:






3.3 How this documentation works

1) In most cases you will first see the full page of a settings page without commentary.

2) All settings are found in the ACP (Admin Control Panel).

3) We dissect each setting and explain each setting.

4) A screenshot of that setting is provided.

5) Then followed by a screenshot which shows what effect that setting has on the front-side inside the forum.

6) Often commentary is added to the screenshots when it is not obvious what the setting does.

7) In some cases no screenshot is provided because it is superfluous.

8) But remember, always read the descriptions you will find under each setting provided by the addon already.

4. Types

In this example I already created 3 types as you see.



To create a type click on "Add Form Type":




You can order the created types, copy or delete them using the available buttons.






4.1 Types all blank settings

If you want to create a type, these following settings will be displayed.

4.2 Main settings

Showing the setting in the ACP and then followed by its outcome on front-end.




4.2.1 Type name


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





4.2.2 Display order


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





4.2.3 This type is active


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





4.2.4 Show in widget


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





4.2.5 Show in navigation tab


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓

↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓

4.3 User criteria

User criteria in XenForo are part of the core. The core software utilises it in different places and many add-ons include user criteria in the add-on options. The Advanced Forms addon does it, too. It works the same way it does everywhere.

Important to note is that if you want to display a type to your users, you must pick at least one criteria so it "knows" under which circumstance it is displayed and used. If you do not select at least one criteria, you will not be able to save a type.

I will not attempt to explain every criteria as everyone has individual cases and needs. But I will shortly talk about the most important criteria which will be used primarily all the time in most cases.




4.3.1 User groups



Every registered user's primary usergroup including admins and moderators should be the registered usergroup.
Which means by selecting the registered usergroup, the criteria targets every registered user. This is the "default" way of allowing registered users to use a form or a type.



Same target can be achieved by the negation:



If you want to target ALL people, registered and unregistered, then you do like this:



(Note: by holding down the CTRL button you can pick more than one choice).


You can combine every criteria and make the target group smaller. It depends on what you want to do and your case. As example I set this criteria additionally:



Then, I must be in the relevant usergroup AND have posted at least 10 messages. It is not enough to meet one criteria, all must be met.


Warning:
As the description for user groups says: if a user is a member of any of the selected user groups, the criteria is met. So say, if you picked "administrative and moderating" as criteria, it is enough for me to be a moderator to meet the criteria. I don't need to be in both usergroups, one is enough. This only applies to the usergroup criteria. Outside you must meet all of them.

Note:
There can be cases where you want a user to be in usergroup A and B.
By default in XF it is not possible to target that.
But there is a trick you can do in the Advanced Forms addon, which only works in this addon. If you create a type and a form, you can set for both a user group criteria. Which means in order to see the type, you can select user group A. In order to see the form which is inside the type, you can select user group B. That means the user must be in both user groups in order to see that form. He needs to be in usergroup A to see the type, and in usergroup B to see the form which belongs to that type.

5. Forms

In this example I already created several forms as you see.



To create a form click on "Add New Form":




You can order the created forms, copy or delete them using the available buttons.



If you want to create a form, these following tabs will be displayed. There are in total 7 tabs and each tab has a lot of settings.

5.1 Form






5.1.1 Form name


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.1.2 Display order


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.1.3 This form is active


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.1.4 Start date / End date


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓



↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.1.5 End date error


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.1.6 Form type


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓

↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.1.7 PC sender name

PC stands for Private Conversation.
This is required even though you may not send any private conversations to anyone. Just in case you have to enter a valid username.
As example I created an account named "User account for forms".


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓
In case you use it in the report options (we will see later), that entered username is used:





5.1.8 Delete PCs


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓
It means the user who submitted the form will receive the PC, but it will be locked. And the user account who sent it will not have this conversation saved at all.






5.1.9 Success message


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.1.10 Override user style choice


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.1.11 Save answers to database


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓

5.2 User criteria






5.2.1 Must meet criteria



One must choose at least one criteria and it has to be met in order to use it.

As explained in the types chapter, the user criteria can be found in many areas and it works everywhere the same way. Recommended are the user group criteria for general purposes. Every case is different, so there is no right or wrong. Experiment with the criteria and choose what fits you the best. If you set more than one criteria, then each single one must be met, not just one of them.

Read 4.3.1 where additional stuff is explained as we already discussed user criteria for types and it works the same way for forms.




5.2.2 Form use limit


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓
After the limit is reached the form disappears from the list for the user.

And in ACP you get these buttons and you can reset the counter.
↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓

↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓




↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓

5.3 Report type

This is the place where you configure the outcome of the submitted forms. What should happen when submitted? How should it be processed?






5.3.1 Main Settings


5.3.1.1 Report title

This option is very important to configure. If someone submits a form, then that can trigger several things, such as creating a new thread, a new personal conversation or sending an e-mail. And here you can determine what the thread title will be as an example. I opted to have threads created when a form is submitted and chose to have the thread titles to be the username of the person who submitted. But you can also have answers of forms to be the title. So whatever the user submits as an answe to the question nr. X, that answer will be the thread title. You can also have multipe answers to be the title, for example {A1} - {A2} - {A4}. So the answers to the questions 1, 2 and 4 will be used as a title with a separating - between as that is what I used as example. But in our example screemshot I used {1}, which is different than to {A1}, as that stands for the username of the member who submitted it.


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.3.1.2 Parse URLs


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓



↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.3.1.3 Include member name/IP address


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓




↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.3.2 Email report options


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓
The king of the world would receive an e-mail after someone submits the form.




5.3.3 Thread report options


5.3.3.1 Poster user name


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓




↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.3.3.2 Report in existing thread


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.3.3.3 Use form as thread quick reply


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓




↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓




5.3.3.4 Quick reply option button


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.3.3.5 Report in new thread

If you wish that each submitted form has its own thread, you tick this box Pick a destination forum node. And then you can configure additional stuff, like if the created should be automatically watched by the creator or if the created thread should require approval. One nice touch is the "Post thread button to form" option. And you can choose a thread prefix which will be applied automatically to all created threads by this form.





↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.3.4 PC report options


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.3.5 User PC options


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓

5.4 Redirect options

Self-explanatory.

5.5 Promotion options






5.5.1 Instant promote

After submission the user is promoted to primary/secondary usergroup. I would never suggest you to change the primary usergroup of any user. If you want to use this feature, add a secondary usergroup to the user.



5.5.2 Decision or poll promote

Most options are self-explanatory here, so I will highlight only both important settings here.


5.5.2.1 Include decision links


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓

↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓

↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.5.2.2 Create promotion voting poll


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓

5.6 Normal poll

Creates a standard XF poll after the submission of the form. Has nothing to do with promotion options.

5.7 Misc. options






5.7.1 Show above form


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





5.7.2 Show below form


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓




5.7.3 Report color


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓

6 Questions

After you have created forms, you want to create the questions you want each form have. Each created form has a Questions button. Pick a form and create questions for it by clicking that button.



As example clicking on the "Questions" button of my form called "Administrator" forwards me to this section. I already have 3 questions created for this form, so you see them.



If you want to add a question, click on the button Add new question






6.1 Main base settings

Each question you want to create has some base settings.
2 base settings before you choose a question answer type and 5 at the end (after).
Only Question or Header phrase and Report format settings are mandatory out of those 7 base settings. They are required to be filled in if you want to create a question.

(For the None - This is a header phrase question answer type the latter 5 base settings are not available fyi.)

But based on which question answer type you pick, some extra settings inbetween the base settings will appear additionally as well. Those I will explain individually when each question answer type is explained. Right now I will explain all common 7 base settings among all of them (except for 1).

Very important thing is to read the explanation texts below each setting to understand how to use them as always.






6.1.1 Question or Header phrase (required)


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





6.1.2 Description


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





6.1.3 Question error


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





6.1.4 Show question in report


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓




↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





6.1.5 Show question if not answered


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





6.1.6 Report format


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





6.1.7 Question position in report Post/PC


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓

6.2 Question answer types

We've talked about the main base settings for all of them. Now let's look into the additional settings each answer type has (if any). These are the available answer types and below you will find the additional settings:






6.2.1 Agreement (Displays question text with optional checkbox below text)

Expected answers


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





6.2.2 Date picker

No additional settings to those 7 main base settings.




6.2.3 File upload (No more than 1 per form)

File display


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





6.2.4 Multi-line text

Placeholder


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓



Default answer


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓



Match regular expression & Regular expression validation error

You may use regex if you want to limit the answers to specific patterns and give it an error, if that pattern is not matched. Such as you might disallow numbers in the answer or only allow capitalized letters, etc. There are many websites which provide regex for specific needs.






6.2.5 Multiple choice (Checkboxes)*

Checkbox answer limit & Checkbox limit error




Expected answers


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓



Default answer


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓






6.2.6 Multiple Choice w/ all of the above option (Checkboxes)*

Expected answers and default answer is the same as above, just with "all of the above option" automatcally included to the form if you decide to use this answer type.







6.2.7 None - This is a header phrase

No additional settings to those 7 main base settings, in fact this is the only answer type which doesn't have the latter 5 base settings at all, which leaves this type with 2 settings only.




6.2.8 Single line text

Same as the 6.2.4 Multi-line text where the only difference is that it accepts only a single line as an answer compared to multiple lines. Has the same 4 additional settings. It has one special setting:


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





6.2.9 Single selection dropdown*

It's a dropdown where you define the choices and can choose a default answer if you wish.


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





6.2.10 Single selection forum list

It gives you a dropdown list of the forum nodes of your existing forum.


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





6.2.11 Single selection radio button*

Same thing as many above. You pick choosable answers and if you wish you can pick a default answer and it looks like as radio buttons.






6.2.12 Spinbox (number input)

Same Expected answers, Default answer, Match regular expression, Regular expression validation error settings as many of the answer types.

My default is 99 and it increases/decreases in 0.0001 steps


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓

↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





6.2.13 Thread prefixes (No more than 1 per form)

No additional settings to those 7 main base settings.


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





6.2.14 Yes/No*

Default answer


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓





6.2.15 WYSIWYG editor

Placeholder


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓

6.3 Conditional questions

This addon also lets you to create conditional questions. So you create a question, one answers it, and based on the answer of that, another question appears. This is called conditional questions. Conditional questions are limited to only specific answer types which are marked with a red asteristk (in total 5 different). Also please read the warning text.



To create a conditional question, you create a normal question and you pick one of the above answer types. Then a button appears in the questions section:



By clicking it we can now add a conditional question. The conditional question works the same as normal question. You can pick different question answer types and configure it like you want it. Only difference is you can now pick an existing question whose answer will now make this conditional question appear.




In my example below I can choose my existing question "Question 1" and then I can pick what answer to that question will make this conditional question appear. Let's pick "Yes". So if the user picks yes, my conditional question will appear.


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓


When answer is no:




When answer is yes the conditional question appears:



My example above is based on a "Yes/No" question answer type.




6.4 Default questions

Default questions are just regular questions jsut like explained above. Now if you don't want to create over and over the same questions but just with a different title, you can create a default question and include them in any form you have. This saves a lot of time.

I created one default question already.



Now I can go into any form and include this default question with 1 click.


↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓ ↓

7. Export

Now much to say here. If you click on the export button, you get a prompt on your Windows/Linux/MacOS asking you if you want to download a XML file. This file exports your created forms and you can import them whenever you need it.






8. Import

Here you can import the exported XML file. Not much to say here.

9. User group permissions



There are 3 permission for user groups. The first one is the basic permission about if one can view forms on the frontend. It only activates/deactivates the entry on the navigation bar. The real permission is set for each form in the user criteria section as explained in 4.2 and 5.3. Those define if you have the access to a form on the front-end.

The 2nd permission is needed for promotion options explained in 5.2.1 when you want to include decision links. This is a very powerful tool. You can create forms, people can use those forms as in answer the questions you set up. And then you can approve or deny them based on whoever has this permission. Let's say I have this permission and I approve one submitted form. Then that user will be promoted directly to a user group I selected in the options. So you can let people access specific areas of your forum by using this.

The 3rd permission is tied to 5.2.2. Not only we can include decision links but also can use polls to determine if we want to promote a user. And this permissions allows one to extend the end date of a poll.




10. Widget

Like many addons and the XF core, this addon makes use of the widget system of XF. Widgets are gadgets you can place on the front-end of your forum. You have several options around them like on which places you want to place them. Most notably the sidebar on the front-page is the most used place for widgets. The XF default has severals widgets placed there already. Like "Staff online, Members online, Latest replies" widgets.


To achieve this I created a widget like this:






11. Quick Example

https://streamable.com/8gpkti