Developers Only: AWPCP Customization Guide

Introduction

This document describes the general layout of the AWPCP folder as well as the contents of most of the files and folders inside. The instructions provided here assume that you are an expert in PHP coding, understand HTML very well, and are comfortable with the WordPress PHP API. If you feel that your skills aren't up to par in these areas, you should consider hiring help for your project on a site such as Upwork or Codeable.io.

CUSTOMIZATION WARNING: Beyond the help provided here, customizations to the plugin are something that you do on your own and without further support from the AWPCP team. We can't provide support on any custom changes you make to the plugin--you must be comfortable in debugging techniques and tools to find and fix issues on your own. Any bugs you find in the plugin must be reproducible with the original, unmodified plugin in order to be considered issues we can address.

Before altering plugin files

• Consider alternative ways to achieve what you want: AWPCP supports CSS customization and a basic Ad HTML template for list and detail views that you can customize under Classifieds->Settings, Ad/Listing Tab.
• Avoid modifying plugin files unless absolutely necessary. You could end up breaking your site or losing information.
• MAKE A FULL BACKUP BEFORE UPGRADING THE PLUGIN EACH TIME! Please keep in mind that WordPress will remove any modifications you make to the plugin files during plugin upgrades. This is standard WP behavior and not in AWPCP's control, so if you forget about it, you'll lose your changes!

OK Dave...I get it. What about the customization guide?

Naming Conventions

• New classes must be defined in their own files and the name of should start with the class- prefix, followed by the name of the class in lowercase letters with dashes as word separators.
• Template files should be added to the corresponding sub-directory of /templates/ and the name of the file should end with tpl.php.

Directory Structure

Top level files

Top level directories

admin/

frontend/

includes/

Most files inside the includes/ directory are utility classes, defined in their own files, that are combined to create the internall API used to power all the plugin features.

The naming convention filename for files that define classes is to use the class- prefix followed by the name of the class in lowercase letters with dashes as word separators. For example class-listings-collection.php defines class AWPCP_Listings_Collection.

templates/, frontend/templates and admin/templates

These three directories hold the PHP files used as templates to generate admin and frontend screens, widgets and email messages. The following is a list of the most relevant templates:

resources/

Both CSS and JavaScript code used by the plugin comes minified, so:

• Do not change the plugin's JavaScript code. Include your own scripts using a custom plugin or the active theme's functions.php file.
• Do not change the plugin's CSS code. Include a custom stylesheet or use the active theme's stylesheet to overwrite plugin styles.

Hooks and Filters you can Use

The following defines hooks and filters built into AWPCP 3.6.x and later to allow you to override and customize the behavior of the plugin. These API calls do not exist on any AWPCP version before 3.6.

NOTE: You should put these hooks and filters into a file outside of the plugin directory to avoid loss of your work on upgrade of the plugin.

awpcp-get-posted-data

Used to filter the data posted to listing details and search listings forms.

Parameters

• $data: The data posted already collected by the plugin.
• $context: Either search or details.
• $source: Available when context is details, otherwise set to an empty array. It is the source the plugin used to retrieve the $data, usually $_POST or information previously extracted from that global variable.

Usage

function my_get_posted_data( $data, $context, $source ) {
    if ( $context === 'the-context-i-am-interested-in' ) { // either 'details' or 'search'
        // alter $data
    }
    return $data;
}
add_filter( 'awpcp-get-posted-data', 'my_get_posted_data', 10, 3 );

awpcp-before-save-listing

Fired before attempting to save a listing to the database.

Parameters

• $listing: The listing object that will be presisted to database.
• $data: The data array used to populate the listing's properties.

Usage

function my_before_save_listing( $listing, $data ) {
    // your code here
    return $listing;
}
add_filter( 'awpcp-before-save-listing', 'my_before_save_listing', 10, 2 );

awpcp-listing-from-object

Allows developers to filter the listing that was constructed from the database record.

Parameters

• $listing: The listing to be rendered.
• $object: The database record pulled

Usage

function my_listing_from_object( $listing, $object ) {
    // your code here
    return $listing;
}
add_filter( 'awpcp-listing-from-object', 'my_listing_from_object' );

awpcp-content-before-listings-list

AWPCP's uses awpcp-content-before-listings-list filter to allow modules and third party plugins to insert any content before the list of listings that appears in the Main Classifieds page, the Browse Ads/Categories page, or the Search Ads page.

Parameters

• $content: The content to insert before the list of listings.

Usage

function my_filter_handler( $content ) {
    // insert additional content here
    return $content;
}
add_filter( 'awpcp-content-before-listings-list', 'my_filter_handler' );

awpcp_menu_items

AWPCP's uses awpcp_menu_items filter to allow modules and third party plugins to control which links appear in the menu that is usually printed at the beginning of each AWPCP page.

Parameters

• $items: An associative array of menu items:
  • post-listing: Place Ad menu item.
  • edit-listing: Edit Ad menu item.
  • browse-listings: Browse Ads menu item.
  • search-listings: Search Ads menu item.

Usage

function my_filter_handler( $menu_items ) {
    $menu_items['custom-menu-item'] = array( 'url' => 'http://example.com', 'title' => 'Custom Menu Item' );
    return $menu_items;
}
add_filter( 'awpcp_menu_items', 'my_filter_handler' );

awpcp-content-placeholders

AWPCP's uses awpcp-content-placeholders filter to allow modules and third party plugins to extend the set of placholders that can be used in the Single Ad Layout and Listings Layout settings.

Parameters

• $placeholders: An associative array of placeholders.

Usage

function my_filter_handler( $placeholders ) {
    $placeholders[ 'placeholder' ] = array( 'callback' => 'my_placeholder_handler' );
    return $placeholders;
}
add_filter( 'awpcp-content-placeholders', 'my_filter_handler' );

awpcp-render-listing-item

Fires when a listing is being rendered using the content of the Listings Layout setting as template.

Parameters

• $rendered_listing: The rendered content.
• $listing: The listing that was rendered.
• $position: The position of the item in the list.

Usage

function my_filter_handler( $rendered_listing, $listing, $position ) {
    // alter rendered content or provide your own.
    return $rendered_listing
}
add_filter( 'awpcp-render-listing-item', 'my_filter_handler', 10, 3 );

awpcp-browse-listings-content-replacement

Use to completely replace the content of the Browse Listings page.

Parameters

• $content: The content of page. If the value IS NOT null then a different
  filter handler already provided content replacement.

  Return null to let the plugin use the default page's content.

• $category_id: If not null, you should show only litings from this category.

Usage

function my_filter_handler( $content, $category_id ) {
    // provide your own content here
    return $content;
}
add_filter( 'awpcp-browse-listings-content-replacement', 'my_filter_handler', 10, 2 );

awpcp-search-listings-content-replacement

Use to completely replace the content of the Search Listings page.

Parameters

• $content: The content of page. If the value IS NOT null then a different
  filter handler already provided content replacement.

  Return null to let the plugin use the default page's content.

• $data: Posted form data.

Usage

function my_filter_handler( $content, $data ) {
    // provide your own content here
    return $content;
}
add_filter( 'awpcp-search-listings-content-replacement', 'my_filter_handler', 10, 2 );

awpcp-show-listing-content-replacement

Use to completely replace the content of the Show Listings page.

Parameters

• $content: The content of page. If the value IS NOT null then a different
  filter handler already provided content replacement.

  Return null to let the plugin use the default page's content.

Usage

function my_filter_handler( $content ) {
    // provide your own content here
    return $content;
}
add_filter( 'awpcp-show-listing-content-replacement', 'my_filter_handler', 10, 2 );

awpcp-content-before-listing-page and awpcp-content-after-listing-page

Use to insert content before/after a single listing's page.

Parameters

• $content: The content to be inserted.

Usage

function my_filter_handler( $content ) {
    // add your own content here
    return $content;
}
add_filter( 'awpcp-content-before-listing-page', 'my_filter_handler' );

awpcp-show-ad

Use it to filter the content of the Single Ad page.

Parameters

• $content: The content of the page.
• $listing_id: The ID of the listing being shown.

Usage

function my_filter_handler( $content, $listing_id ) {
    // add your own content here
    return $content;
}
add_filter( 'awpcp-show-ad', 'my_filter_handler', 10, 2 );

awpcp-single-ad-layout

Use it to filter the template used to render the Single Ad page.

Parameters

• $layout: The template.
• $listing: An instance of AWPCP_Ad. The listing being shown.

Usage

function my_filter_handler( $layout, $listing_id ) {
    // modify layout here
    return $layout;
}
add_filter( 'awpcp-single-ad-layout', 'my_filter_handler', 10, 2 );

awpcp-ad-details

Use it to filter the listing's details before they are shown in the Single Ad page.

Parameters

• $details: The listing's details.

Usage

function my_filter_handler( $details ) {
    // modify details here
    return $details;
}
add_filter( 'awpcp-ad-details', 'my_filter_handler' );

awpcp-featured-image-placeholder

Use it to filter the HTML markup for the featured image.

Parameters

• $html: The HTML markup for the featured image.
• $context: 'single' or 'listings' for Single Ad page and Listings page, respectively.
• $listing: The listing whose featured image is being filtered.

Usage

function my_filter_handler( $html, $context, $listing ) {
    // modify html here
    return $html;
}
add_filter( 'awpcp-featured-image-placeholder', 'my_filter_handler', 10, 3 );

awpcp-image-placeholders

Use it to filter an array of image-related placeholders. The available array keys are:

• featureimg/featured_image: The HTML markup for the featured image (Single Ad).
• awpcp_image_name_srccode: The HTML markup for the featured image (Listings Page).
• imgblockwidth/thumbnail_width: Width for thumbnail image, in pixels.

Parameters

• $placeholders: The array of placeholders.
• $listing: The listing being shown.

Usage

function my_filter_handler( $placeholders, $listing ) {
    return $placeholders;
}
add_filter( 'awpcp-image-placeholders', 'my_filter_handler', 10, 2 );

awpcp-listings-widget-listing-thumbnail

Fired when a listing item is being rendered inside a Widget. Use it
to filter the HTML markup of the listing's thumbnail.

Parameters

• $html_image: The markup of the thumbnail.
• $listing: The listing being rendered.

Usage

function my_filter_handler( $placeholders, $listing ) {
    return $placeholders;
}
add_filter( 'awpcp-listings-widget-listing-thumbnail', 'my_filter_handler', 10, 2 );

awpcp-file-associated-paths

This hook allow developers to modify an array of paths associated
to versions of a media item (image, attachment or video).

Parameters

• $paths: An array of absolute paths. Some of the files those paths point to may not exist.
• $media: The media item being deleted.

Usage

function my_filter_handler( $paths, $media ) {
    // do your stuff here
    return $paths;
}
add_filter( 'awpcp-file-associated-paths', 'my_filter_handler', 10, 2 );

awpcp-content-before-listings-page and awpcp-content-after-listings-page

Use to insert content before/after a list of listings.

Parameters

• $content: The content to be inserted.
• $context: The context where the listings are being rendered.

Usage

function my_filter_handler( $content, $context ) {
    // add your own content here
    return $content;
}
add_filter( 'awpcp-content-before-listings-page', 'my_filter_handler', 10, 2 );

awpcp-content-before-listings-pagination and awpcp-content-after-listings-pagination

Use to insert content before/after a pagination around a list of listings.

Parameters

• $content: An array with content to be inserted ($key => $priority).
  The array will be sorted by priority before the content is inserted.
• $context: The context where the listings are being rendered.

Usage

function my_filter_handler( $content, $context ) {
    // add your own content here
    return $content;
}
add_filter( 'awpcp-content-before-listings-pagination', 'my_filter_handler', 10, 2 );

awpcp-content-before-listings-list

Use to insert content before the list of listings, but after the top pagination block.

Parameters

• $content: The content to be inserted.
• $context: The context where the listings are being rendered.

Usage

function my_filter_handler( $content, $context ) {
    // add your own content here
    return $content;
}
add_filter( 'awpcp-content-before-listings-pagination', 'my_filter_handler', 10, 2 );

awpcp-listing-details-user-info

When the form used to post or edit a listing is being rendered, the plugin
gathers information about the current user or the owner of the listing. That
information is passed through this filter before the plugin uses it to populate
the form.

Parameters

• $user_info: An array with user info.
• $user_id: The ID of the user whose information is being gathered.

Usage

function my_filter_handler( $user_info, $user_id ) {
    // add your own content here
    return $user_info;
}
add_filter( 'awpcp-listing-details-user-info', 'my_filter_handler', 10, 2 );

awpcp-listing-url

Use it to filter a listing's permalink.

Parameters

• $url: The listing's permalink.
• $listing: An instance of AWPCP_Ad. The listing's whose permalink is being generated.

Usage

function my_filter_handler( $url, $listing ) {
    // do your stuff here
    return $url;
}
add_filter( 'awpcp-listing-url', 'my_filter_handler', 10, 2 );

awpcp-edit-listing-url

Use it to filter the URL to the edit page for a given listing.

Parameters

• $url: The URL.
• $listing: An instance of AWPCP_Ad. The listing's whose URL is being generated.

Usage

function my_filter_handler( $url, $listing ) {
    // do your stuff here
    return $url;
}
add_filter( 'awpcp-edit-listing-url', 'my_filter_handler', 10, 2 );

awpcp-delete-listing-url

Allows you to filter the URL that you can use to delete a listing. This URL is normally
equal to the Edit Listing URL.

Parameters

• $url: The URL.
• $listing: An instance of AWPCP_Ad. The listing's whose URL is being generated.

Usage

function my_filter_handler( $url, $listing ) {
    // do your stuff here
    return $url;
}
add_filter( 'awpcp-delete-listing-url', 'my_filter_handler', 10, 2 );

awpcp-listing-access-key

Fired when the listing's access key is being generated. The access key
should be a unique value for each listing, and it should always be the same
value for the same listing.

Parameters

• $access_key: The Access Key.
• $listing: The listing the access key is being generated for.

Usage

function my_filter_handler( $access_key, $listing ) {
    // do your stuff here
    return $access_key;
}
add_filter( 'awpcp-listing-access-key', 'my_filter_handler', 10, 2 );

awpcp-category-data

Filter the category data before it is stored in the database.

Parameters

• $category_data: An array with the category information that is going
  to be stored in the database.
• $category: An instance of AWPCP_Category. The object where the information
  was extracted from.

Usage

function my_filter_handler( $category_data, $category ) {
    // do your stuff here
    return $category_data;
}
add_filter( 'awpcp-category-data', 'my_filter_handler', 10, 2 );

awpcp-render-transaction-items

Filter the HTML markup used to show the transaction items.

Parameters

• $html: The HTML markup.
• $transaction: The transaction that is being currently shown.

Usage

function my_filter_handler( $html, $transaction ) {
    // do your stuff here
    return $html;
}
add_filter( 'awpcp-render-transaction-items', 'my_filter_handler', 10, 2 );

awpcp-categories-list-container

The HTML markup for the element that will contain the list of categories.

The markup must include a [categories-list] placeholder.

Parameters

• $container: The HTML markup.
• $options: Options array for the Categories List.

Usage

function my_filter_handler( $container, $options ) {
    // do your stuff here
    return $html;
}
add_filter( 'awpcp-categories-list-container', 'my_filter_handler', 10, 2 );

awpcp-category-shortcode-content-replacement

Use to completely replace the content of the Category shortcode.

Parameters

• $content: The content of page. If the value IS NOT null then a different
  filter handler already provided content replacement.

  Return null to let the plugin use the default content.

• $attrs: The shortcode attributes.

Usage

function my_filter_handler( $content, $attrs ) {
    // provide your own content here
    return $content;
}
add_filter( 'awpcp-category-shortcode-content-replacement', 'my_filter_handler', 10, 2 );

awpcp-login-form-implementation

Use it to provide a custom Login Form Implementation.

Parameters

• $implementation: NULL or an object that exposes a render() method like the
  one available in AWPCP_Default_Login_Form_Implementation.

Usage

function my_filter_handler( $implementation ) {
    // provide your own implementation here
    return $implementation;
}
add_filter( 'awpcp-login-form-implementation', 'my_filter_handler', 10, 2 );

awpcp-form-fields

Allow developers to register new Form Fields to be displayed in the Post Listing
and Serach Listings form.

Parameters

• $form_fields: An array of form fields definitions. The keys are the slugs of the
  fields and the values are the name of constructor functions (or factory functions)
  that can be executed to get an instance of a subclass of AWPCP_FormField.

  The constructor function will be called with the field's slug as it only paramater.

Usage

function my_custom_field_constructor_function( $field_slug ) {
    return new Subclass_Of_AWPCP_Form_Field( $field_slug );
}

function my_filter_handler( $form_fields ) {
    $form_fields['custom-field-slug'] = 'my_custom_field_constructor_function'
    return $form_fields;
}
add_filter( 'awpcp-form-fields', 'my_filter_handler', 10, 2 );

awpcp-render-form-field-{field-slug} and awpcp-render-form-field

Use it to modify the HTML markup of form fields used in the Post Listing
and Search Listing forms.

Parameters

• $content: The HTML markup.
• $field: The field being rendered. An instance of AWPCP_FormField.
• $form_value: The current field value.
• $form_errors: An array of error messages.
• $listing: The listing being edited or posted (if the field is being
  rendered in the Post/Edit Listing form).
• $context: Array with information about the context where the field
  is being rendered.

Usage

function my_filter_handler(  $content, $field, $value, $errors, $listing, $context  ) {
    // alter HTML markup here
    return $content;
}
add_filter( 'awpcp-render-form-field', 'my_filter_handler', 10, 6 );

Common Customizations

How to register custom form fields

Add a handler for the awpcp-form-fields filter (See register\_listing\_form\_fields method in class-listing-form-fields.php) and register a new field or replace the standard fields with your own custom implementations. The code to achieve that should be put in a custom plugin or the active theme's functions.php file, to ensure the modifications are preserved after upgrades.

Remember that custom form fields must be sub-classes of the AWPCP_FormField class or at least expose the same public methods.

How to add support for other payment gateways

Implementation

All payment gateways should extend class AWPCP_PaymentGatewayand implement at least the four methods described below:

• process_payment: called when the payment gateway is about to be used in a transaction. This is the method used to render the payment buttons in PayPal or 2Checkout payment gateways, and the Billing Form in PayPal Pro Direct Payment or Authorize.Net.
• process_payment_notification, process_payment_completed and process_payment_canceled: that are called when a notification is received for a transaction associated to the payment gateway, or when the user is redirected to the payment-completed and payment-canceled URLs.

Most payment gateways allow developers to specify a notify, return and cancel URL. Those are directly associated with the process_payment_notification, process_payment_completed and process_payment_canceled methods above, respectively.

You can use the following code to generate the URLs mentioned above, for a given transaction,

$payments = awpcp_payments_api();
$notify_url = $payments->get_notify_url($transaction);
$return_url = $payments->get_return_url($transaction);
$cancel_url = $payments->get_cancel_url($transaction);

The plugin will handle those URLs automatically and will take care of calling the right method in each case.

The implementation of the methods varies depending on the kind of integration you are trying to develop.

1. Integration by Payment Button (PayPal Standard or 2Checkout)

   1. process_payment: should print the payment button.
   2. process_payment_completed: called when the user returns to your website from the payment gateway's website, after having made a payment. The method should validate the information received and try to find out if the payment was successful or not, and update the transaction's payment status. This is how PayPal Standard payment gateway works; see payment-gateway-paypal-standard.php.
   3. process_payment_canceled: called when the user returns to your website after he or she cancelled the payment request. The method should update the payment status of the transaction.
   4. process_payment_notification: called every time a notification is received for a transaction that used your payment gateway. Similar to what process_payment_completed does, this method has to verify the information received and figure out the new payment status and update the transaction accordingly.

   After process_payment_completed or process_payment_canceled have been called, the plugin continues handling the payment transaction and will let the user post the listing, if the payment was successful, or show him an error, if the payment failed.

2. Integration by Custom Form (Authorize.Net)

   1. process_payment: should print the billing form, but also takes care of precessing the data entered, contacting the payment gateway's servers and consolidate the payment (update the transaction with a proper payment status).

      When you are done processing the payment, after you have updated the payment status of the transaction, call return awpcp_payments_api()->process_payment_completed($transaction); to let the plugin continue handing the transaction and allow the user to post the listing (if the payment was successful).

   2. process_payment_completed and process_payment_cancelled are usually implemented without a body (just a return; line), because the user is never redirected during the payment transaction.
   3. If the payment gateway supports notifications, the process_payment_notification method should be implemented as described in the Integration by Payment Button case.

Registering a payment gateway

Register an action for the awpcp-register-payment-methods hook. The callback will receive an instance of the Payments_API as its only argument. You should create an instance of your Payment Gateway and pass it to the register_payment_method method. For example:

public function register_payment_methods( $payments ) {
    $payments->register_payment_method( new AWPCP_PayPalStandardPaymentGateway );
}