Custom Fields

Posted in: Developer Documentation

This tutorial explains how to insert custom fields into WPAdverts using API, in order to complete it some PHP and WordPress API knowledge is required.

The code visible below you should paste either in your current theme functions.php file or create a new plugin and put it there.

Registering Custom Field in Form

Adverts is using Adverts_Form class to handle all the Forms, registering a field using this class adverts_form_load filter. This filter is executed when form scheme is being loaded, we will be basically updating the for structure before it’s loaded.

New fields are just associative arrays, look at the code below it will register two custom fields Text Input named my_custom_field and list of checkboxes named my_custom_checkbox.

add_filter( "adverts_form_load", "my_adverts_form_load" );

function my_adverts_form_load( $form ) {

    if( $form["name"] != "advert" ) {
        return $form;
    }
    
    $form["field"][] = array(            
        "name" => "my_custom_field",
        "type" => "adverts_field_text",
        "order" => 25,
        "label" => "Custom Field",
        "is_required" => true,
        "validator" => array( 
            array( "name" => "is_required" ),
        )
    );    
    $form["field"][] = array(            
        "name" => "my_custom_checkbox",
        "type" => "adverts_field_checkbox",
        "order" => 25,
        "label" => "Custom Checkbox",
        "is_required" => false,
        "validator" => array( ),
        "max_choices" => 2,
        "options" => array(
            array("value"=>"1", "text"=>"One"),
            array("value"=>"2", "text"=>"Two"),
        )
    );
    
    return $form;
}

That is it. The “Custom Field” and “Custom Checkbox” will now be visible when posting and editing an Ad, both in wp-admin and frontend.

adverts-custom-fields-form

Hint: If you want to display the field in wp-admin or frontend only, use is_admin()function to decide if the field should be displayed or not.

Adding a field to a form comes basically down to adding an array into “field” array, let’s have a quick look at the field params:

  • name (string) – this is field name that will be used as a <input> name parameter, but more importantly this will be also key used to save value for this field in posts meta table (you will be later able to access this variable using get_post_meta() function.
  • type (string) – field type, this needs to be one of registered inputs, refer to wpadverts/includes/defaults.php to find all registered and available field types
  • order (int) – the lower the number the higher in the form this field will be visible
  • label (string) – field name visible to user posting an ad (usually on the left side of the input)
  • is_required (boolean) – if true, form will not validate until this field is filled, additionally it will display a red asterisk next to field label
  • filter (array) – array of field filters, filters are functions that will format field value in a specific way, the complete list you will find in wpadverts/includes/defaults.php file.
  • validator (array) – array of field validators, basically a list of functions that will check if this field value is correct, the complete list you will find in wpadverts/includes/defaults.php file.

Further more multiselect fields (like <select> and <input type=”checkbox” />) have additional options:

  • max_choices (int) – maximum number of choices user can make (although as of now this option is for future, setting it to value greater than 1 will allow unlimited choices).
  • options (array) – this is basically list of available options in this field.

Note that the field is added to form along with filters and validators, so aside of displaying this field in the form it will also automatically take care of saving it in DB (in wp_postmeta table to be more precise).

Displaying Custom Field in wp-admin List

Sometimes the information you store in custom field is important enough to display it on ads list in wp-admin panel, the code below will show you how to do it

add_filter("manage_edit-advert_columns", "my_adverts_edit_columns", 20);

function my_adverts_edit_columns( $columns ) {
    $columns["my_custom_column"] = "Custom Field";
    return $columns;
}


add_action("manage_advert_posts_custom_column", "my_adverts_manage_post_columns", 10, 2);

function my_adverts_manage_post_columns( $column, $post_id ) {
    if($column == "my_custom_column") {
        $cf = get_post_meta( $post_id, 'my_custom_field', true );
        if(empty($cf)) {
            echo "<em>Empty</em>";
        } else {
            echo "<strong>".$cf."</strong>";
        }
    }
}

The code itself is pretty straightforward i think, there are just few things to remember:

  • your add_filter function for manage_edit-advert_columns needs to be run with priority 11 or higher (in example it is 20) otherwise the custom column will not be visible.
  • inside my_adverts_manage_post_columns() function we check if currently displayed column will be my_custom_column and if so, we echo value for this column.
  • the value for my_custom_column we take from my_custom_field post meta, if you followed the first step you should already have this field in the form.

This all is actually quite basic WordPress API 101, i do not want to get into details here as this topic was covered in depth in many tutorials available online, they will additionally teach you how to sort by your custom column

Displaying on Ad Details Page

Displaying custom field value on details page is pretty simple you just need one filter and one function.

In the code snippet below i again assume that your custom field is named my_custom_field and it is a simple text field.

add_action( "adverts_tpl_single_details", "my_adverts_tpl_single_details" );

function my_adverts_tpl_single_details( $post_id ) {

    $cf = get_post_meta( $post_id, "my_custom_field", true);
    $cc = get_post_meta( $post_id, "my_custom_checkbox", false);
    
    ?>
    
    <?php if(! empty($cf) ): ?>
    <div class="adverts-grid-row">
        <div class="adverts-grid-col adverts-col-30">
            <span class="adverts-round-icon adverts-icon-wordpress"></span>
            <span class="adverts-row-title">Custom Field</span>
        </div>
        <div class="adverts-grid-col adverts-col-65">
            <?php esc_html_e( $cf ) ?>
        </div>
    </div>
    <?php endif; ?>
    
    <?php if(! empty($cc) ): ?>
    <div class="adverts-grid-row">
        <div class="adverts-grid-col adverts-col-30">
            <span class="adverts-round-icon adverts-icon-wordpress"></span>
            <span class="adverts-row-title">Custom Checkbox</span>
        </div>
        <div class="adverts-grid-col adverts-col-65">
            <?php esc_html_e( join(", ", $cc) ) ?>
        </div>
    </div>
    <?php endif; ?>
    
    <?php
}

The final effect should look similarly as on the screenshot below

adverts-custom-fields