wvega/customization-guide.md

## customization-guide.md

      
    Raw
  

              customization-guide.md
            
          
    AWPCP Customization Guide

Introduction

This document describes the general layout of the Another WordPress Classifieds Plugin directory as well as the contents of most of the files and directories 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 forum such as Upwork.
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 core, unmodified plugin in order to be considered issues we can address.
Before altering plugin files


Consider alternative ways to achieve what you want: Another WordPress Classifieds Plugin supports CSS customization and provides a lot of WordPress filters and actions you can hook into.


Avoid modifying plugin files unless absolutely necessary. You could end up breaking your site or losing information.
When you modifiy the plugin files, it becomes harder for us to provide support and for you to keep up with updates. If you need us to add more filters and actions to allow you achieve what you want without changing the plugin, let us know and we will consider your suggestion.


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, so if you forget about it, you’ll lose your changes!


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


            File/Directory
            Description
        
    
            awpcp.php
            The main plugin file. It sets everything up including loading the plugin's text domain, configuring rewrite rules and instantiating the Settings and Payments API's.
        
        
            cron.php
            Includes functions to schedule and handle the plugin's WP Cron events covering tasks such as peridocally clearing expired listings or sending notifiations for listings that are about to expire.
        
        
            functions.php
functions/*.php
            This file  include auxiliary functions used to validate and sanitize input data, generate URLs, send notifications, format listing's information among many other tasks.
        
        
            installer.php
            The plugin installer. All the routines executed during installation or upgrade are defined in this file.
        
    
Top level directories


            File/Directory
            Description
        
    
            admin/
            The classes used to render and process admin screens.
        
        
            frontend/
            The classes and functions used to render and process frontend screens. Plugin shortcodes are defined inside this directory.
        
        
            includes/
            Core classes and utility functions used in admin and frontend screens, ajax requests and cron requests.
        
        
            languages/
            All officially supported translations are stored in this directory.
        
        
            resources/
            Holds JavaScript, CSS and image files used to create the different plugin screens.
        
        
            templates/
            Holds *.tpl.php files used as templates to create admin and frontend screens and email messages.
        
    
admin/


            File/Directory
            Description
        
    
            form-fields/
            Code used to render and process screens for Classifieds > Form Fields submenu.
        
        
            profile/
            Code used to render profile fields and to save the information entered by the user back to the database.
        
        
            templates/
            Template files used in admin screens only. If the template you are looking for is not in this directory, please check /templates/admin/ as all templates for admin screens will be gradually moved to that directory.
        
        
            admin-panel*.php
            Code used to render and process admin screens available under the Classifieds menu. Typically a file for each screen.
        
        
            user-panel*.php
            Code used to render and process admin screens available under the Ad Management menu. Typically a file for each screen.
        
    
frontend/


            File/Directory
            Description
        
    
            templates/
            Template files used in frontend screens only. If the template you are looking for is not in this directory, please check /templates/frontend/ as all templates for frontend screens will be gradually moved to that directory.
        
        
            page-*.php
            Class definition for the different plugin pages. Each files contains the code to handle the shortcode that generates that page.
        
        
            placeholders.php
            Definition for the placeholders that can be used in the Listings page layout and Single page layout settings.
        
        
            shortcode.php
            The class responsible for registering all shortcodes available in the plugin.
        
        
            widget-*.php
            Class defintion for widgets.
        
    
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.

    
            File/Directory
            Description
        
    
            compatbility/
            
                Definition of classes and functions that provide automatic integration between AWPCP and other plugins such as:
                
                    Add Meta Tags
                    All In One SEO Pack
                    Content Aware Sidebars
                    Facebook
                    Facebook All
                    WordPress SEO
                
            
            form-fields/
            The Form Fields API. In AWPCP 3.5 and newer versions, all fields shown in the details form are represented at runtime by an instance of the `AWPCP_FormField` class. This directory include class definition for all standard form fields, such as `AWPCP_ListingsContactNameFormField`, and the definition of the classes that register and transform those fields into the HTML form users see and interact with.
        The Extra Fields module uses this API to register extra fields at runtime. You can use thi API too, If the form fields available in the plugin or the Extra Fields premium module are not what you need, you can create your own fields and register them with the API without having to modify any of the plugin files (See <strong>How to register custom form fields</strong>).</td>
    </tr>
    <tr>
        <td><code>functions/</code></td>
        <td>Several PHP files that define utility functions gruped by purpose.</td>
    </tr>
    <tr>
        <td><code>helpers/</code></td>
        <td>Helper classes used for a variaty of tasks, from sending listings information to Facebook to Build the page's title using current listing's information to check listing's content against spam filters, among others.</td>
    </tr>
    <tr>
        <td><code>settings/</code></td>
        <td>Defintion of classes responsible for registering and validating plugin settings.</td>
    </tr>
    <tr>
        <td><code>upgrade/</code></td>
        <td>Definition of classes that represent manual upgrades. Manual Upgrades are potentially expensive routines that the plugin sometimes asks users to run after a new version is installed. These tasks are designed to process the necessary information in steps, triggered by ajax from the Manual Upgrade admin screen.</td>
    </tr>
    <tr>
        <td><code>payment-gateway-*.php</code></td>
        <td>The base class for payment gateways and the implementation of the PayPal Standard and 2Checkout payment gateways. See <strong>How to add support for other payment gateways</strong>.</td>
    </tr>
    <tr>
        <td><code>payment-term-*.php</code></td>
        <td>The base class for payment term types and definition of the default payment term type: Feee.</td>
    </tr>
    <tr>
        <td><code>settings-api.php</code></td>
        <td>The class the we use to integrate plugins settings with WordPress Settings API.</td>
    </tr>
</body>


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:

    
            File/Directory
            Description
        
    
            frontend/templates/email-*.tpl.php
templates/email/*.tpl.php
            
                The templates used to generate the body for the email messages sent by the plugin.
            
        
            frontend/templates/login-form.tpl.php
            The login form shown to anonymous users before they are allowed to post a listing.
        
        
            frontend/templates/login-form.tpl.php
            The menu shown above the list of listings in all plugin pages.
        
        
            frontend/templates/page-*.tpl.php
            Used to render different states of the plugin pages.
        
        
            frontend/templates/payments-*.tpl.php
            Used to render different common HTML components related to payments. The payment methods and payment terms tables are examples of suchs components.
        
        
            frontend/templates/widget-*-form.tpl.php
            The template used to render the widget's settings form shown in the admin when a user is adding a a widget to the sidebar.
        
        
            templates/frontend/form-fields/*.tpl.php
            The templates used to render the standard form fields shown in the listing' details form.
        
        
            templates/frontend/listings.tpl.php
            The HTML markup around the list of listings. This template is used to show the list of listings in the main Classifieds, Browse Ads/Categories and Search Listings pages.
        
    
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.

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.


Integration by Payment Button (PayPal Standard or 2Checkout)

process_payment: should print the payment button.
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.
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.
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.


Integration by Custom Form (Authorize.Net)


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).


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.


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 );
}
File/Directory	Description
`awpcp.php`	The main plugin file. It sets everything up including loading the plugin's text domain, configuring rewrite rules and instantiating the Settings and Payments API's.
`cron.php`	Includes functions to schedule and handle the plugin's WP Cron events covering tasks such as peridocally clearing expired listings or sending notifiations for listings that are about to expire.
`functions.php` `functions/*.php`	This file include auxiliary functions used to validate and sanitize input data, generate URLs, send notifications, format listing's information among many other tasks.
`installer.php`	The plugin installer. All the routines executed during installation or upgrade are defined in this file.
File/Directory	Description
`admin/`	The classes used to render and process admin screens.
`frontend/`	The classes and functions used to render and process frontend screens. Plugin shortcodes are defined inside this directory.
`includes/`	Core classes and utility functions used in admin and frontend screens, ajax requests and cron requests.
`languages/`	All officially supported translations are stored in this directory.
`resources/`	Holds JavaScript, CSS and image files used to create the different plugin screens.
`templates/`	Holds `*.tpl.php` files used as templates to create admin and frontend screens and email messages.
File/Directory	Description
`form-fields/`	Code used to render and process screens for Classifieds > Form Fields submenu.
`profile/`	Code used to render profile fields and to save the information entered by the user back to the database.
`templates/`	Template files used in admin screens only. If the template you are looking for is not in this directory, please check `/templates/admin/` as all templates for admin screens will be gradually moved to that directory.
`admin-panel*.php`	Code used to render and process admin screens available under the Classifieds menu. Typically a file for each screen.
`user-panel*.php`	Code used to render and process admin screens available under the Ad Management menu. Typically a file for each screen.
File/Directory	Description
`templates/`	Template files used in frontend screens only. If the template you are looking for is not in this directory, please check `/templates/frontend/` as all templates for frontend screens will be gradually moved to that directory.
`page-*.php`	Class definition for the different plugin pages. Each files contains the code to handle the shortcode that generates that page.
`placeholders.php`	Definition for the placeholders that can be used in the Listings page layout and Single page layout settings.
`shortcode.php`	The class responsible for registering all shortcodes available in the plugin.
`widget-*.php`	Class defintion for widgets.
File/Directory	Description
`frontend/templates/email-.tpl.php` `templates/email/.tpl.php`	The templates used to generate the body for the email messages sent by the plugin.
`frontend/templates/login-form.tpl.php`	The login form shown to anonymous users before they are allowed to post a listing.
`frontend/templates/login-form.tpl.php`	The menu shown above the list of listings in all plugin pages.
`frontend/templates/page-*.tpl.php`	Used to render different states of the plugin pages.
`frontend/templates/payments-*.tpl.php`	Used to render different common HTML components related to payments. The payment methods and payment terms tables are examples of suchs components.
`frontend/templates/widget-*-form.tpl.php`	The template used to render the widget's settings form shown in the admin when a user is adding a a widget to the sidebar.
`templates/frontend/form-fields/*.tpl.php`	The templates used to render the standard form fields shown in the listing' details form.
`templates/frontend/listings.tpl.php`	The HTML markup around the list of listings. This template is used to show the list of listings in the main Classifieds, Browse Ads/Categories and Search Listings pages.