“Sofa Front Post -WordPress plugin” Documentation by “Dameer DJ” v1.0


“SOFA Front Post - WordPress plugin”

Created: December, 29, 2012
By: Dameer DJ
Email: dameer@presswordthemes.com

Thank you for purchasing my plugin. If you have any questions that are beyond the scope of this help file, please feel free to email via my user page contact form here. Thanks so much!


Table of Contents

  1. Introduction
  2. Requirements
  3. Install SOFA Front Post
  4. Plugin pages setup
  5. How things should work
  6. Plugin Templates and Hooks
  7. Plugin Shortcodes
  8. Plugin Widgets
  9. Credits

A) Introduction - top

Sofa Front Post is WordPress plugin that will turn any WP theme into classified ads web site. As such it allows visitors to publish their entries via site’s front-end submission form.
On the other side, site owners may charge people for publishing ads and thus run profitable business. Of course, it’s not a must but rather an option. PayPal account will be required in that case!


B) Requirements - top

Before you decide to install and use this plugin be sure that the following tech requirements are met:


C) Install SOFA Front Post - top

The very first thing you should do is to install this plugin. So login to WordPress Admin section (Dashboard) then select:

Plugins > Add New >> Upload

...then Browse to ZIP file downloaded from your Codecanyon account and hit "Install Now" button.
Plugin will install automatically.


D) Plugin pages setup - top

After you install Sofa Front Post you’ll have to create 8 pages that will exclusive be used by a plugin! These pages are MUST and without them your plugin can’t work.

Required pages are nothing but common WordPress pages so go ahead and create first one:

Dashboard, Pages > Add New (remember: you’ll do the same for each next page!)

It is important to switch text editor from Visual to HTML mode before you continue!


1. Add New Entry page

This page is supposed to render New Entry submission form so enter an appropriate title, like "Add New Entry".

As for the content, paste the following shortcode:

[sfp_form]

Publish your first page!


2. Edit Entry page

Because users will probably want to edit their entries occasionally, corresponding page is required. Add new page with the title like "Edit your Entry".

Paste the following shortcode into content area:

[sfp_edit]

This will render Entry edit form on front-end automatically. Publish your second page!


3. User Entries archive page

Each registered user will be able to manage Entries from this page; edit, delete, make payment or renew expired entries. The following title could be used as appropriate one: "Your Entries Archive".

Paste this shortcode into content area:

[sfp_list]

Publish page!


4. Make Payment page

Whenever payment is about to be done by user, this page will handle all the details required by payment gateway. Enter the title like "Make Payment" and simply...

...paste the following shortcode into content area:

[sfp_payment]

Plugin will take care about the rest. Now Publish your payment page!


5. Payments History page

Each valid and accepted user payment will be recorded. It may be used as an evidence in case of eventual conflict/disagreement between you (as a site owner) and site user. An appropriate title for this page could be "Your Payments History"

Paste this shortcode into content area:

[sfp_transactions]

Don't forget to Publish this page too!


6. User Login page

This page handles login, new user registration and password reset procedure. It means that user will never have to get WordPress default login/registration/password_reset form. Title this page with something like "User Login"

and paste the following shortcode into content area:

[sfp_login]

Publish User Login page!


7. Search results page

Sofa Front Post plugin is using different kind of search so WordPress' default one is not of great help. The following page title will be all right: "Search Results"

As for the shortcode, this one comes with an exception!

[sfp_search show_search_form=no]

As you may note the above shortcode has an additional attribute show_search_form=no. It will tell your search page whether to display search form on top of search results or not.

By default search form will be displayed so use show_search_form=no attribute only in case you want to remove it!

Now Publish search results page!


8. Entries Archive page

If no attributes provided this page lists all user entries sorted by date in descending order. Suggested title may be something like "Entry Archives"

Here's the shortcode to be pasted - decide which attributes you need:

[sfp_archives cat_id=NN,NN,NN,...,NN per_page=NN]

cat_id=NN,NN,NN,...,NN - one or more categories to filter user entries from. Must be comma separated if multiple!

per_page=NN - number of entries to be listed per page

Publish your last plugin required page!


TIP: If you want to add some text above or below shortcode across plugin pages - that's fine, but be sure to always leave one empty/blank line above shortcode if text is added before or one empty line below shortcode if text is added after shortcode!

Assign plugin pages

Now, after all plugin required pages are created, assign each page to appropriate "slot". From Dashboard select

SFP Posts > Manage Options >> Plugin Pages

You'll notice that the last "slot" is reserved for Terms and Conditions page. Although that page doesn't use shortcode it's recommended that you create this page too and make an assignment, especially if you are about to force users to accept terms and conditions prior to making payment.
Save Changes once done!



E) How things should work - top

How does the plugin work indeed? Well, if you ever heard about Yellow Pages then everything should be clear enough. According to selected operable model people will be able to publish ads in one of predefined categories (predefined by site Admin).

You can now create a couple of test categories if you like. Categories can be set hierarchically if you prefer such structure.
Dashboard, SFP Posts > SFP Post Categories
Beware, people are not allowed to create new categories, you'll have to predefine them all! It's not necessary to do it right now, feel free to append new categories anytime you like.

Site owner can charge for publishing, let users publish for free or let them pay sponsored fee in case they want better positioning on ads listing or search results page.
Sponsored ads will always be listed on top regardless the publish date!

For better control ads don't get status of "publish" as long as content is revised by Admin. Of course, that's just one of the options! If you feel comfortable with immediate publish - enable from plugin settings page.

All due-to-pay ads are held in quarantine until payment is made and as such they will not be listed!
Due-to-pay entries are also deleted automatically after predefined period of time (plugin settings) in order to unclutter your database.

Optionally, ads may expire after certain period of time - if set so by site Admin.
Expired ads will not be listed as well! As soon as certain ad gets expired, notification is sent to ad holder automatically. Ad owners will either have to renew it or delete permanently.

Payments are handled by PayPal so if you decide to monetize this plugin be sure to have a valid PayPal account!

That should be it - briefly.


Operable Models explained

From Dashboard select:

SFP Posts > Manage Options >> Payment Settings

The very first option "Select operable model..." will let you pick plugin's mode. As you can see there are 3 possible operable models:


Users don't pay for publishing

It should be quite clear that if running your plugin in this mode each new Entry will be published free of any charge. There will be no option for users to make their Entries sponsored and thus improve search results ranking or get their ads closer to the top on category page.

All entries will be sorted by date in descending order.


Users pay for publishing

With this model selected users will need to pay for each Entry added. Optionally, users can decide whether to pay sponsored entry fee as well (on top of the regular publish price). Sponsored Entry will always be on top of category page and search results.

Both sponsored and regular entries will be sorted by date, however, sponsored ones will always proceed regulars regardless the date of publish!


Users may select

This option represents some sort of mix between two already mentioned models. By default Entries are published for free but users may opt for sponsored Entry and thus benefit whenever it gets to ads listing.

Remember, sponsored entries will always be on top of category and search results page regardless the date of publish!


TIP: Users will always be able to pay sponsored fee subsequently from their Entries management page.

Entry Statuses explained

Status: Pending

The very first thing that will have an impact on Entry status is what you decided to do with each new user Entry.
Check out which option is currently active:

SFP Posts > Manage Options >> User Permissions : New user entry is saved as

a) Auto-publish
...or...
b) Pending

If Pending, Entries will be held in queue until published by site Admin itself. Otherwise, Admin has a chance to open each pending Entry, revise content and decide whether to publish or not.


Status: Publish

If Auto-publish, each new Entry will be published immediately! It might lead to publish of unwanted or offending content so think twice before allowing this option.

Entry status will also depend on operable model selected and if expiration time set to certain number of days (greater than zero). Check out first two options of plugin settings page:

SFP Posts > Manage Options >> Payment Settings

Now let's see how "Select operable model..." and "Make user Entries expire after" options affect Entry status...


Status: Due-to-pay

Whenever operable model is not set to "Users don't pay for publishing", payment may occur. It could either be a regular entry publish fee or sponsored entry fee (or both!).

So whenever payment is required Entry status will be "due-to-pay" until payment resolved!

Once resolved, Entry status becomes "Publish" or "Pending" and depends on how each new Entry is saved (see option "New user entry is saved as").


TIP: All "due-to-pay" Entries will be deleted automatically after NN hours where NN is the number of hours defined in plugin settings page. See:
SFP Posts > Manage Options >> Payment Settings : Delete all "Due to pay" Entries after

Status: Expired

If "Make user Entries expire after" option is set to any number greater than zero all published Entries whose date of publish + the number of expiration days exceeds today's date will become expired.


TIP: Status switch will happen automatically! As soon as user Entry is identified as expired e-mail message (notification) is sent to entry owner. After that owner needs to either renew or delete expired entry otherwise an expiration notice is sent repeatedly!


F) Plugin Templates and Hooks - top

WordPress uses query string to decide which template or set of templates will be used to display the page. This plugin has all the necessary templates to display content properly and that's why it can be used with any theme. You can find these templates in folder named "templates". Path to template files should by default be:

wp-content/plugins/sofa-front-post/templates

Inside that folder you gonna be able to find 3 files:

Copy and paste these templates to the root of your theme! Whenever you have to edit any of them, you'll edit copies that reside in theme's root folder rather than originals.
Keep reading in order to find out in which case and how to edit these files safely.

Template Hooks

Template hooks are functions. They contain code that can be reused in templates simply by calling function name.

First of all you need to know where to find template hooks (functions) in case you need to edit something. There's a file named "custom_functions.php" which can be found in following location:

wp-content/plugins/sofa-front-post/include/custom_functions.php

Five basic hooks are used across templates to handle content appearance:

1. sfp_template_wrap_begin( $pre_wrap )

- lines: #6 thru #9

2. sfp_template_wrap_end( $post_wrap )

- lines: #10 thru #13

These two are so called wrapper hooks and are used to wrap the rest of the content.

Each hook accepts one argument which is usually opening and closing tag. For instance:

sfp_template_wrap_begin( '<div class="my-content-wrapper">' );
// loop
sfp_template_wrap_end( '</div>' );

Whenever sfp_template_wrap_begin() is "opened" in template, sfp_template_wrap_end() MUST BE there to "close it"!

You need to know that each WordPress theme uses one or more DIV elements to wrap the content. These DIV elements may contain one or more classes (and/or ID) as well.
Be sure to pass correct data to sfp_template_wrap_begin() and sfp_template_wrap_end() functions.


3. sfp_single_template_content()

- lines: #17 thru #211

This hook is used to render Entry single page and all the content "attached" to this page like: title, contact details, GoogleMaps, entry text, images, contact form and related entries.
4. sfp_category_template_content()

- lines: #217 thru #374

Whenever certain category is requested by WordPress query string this hook will be triggered and all Entries published in this very category show up on page. Essentially this is custom WordPress loop.
5. sfp_tags_template_content()

- lines: #380 thru #537

It's almost identical to previous hook (#4) but comes with a little exception: this one displays all Entries that share selected tag/keyword.
TIP: Don't edit any of above mentioned functions unless you know how and what to do, PHP and WordPress API knowledge is a must. One single mistake might lead to plugin dysfunctionality.


G) Plugin Shortcodes - top

Sofa Front Post has several handy shortcodes that can be inserted to any page. Avoid on-page redundancy because some of them are server resources intensive!

Latest Entries

This shortcode is supposed to make the list of latest Entries according to attributes provided. If no attributes provided it'll act as a regular Entries archive.

[sfp_latest cat_id=NN,NN,...,NN num_entries=NN offset=NN show_images=no show_tags=no]

Shortcode attributes:

cat_id=NN,NN,...,NN - one or more category IDs (separated by comma if multiple) that you want to list Entries from

num_entries=NN - number of listed Entries per page

offset=NN - exclude first NN entries from the list

show_images=no - don't display entry featured image next to contact details

TIP: It's not necessary to use "show_images=yes" explicitly because featured image will be shown by default!

show_tags=no - don't display entry tags

TIP: It's not necessary to use "show_tagss=yes" explicitly because Entry tags will be there by default!

Categories

The following shortcode can be used to make the list of all categories used by a plugin.

[sfp_categories hide_empty=1 include_children=no]

Shortcode attributes:

hide_empty=1 - if this attribute provided categories that do not contain published Entries will not be shown!

TIP: This attribute can only accept 1 or 0. It's not necessary to use "hide_empty=0" explicitly because empty categories will be included by default!

include_children=no - use this attribute in case you like to exclude child categories from the list

TIP: It's not necessary to use "include_children=yes" explicitly because child categories will be included by default!

Search Form

This shortcode can be used to insert advanced search to any page. No attributes available for it yet!

[sfp_search_form]

H) Plugin Widgets - top

Currently, Sofa Front Post plugin is equipped with 3 Widgets. Maybe there will be more in future releases of this plugin - it depends on further development. Let's see if there's anything you should know about, say when or where to use...

SFP Related Businesses

As you probably know, categories may use hierarchy. This helps you group 2 or more businesses that are actually considered as children of the main business. That's how you enable users to pick more descriptive or appropriate category by adding new Entry.

This widget will check whether currently selected category has child categories and display them all.

TIP: Place this widget in sidebar of "taxonomy-sfp_post_category.php" template file. If you place it elsewhere it won't score any results because it only checks for current taxonomy.

SFP Search

This Widget is supposed to show up Search form that can only be used to search user ads.

Feel free to place this Widget in sidebar of your choice.


SFP User Menu

Site visitors who are not signed-in will only see a login link. For a case user is logged in, this Widget will show all the user profile relevant links; logout, user Entries archive, add new Entry and payments history.

Feel free to place this Widget in sidebar of your choice.


I) Credits - top

Sofa Front Post plugin uses a couple of icons from 2 different iconsets. Here are the credits for both!


"Wireframe mono icons" by Gentleface.com

License: Creative Commons (Attribution-Noncommercial 3.0 Unported)

downloaded from: http://www.iconfinder.com/search/?q=iconset%3Acc_mono_icon_set


"Retina Display Icons" by The Working Group

License: Creative Commons (Attribution-Noncommercial 3.0 Unported)

downloaded from: http://www.iconfinder.com/search/?q=iconset%3ATWG_Retina_Icons


Once again, thank you so much for purchasing this plugin. As I said at the beginning, I'd be glad to help you if you have any questions. No guarantees, but I'll do my best to assist. If you have a more general question relating to the plugin on Codecanyon, you might consider visiting the forums and asking your question in the "Item Discussion" section.

Dameer DJ

Go To Table of Contents