Custom Fields (Paid Addon)

Posted in: Modules and Extensions

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 / Add New panel, you will see a form like on the image below

wpadverts-cf-add-new

The form has 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 – some 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 form scheme to a 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 “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.

wpadverts-cf-editor-new

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 a form which you are editing.

On the right side, there are three widgets

  • Form – contains basic information about the form, including “Default” checkbox and “Delete” button which allows deleting Form Scheme if you no longer wish to use it.
  • Basic Fields – here you can find fields which 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 gray dashed line and Edit and Delete buttons will appear as on the image below.

wpadverts-cf-editor-new-hover

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

Field Types

The Custom Fields editor allows creating 6 different custom field types: Header, Short Text, Text Area, Dropdown, Checkbox and Radio, this fields will be described in more details below, additionally in Adverts Add form there are two special fields Account and Gallery but these fields are not in the Basic Fields section as both of this fields 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 “Field Specific Settings” section. You can either enter options manually or use registered data source to automatically fill options.

wpadverts-cf-multiselect

There are following configuration settings which 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 user will submit form without selecting 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 “Add Option” button, a new field will appear, you can enter option value there. To add more options click “Add Option” button again. To reorder options use drag and drop icon to drag the options up or down. Use the trash icon to remove option.

By default the value visible in the option will be also saved in DB, if you would like to display one value as option in the Form and save a different value in DB then check “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” which will automatically generate a list of categories, it is possible to register your own data sources using wpadverts_custom_fields_register_data_source() function, below you can see an example code explaining how to use this function.

add_action( "init", "register_data_source" );
function register_data_source( ) {
    wpadverts_custom_fields_register_data_source(array(
        "name" => "unique-name-here",            // som unique name of your choosing
        "title" => "Options",                    // this will be visible to users 
        "callback" => "data_source_function"     // function which will list options
    ));
}

function data_source_function( ) {
    return array(
        array(
            "value" => "apple",
            "text" => "Apple",
            "depth" => 0,
        ),
        array(
            "value" => "banana",
            "text" => "Banana",
            "depth" => 0,
        ),
        array(
            "value" => "orange",
            "text" => "Orange",
            "depth" => 0,
        ),
    );
}

You need a unique name to identify the data source, some title explaining what this data source is storing and a callback function which will list all available options.

The callback function needs to return an array of arrays, each nested array should have three keys

  • value – text that will be saved in DB.
  • text – option label visible to a user when filling the form
  • depth – for future use, for now always set this to 0

This code you can add either in your theme functions.php file or create a new WordPress plugin and paste it there.

Form – Add

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” are available only for custom fields. For built-in fields, you cannot change display settings.

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

wpadverts-cf-display-settings

The display options are

  • Display – select where the form field will be displayed, if you select 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 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 which will e displayed next to field label.

Form – Search

When you will create first search form you will notice that it layouts differs from the Ad form and mimics the design of a search form in [adverts_list] shortcode

wpadverts-cf-form-search

The first thing you can notice is a dark line with a drag icon, it separates fields which are always visible in the form from fields visible after clicking “Advanced Search” button.

When editing fields in this form you will notice “Field Width” option which allows selecting if the field should take 50% or 100% of the available space.

The most important part of the configuration is the “Search” section, it allows to configure how Ads database will be searched when this field is filled. The first field in Search section is “Search By” dropdown which has options in four groups:

  • Advert Fields – these options does not require any additional configuration
  • Dates – requires configuring how dates will be compared
  • Taxonomies – requires configuring which taxonomy field you will be searching by and how matching should be done
  • Custom Fields – requires configuring how the fields will be searched and how to compare values.

This is quite complex and getting the search right might be difficult at first, so below, i will explain in more details how does the different search types work.

Once you select in Search By field that you want to search by one of the groups requiring configuration you need to fill a “madlib” form, also known as natural language form, this is a kind of form which inputs are inside a sentence, feeling the inputs completes the sentence,you can learn more about madlibs here.

Dates

Currently, you can configure search by Publication and Last Modification date (the expiration date is a custom field so it is not really possible to have it there), if you will select one of dates you will need to fill following sentence in order to configure the search

Retrieve Ads posted [ … ] selected date.

In place of [ … ] you need to select one of following options

  • on – use this option if you want show Ads posted on a specific date.
  • before – use this option if you want to display Ads posted before a specific date
  • after – use this option if you want to display Ads posted after a specific date

Typical use case is showing Ads posted within a date range, in this case you would need to have two inputs searching by the same date field, one configured with “before” option and the other with “after” option.

ProTip: The search by date accepts relative search by date, so if you wish to search by ads posted in last 7 days you can have field configured to search “before” and as the search option enter “7 day ago”.

Taxonomies

Taxonomies usually have predefined values in the wp-admin panel, so most of the time you will want to use radio, checkbox or drop-down inputs to search for them, although the search can work with other inputs as well.

By default the sentence will look pretty much like below, you will need to fill two values:

Match if “Categories” taxonomy field [ … ] [ … ] search values.

In the first field you select taxonomy field you want to search by, allowed values are term id, title, term slug and term taxonomy id.  When searching by “Adverts Categories” you will want to select term id, in other cases, it will depend on how is your callback function was written or what field you are using to search. If you are using a text field it makes sense by title or term slug.

In second field you can select search operator or what will be considered a valid match, explaining it is a bit tricky, to make it easier lets imagine we have three Ads each with different categories selected

  1. Car with taxonomies A, B, C
  2. Toy with taxonomies C, D
  3. Book with taxonomies D, E

I will use this imagined Ads and taxonomies when explaining search types, there are three options

matches one or more – use this to return only Ads which have assigned at least one category from the search, for example

  • searching for B will return Car
  • searching for D will return Toy and Book
  • searching for A and C will return Car and Toy

matches none of – use this to exclude some taxonomies from search, for example

  • searching for C will return Book
  • searching for E will return Car and Toy
  • searching for A and E will return Toy

matches all of – use this to return only Ads which have assigned all categories from the search, for example

  • searching for C will return Car and Toy
  • searching for B and C will return Car
  • searching for A, C and D will return Toy

 

Include Ads from sub-categories as well

At the end of Search group there is an “Include Ads from sub-categories as well” checkbox. Checking it is only applicable if you are using tree-like taxonomies (for example multi-level categories), in other cases it does not do anything.

If you decide to check this checkbox then when selecting an option in search form WPAdverts will automatically search in this option sub-categories. In other words selecting an option in search form will have the same effect as selecting this option and ALL its sub-options.

Custom Fields

When searching by meta fields you will need to fill two short sentences, first one being

Match if “Meta Field” [ … ] search value.

In the place of [ … ]  you can enter one of following values:

  • is equal to – use if search field value should exactly match meta value
  • is NOT equal to – use if search field value should be different than match meta value
  • is greater than – use if search field value should be greater than meta value
  • is greater or equal to – use if search field value should be greater or equal to meta value
  • is smaller than – use if search field value should be smaller than meta value
  • is smaller or equal to – use if search field value should be smaller or equal to meta value
  • contains – use if search field value should contain match meta value
  • does NOT contain – use if search field value should not contain match meta value
  • has one or more selected – use this field only with multi-select fields (checkbox, dropdown)
  • has none of selected- use this field only with multi-select fields (checkbox, dropdown)

The second sentence to fill is

Compare values as [ … ]

Where [ … ] can be one of numbers, binary data, texts, dates, dates and time, decimal numbers. Which one you will select depends on what data is user entering in the search field, most of the time you will select either numbers or texts.

Form – Contact

The contact form looks similarly 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 contact email sent to a person who posted the Ad.

This form does not have any special sections.

Applying Form Schemes To Shortcodes

When creating or editing form you can select that the form scheme is default scheme and it will be automatically applied when the form is rendered. For forms in [adverts_add] and [adverts_list] it is possible to override the default setting with “form_scheme” param.

For example, if you have a form named “cars”, you can apply it to the [adverts_add] shortcode by changing the shortcode to

[adverts_add form_scheme=”cars”]

The form names you can find in wp-admin / Classifieds / Options / Custom Fields panel.