Getting Started With Custom Fields

Custom Fields add-on allows modifying forms in [adverts_add], [adverts_list] shortcodes, and the contact form on Ad details pages, using drag and drop forms editor.

Creating First Form

In order to create the first custom form, you need to start with purchasing, downloading, and installing custom fields add-on.

Once you have it installed and activated go to wp-admin / Classifieds / Options / Custom Fields page, you will see an empty list like on the image below

To customize a form you need to first click the “+ New Form Scheme” button it will allow you to create a copy of the form selected in the “Form Type” field.

The form has the following fields:

• Form Type – allows to select which form you will be extending, you can select one either “Adverts Add” (modify Create Ad [adverts_add] form), “Adverts List” (modify search form on Ads list [adverts_list]), and “Contact” (modify contact form on Ad details pages).
• Form Title – a title that will help you remember what this form does.
• Form Name – enter the unique name using only a-z, 0-9, and “-” characters only, the name you will be able to use in shortcodes to apply the form scheme to a selected shortcode.
• Default – if you check this checkbox, then this form scheme will be automatically applied to all shortcodes (unless overwritten in the shortcode itself).

When you click the “Create New Form” button the form will be saved and you will be redirected to the visual editor where you can edit the form using drag and drop editor.

On the left side, there is a visual representation of a form, you can drag and drop fields to rearrange the form any way you want. The visual representation of a form depends on the form which you are editing.

On the right side, there are three widgets

• Form – contains basic information about the form, including the “Default” checkbox and “Delete” button which allows deleting the Form Scheme if you no longer wish to use it.
• Basic Fields – here you can find fields that you can drag and drop into the form on the left. Note that when you are editing Search Form the Header and Text Area fields will be missing as they are not applicable to the search form.
• Trash – when you delete a field in the form on the left it goes into Trash, the custom fields you can permanently delete from there by clicking the trash icon, the built-in fields can be thrown into the trash but you cannot delete them permanently.

To edit existing fields in the form, you need to hover a mouse cursor over them, when you do that the cursor will change to drag, the field which will be dragged will become selected with a gray dashed line, and Edit and Delete buttons will appear as on the image below.

When you do some changes in the form remember to click the Update button in order to apply the changes.

Field Types

The Custom Fields editor allows selecting from 10 different custom field types: Header, Label, Short Text, Text Area, Dropdown, Checkbox, Radio, File Upload, Autocomplete, and Date&Time.

These fields will be described in more detail below, additionally in the Adverts Add form there is a special field Account but this field is not in the Basic Fields section as it can have one instance only.

In the Add Form when editing fields, each field has some common settings like name, label, additional CSS class, and is-required. Additionally, each field has a “Field Specific Settings” section which depending on the field allows setting some validation options or if the field is a dropdown, checkbox, or radio then when editing you can enter field options.

Entering Field Options

Every field with predefined options (dropdown, checkbox, radio) allows entering options in the “Field Specific Settings” section.

You can either enter options manually or use Data Sources to automatically fill the options.

There are the following configuration settings that allow configuring field options

Max Choices – enter how many options users can select (applicable to checkboxes and dropdowns)

Empty Option – check if you want the options list to start with an empty option, the empty option is not a valid selection, that is when the user will submit the form without selecting a different value, this field will show an error (applicable to dropdown only)

Fill Method – either “use registered data source” or “I will enter options myself”, if you decide to enter options yourself, below a new section will appear where you can enter options.

Entering Options Manually – In order to start adding options click the “Add Option” button, a new field will appear, you can enter the option value there. To add more options click the “Add Option” button again. To reorder options use the drag and drop icon to move the options up or down. Use the trash icon to remove the option.

By default the value visible in the option will be also saved in DB, if you would like to display one value as an option in the Form and save a different value in DB then check the “use values” checkbox, this will allow you to set both “value” and “text”. “value” will be saved in DB and “text” will basically be an option label.

Using Registered Data Source – by default, the only registered data source is “Adverts Categories“, but it is possible to register new Data Sources from wp-admin / Classifieds / Options / Custom Fields / Data Source / Add New Data Source panel.

To read more about data sources please check the Gettings Started with Data Sources article in the documentation.

Form – Create Advert

When editing fields in Adverts Add Form there is an additional section named “Display Settings” which allows configuring how the field will display on Ad details pages.

Note that the “Display Settings” is available only for custom fields. For built-in fields, you cannot change display settings.

The display options are

• Display – select where the form field will be displayed, if you select the option “Forms Only” or “Admin Only” then the rest of the fields will disappear as the field will be displayed in forms only or only when editing an Ad in the wp-admin panel, so the display settings on Ad details pages will not be applicable.
• Display Type – select if the field should be displayed as Table Row (that is like Location or Category on Ad details page) or as Full Width (that is similarly as Ad description).
• Display As – select how the field should be rendered, by default it will be rendered as Text. Other allowed options are HTML, URL, Image, Audio, Video (the last four you should use only if the user will provide a valid URL as a field value).
• Display Style – this field is visible only for multi-select fields (Select and Checkbox) it allows to define how items will be displayed if there is more than one value selected.
• Icon – this field will show only if Display Type is equal to Table Row and allows selecting an icon that will e displayed next to the field label.

Form – Search

The search form ([adverts_list)] fields you can edit the same way as you edit the [adverts_add] fields using the drag and drop editor, the main difference between them is that in the search form you can configure how each field in the search form will be used to search the database. To find out more about search forms please refer to the Configuring Search Fields article

Form – Contact

The contact form looks similar to the Adverts Add form and you can similarly add fields to it, all the fields that are added and filled when submitting the form will be appended to the contact email sent to a person who posted the Ad.

This form does not have any special sections.