Add-on Classifieds addon development discussion

[Stuart Wright]

I'm organising the development of a classified adverts addon for Xenforo.
For those people who don't know me, we've been running classifieds on AVForums on Xenforo since 2013 using several addons written by @Chris D (not released here through lack of time) and for many years on vBulletin before that. We have vast experience running classifieds.

I've started this thread in order to get input from the community. The Classifieds addon will be sold in the resource manager and I want to ensure that the functionality is generic enough to cater for the majority of peoples' requirements. But at the same time keep it as simple as possible in keeping with Xenforo.

Please reply below with your input.

Key points
Associated threads
By default, discussion threads are created for every advert when it goes live. There is an admin option to allow advertisers to choose not to have a discussion thread.

Adverts with discussion threads use the Xenforo tab system to have an Advert tab and a Discussion tab. Maybe also a Map tab if it’s easy enough. Is a Media tab necessary if the advertiser wants to embed images and/or video and/or attachments in the advert text?

Post #1 of the advert thread contains a summary of the advert and is indexed by the search engine to help return classifieds in the search results. This is NOT editable by the owner. Only moderators. If the owner wishes to change the text, they must edit their advert. Updating the advert updates the first post of the thread.

Advert data is stored in separate tables linked to the thread by the thread ID.

There will need to be some forums set up for the classifieds addon:

• The forum(s) which host the live adverts. A busy forum will require several classifieds forums to separate the adverts for different categories of goods (E.g. Xbox One Games, PS4Games). A quieter forum might have just one classifieds forum initially.
• An Archive Forum to host archived, In Dispute and Dispute Resolved ads

Customisable fields
There are standard advert fields and also additional admin defined advert fields to customise the adverts as admin desire.

Categories
Each advert has a product category, and each category is associated with a forum in which the discussion thread is created. Categories are types of product (E.g. Video Gaming, Xbox One, Xbox One Games) and have a hierarchical structure.

Packages
Each advert has a cost package which the owner of the advert chooses. The package determines the nature of the advert and how much the owner pays to place the advert. Free adverts, for example, would have fewer features available. Admin set up the available packages.

Key attributes
There are five fundamental advert attributes

1. Category
2. Status (Draft / Live / Archived (includes In Dispute and Dispute Resolved))
3. Advert Type (For Sale/Exchange/Wanted)
4. Condition (New/Used)
5. Advertiser Type (Private/Dealer)

3-5 are shown as flags/ribbons/banners against the adverts.

Search tab
There will be a classifieds search tab so that people can search classifieds. Also the quick search box will default to search classifieds when on a classifieds page.

Location
The advertiser’s location will be one of the core advert fields and we use Google Maps to show that in a MAP tab of the advert. The location can be a post/zip code or a city/town name. The advertiser picks their Location from the map when placing the advert. Google’s map functionality can use the person’s location from geo functionality of the device being used. We recommend that people choose an approximate location for security purposes. Post/zip code should be approximate enough. Google’s functionality can be used to get the country, city, town/area from the post code entered and we should use that in the search functionality.

Trader ratings
Full trader ratings system. This is a significant chunk of functionality in itself with an importer from the Xencentral trader ratings system. Possibly also an importer from the main vB trader ratings system.

Sidebar widget
On all classifieds pages, there will be a sidebar. This can be a ‘built-in’ sidebar or one which uses the [bd] Widgets Framework addon. Admin chooses and also choses whether it’s on the left or right. In both there will be widgets like on XMG to filter ads by category, type (For Sale/Exchange/Wanted, New/Used, Private/Dealer) etc. Spotlight adverts are shown in a side scrolling widget.

Standard Xenforo features included

• Tags
• Watch functionality with filters enabled. I.e. someone sets up the key filters and can then watch that combination.
• Like adverts
• Share adverts
• News Feed
• Reporting adverts
• Warnings for adverts
• Moderators for categories
• Moderation queue (for paid ads?)
• Sitemap inclusion

Reports
There will be various reports.

Possible planned future functionality
Auctions
Adverts can run as classifieds where people negotiate (in an associated thread) or as an auction where people bid in the same way as they do on ebay.

 

[Stuart Wright]

Admin setup & options
This is draft and will undoubtedly be refined.

• URL path. Default ‘classifieds’.
• Category setup. Define the categories and their structure. This will include defining which forum corresponds to each category. A category may not have a corresponding forum as it may be for hierarchical (parental) purposes only, in which case, adverts may not be created using that category (only its children).
• Select the forum for archived adverts
• Option: Enable Advert type
• Option: Enable Condition
• Option: Allow adverts from dealers (no by default). Requires a dealer usergroup to be set up to allow admin to identify dealers. Enables the Advertiser type (Private / Dealer) functionality. In the UK at least, it is illegal for commercial organisations to advertise goods privately. I.e. they must declare that they are a commercial organisation because they are subject to distance selling laws. So there are stern punishments for dealers who place private ads.
• Thread prefix selector. Based on what of the above are enabled, choose which prefix to use for adverts threads
  • Advert Type (default) (For Sale / Exchange / Wanted)
  • Condition (Used / New)
  • Advertiser Type (Private / Dealer)
  • None
• Option: Enable trader ratings (yes by default)
• Option: Enable Contact details (yes by default). Mobile phone, landline phone, email and postal addresses, Skype and other online contact details. There may (in the UK at least) be a data protection issue with storing this information.
  • Option: Require contact details (no by default). For security purposes, it may be desirable to require advertisers to enter their contact details before they can place their first advert. This means their postal address plus at least one phone number.
  • Option: Store contact details for reuse (yes by default). The system will store their contact details to be used as a default each time they create an advert. There is potentially a data protection ramification (in the UK at least) if this is used.
• Set up custom user profile fields for use by the classifieds system. Define which ones are contact details if contact details are enabled.
• Set up packages. These define what cost types the adverts have including free adverts. The packages are available to specific usergroups.
• Set default advert list view – grid (default) or list.
• Option: Require numeric asking price on For Sale adverts (default no).
• Option: Require user’s age to be over 18 to use the classifieds (default no). We use their DOB in their profile to determine this.

In addition it’s advisable to set up a classifieds rules, terms and conditions text page.

 

[Stuart Wright]

Classifieds home page
Using an admin definable route defaulting to /classifieds, the classifieds home page lists the newest ads from all categories. It uses a sidebar layout in a very similar layout to XMG. The sidebar widget displays ads of various categories/new ads/watched ads.

Grid view or list view. Grid view will be like XMG. List view will be similar to thread lists.

The primary image of adverts will be key here to create a pretty design.

All the key filter information must be shown against all ads.

Featured ads are shown stuck to the top of the list.

Spotlight ads are shown in a sidebar slider entitled Classifieds Spotlight. (more about this below).

This is how Gumtree looks.

https://www.gumtree.com/search?q=sa...s-plasma-lcd-tvs&search_location=&distance=30

showing the newest at the top, grouped by Featured ads first (like sticky threads) then the rest.

There needs to be a method of choosing the filters and sort order.

 

[Stuart Wright]

Category data
This is a guideline only.
Categories are product types and are set up in the admin area with a parent/child hierarchy. E.g. Video Gaming -> Xbox One -> Xbox One Games.

• Category ID
• Parent Category ID
• Category Name
• Category Description
• Forum ID
• Cached number of live ads?

Categories have an organisational hierarchy so that users can navigate down to the appropriate category when placing and searching for ads. Some parent categories might exist for organisational reasons only and not have a corresponding forum. (The equivalent of categories in the forum hierarchy).

In this case, the associated forum field will be left blank and users can’t pick this category for their advert. Categories are associated with forums so that when someone makes an advert live, the advert’s thread is automatically created in the associated forum.

The link between categories and forums needs to be maintained. If a forum is deleted, then admin need to manage what happens to the category and adverts associated with that forum.

Similarly if the forum associated with a category is changed, then all the adverts in that category will need to be moved to the new forum. The owners of all the adverts will need to be sent an alert telling them their advert has been moved.

Once an advert has been made live, editing its category (either by the owner or admin) will move the thread to the forum corresponding to the new category.

 

[Stuart Wright]

Advert data

• Advert ID
• Advertiser (user ID)
• Category ID – each product type (e.g. Xbox Games) has a separate category ID. Categories are set up in the admin page.
• Advert Type (For Sale / Exchange / Wanted – matches the thread prefix)
• Condition (New/Used)
• Advertiser Type (Private/Dealer)
• Title
• Text
• Location (could be Google maps driven?)
• Currency
• Price (text field for OFFERS etc.)
• Creation datetime
• Thread ID
• Status: Draft / Live / Archived / In Dispute / Dispute Resolved
• View count

Custom fields
Additional fields can be created by the custom fields functionality. Fields can be displayed above or below all the standard advert fields and are of two types – formatted text and input fields.

Some field dependencies will be required. I.e. fields are only used when the core data (e.g. Category, Advert Type, Condition, Advertiser Type) or other custom fields have certain values. There will need to be a category picker, for example, if a field is dependent upon the category.

An example on AVForums is the Delivery custom field. This is available in the For Sale and Exchange ads types and has radio button options for the preferred delivery type.

Some custom fields will be required, others not.

Custom field types will be the usual field types which admin can select. Also need varchar(255) types designated for image URLs
E.g. For Mobile phones only, an image of the mobile phone and a their user name written on a piece of paper next to it to verify the phone is theirs and in their possession.
and also links
E.g. To where the product was originally purchased, or manufacturer's warranty information.

Images
There will also need to be associated images.

The user can attach images and can also use the tag to embed them into the advert text.
One of the attached images will need to be designated the thumbnail image which is what gets displayed as part of the advert listing and when the ad is shown in the Spotlight widget etc.
By default this is the first attached image.

 

[Stuart Wright]

Advert Status

The standard statuses are DRAFT -> LIVE -> ARCHIVED

If a trade goes south then we change the status to IN DISPUTE and then if resolved -> DISPUTE RESOLVED

At all times the status of the advert is displayed prominently to its owner.

Changes to an advert’s status are recorded in a log which the owner and admin can view for each advert.

Permission is needed to create adverts. Optionally we can restrict creation of adverts to members who are over 18 years of age (recommended since minors may not enter into a legally enforceable contract).

Draft
All adverts are created as DRAFT and are only visible to the owner and admin. At any point an advert which is DRAFT can be cancelled. This removes all traces of the ad.

Once all the required fields have been entered, the PUBLISH ADVERT button becomes available on DRAFT adverts to those people with permission.

Publishing an advert

· Activates the payment process if the advert has chargeable options. If the payment process fails then the advert cannot go live.

· Creates a thread in the appropriate forum or undeletes it if one exists but is soft deleted. If the thread is not created successfully, the advert cannot go live.

· Changes the advert status to LIVE.

Live
Once published, advert owners may not change LIVE ads back to DRAFT, but a moderator can.

Moderators who find an advert which breaks the rules should change the status to DRAFT so the member can amend it to comply with the forum rules. A reason for the status change is required to be entered by the moderator and is both stored in the status history of the advert and sent to the member as an alert. This also soft deletes the associated thread.

Live ads have an ARCHIVE ADVERT button for those people with permission. Typically ad owners and moderators can archive an advert.

Archiving undeleted a thread if it is soft deleted and moves the thread into the archive forum.

Archived
Adverts may be automatically archived according to the chosen package. A package which sets an advert lifetime of 30 days will mean the advert get archived at the end of the 30th day.

Alerts sent to the owner to let them know a set number of days in advance that their advert will be archived and again once it has been archived.

Permission is needed to see threads in the archive forum. (Admin may want to disallow guests in order to stop the indexing of archived ads by search engines)

Permission to reply to archived threads is set in the usual permissions, but is normally restricted to the members who have already posted in the thread and moderators.

Archiving an advert requires a reason, which is entered in a modal. This reason is then posted as a reply to the thread so there is a public record of when it was archived and by whom (including when it is automatically archived).

If the deal falls through, the advertiser (or moderator) can RELIST the advert.

Relisting an advert requires a reason via a modal which is then automatically posted as a reply to the thread.

Relisting changes the status back to LIVE and moves the thread back to the appropriate forum (according to the category).

In Dispute
If admin decides to allow moderator mediation of disputed trades, we will also need the In Dispute and Dispute Resolved statues.

When a trader reports an advert as being in dispute, a moderator has the ability to change its status to IN DISPUTE. Ads can be changed to IN DISPUTE from LIVE or ARCHIVED.

A reason for the advert going IN DISPUTE is given via a modal and posted as a reply to the thread.

The disputed ad threads are moved to the Archive forum if not already there and can be replied to by all participants of that thread.

In Dispute ads are viewable only by admin and the people who posted in them.

Dispute Resolved
Once a disputed ad is resolved, a moderator changes its status to DISPUTE RESOLVED.

So all adverts end with having a status of ARCHIVED, IN DISPUTE (where disputes are never resolved) or DISPUTE RESOLVED. This means we can report on how many disputed ads there are, and look at the traders with disputes resolved and not.

 

[Stuart Wright]

Placing/editing ads

This is the first draft and intended as a guideline only. The developer will need to use considerable discretion.

Users need appropriate permission to place new adverts. If they do not have permission, then the reason needs to be clearly stated.

If the minimum age of 18 option is set then if the user’s DOB is empty or puts them under 18 then they may not post adverts.

To post a new advert, you can either click a ‘Post New Advert’ button from the classifieds home page or navigate to the appropriate forum and click the ‘Post New Advert’ button there (we will need custom text for the Post New Thread button).

Advert creation page
The advert creation page looks similar to a standard thread creation page with the addition of some fields and explanatory text.

1. If the user already has existing adverts, then a link to see that list of adverts needs to be displayed at the top of the page. This will open a paginated modal window of existing adverts with links to open each advert thread.

2. The user must first choose the category for their new advert. The hierarchy of categories is presented with each level as a separate drop-down menu starting with the top level on the left (or right for RHS languages) and then working down through the hierarchy. E.g. Gaming > Xbox One > Xbox One Games. When starting new advert from within a forum, if that forum has more than one associated category, then the user must pick which category from a drop-down list. Otherwise the single category associated with that forum is selected automatically.

3. Choose advert type (FOR SALE / EXCHANGE / WANTED)

4. Ad title. This is the standard thread title and is required. It’s strongly encouraged that the title is the product make and model similar to what you might see on Amazon.

5. Short title (max 20 characters) to be used where space is tight like on the grid view. Automatically populate this from the ad title, but allow the user to edit it.

6. If the user selected a FOR SALE, FOR AUCTION or EXCHANGE type advert, then they are asked to
6a. Select a currency. This will default to the currency associated with the country determined by their current IP address (admin can set this to optional or compulsory)
6b. Admin option to force the user to enter a numeric price. If not, they can enter a price or text e.g. OFFERS. Enter an asking price for all the goods being advertised in the advert. The prices of individual items can be detailed in the advert text.

7. Ad text. This is the standard post text entry box and is required. All the standard tags including video embedding can be used in the body text including video. The user can select one of their attached images as the thumbnail shown in the advert list & Spotlight etc. The first image is used by default or if no images are attached or linked to, then a default image will be used.

8. Binary option tickbox asking the user to indicate if they are a dealer. If a ‘Dealer’ usergroup has been allocated to a member then this tick box is checked and disabled so they cannot uncheck it. We define dealers as
8a. people selling goods which belong to a commercial organisation
8b. people representing a commercial organisation selling goods on behalf of their customer
8c. people using the forums regularly to buy and sell goods for a profit

9. Select the Cost Package. Additional options to feature, spotlight etc. The cost of placing the advert needs to be display prominently to the advertiser on the advert page.

10. There needs to be a tickbox where the advertiser agrees to Terms and Conditions in order to proceed.

There will also be admin set custom fields placed anywhere above or below the standard fields.

Once the ad has all the required fields entered, the CREATE button is available which creates the ad with a status of DRAFT.

Attached media
The default thumbnail image for adverts will be a ‘NO IMAGE’ except for Wanted adverts when it will be ‘WANTED’. Can’t have images for Wanted adverts, of course, but we still need to list them using the same template as the other ads.

Images can be attached in the standard Xenforo way. For all ad types except Wanted, if images are embedded or attached, the first image will be used by default as the thumbnail for the advert. The advertiser can choose an alternative images as the thumbnail.

Editing ads
Permission to edit are admin set. (The intention is that ads with the status of DRAFT or LIVE can be edited by the owner, moderator and admin).

All fields (including the custom ones) can be edited.

Changing the category when there is an associated thread, moves the thread into the forum associated with the new category.

When the title and text of the advert are changed, the thread is changed to reflect the changes. Thus a history of the advert changes are recorded in the standard Xenforo post history.

 

[Stuart Wright]

Packages

Packages are set up by admin and chosen by advertisers. They set out how long the advert will be live before being automatically archived plus there are options to purchase certain option extras. This generates revenue from the classifieds for the forum.

Each admin created package is applied to categories, so there needs to be a category selector

The package elements are:

Duration
There can be a number of different advert durations defined by admin, after which the advert is automatically archived. Each one can have a different cost attached to it. E.g. 7 days, 14 days, 1 month.

Multiple adverts
The cost of placing multiple concurrent adverts can be set. E.g. cost of one advert, two concurrent adverts, three concurrent adverts, subsequent concurrent adverts. So you could make the first advert free, but charge a fee if they want to put up a second, third or more adverts. For example, if someone wants to post three adverts, they could get charged £0 (for the first advert) + £5 (to add a second advert) + £7 (to add a third advert). Charging for concurrent adverts will discourage people from posting lots of adverts and thereby swamping your classifieds with their adverts.

Featuring adverts
Stick adverts at the top of advert lists. Cost options for set number of days. E.g. 7, 14, 1 month

Spotlight adverts
Display a thumbnail of the advert in the sidebar widget. Cost options for set number of days.

Note ebay charges (when I checked in 2014):
· Featured : 3 days - £2.95 / 7 days - £4.50 / 14 days - £6.75
· Spotlight : 7 days - £14.95

Urgent ads
This combines Featuring and Spotlighting and marks the ad as urgent. Cost options for set number of days.

Dealer ads
If the user setting up the ad is a dealer (and dealer functionality is enabled) then there can be a cost for dealers to place ads. Cost options for set number of days.

Bumping
Packages dictate the frequency that the advertisers can bump their ads. Every 12 hours, every 24 hours, every 48 hours. Option to purchase auto bumping and the functionality which does this.

Paid adverts which break the rules
Moderators should deal with fee paying adverts in exactly same way as any others. If an advert breaks the rules, the moderators may move it back to the DRAFT status (which will move it back to the draft ads forum).

What if someone pays for an advert and then processes a chargeback without good reason? Permanent trading ban?

 

[Stuart Wright]

Searching adverts

There will be a classifieds-specific search in the advanced search page plus a search form at the top of the sidebar of the classifieds home page.

Search results of classified adverts only return LIVE ads by default.

The key search elements are:

• Advert (thread) title
• Advert (post #1) text
• Category (hierarchical drop-down list)
• Filters on
  • Advert type (For Sale / Exchange / Wanted)
  • Condition (Used / New)
  • Advertiser Type (Private / Dealer)
  • Featured ads
  • Spotlighted ads
  • Urgent Ads
  • Other custom fields as specified in the admin setup?

Search results
Thumbnail image shown to the left of the search results. Layout something like http://www.gumtree.com/search?q=samsung&category=all&search_location=United+Kingdom

Displaying adverts
Adverts are displayed in the Advert tab. Copy the general layout of Gumtree

https://www.gumtree.com/p/televisio...-monitor-tv-freeview-hd-ready-720p/1147209100

 

[Stuart Wright]

Trader Ratings

The trader ratings system is a fairly hefty chunk of functionality which fundamentally emulates ebay’s feedback system.

Three types of trader – buyer/seller/exchange

Feedback of positive/neutral/negative is left between the traders

The total feedback points are the sum of positive minus the sum of negative ratings.

The total feedback score is the sum of positive ratings from unique members minus the sum of negative ratings from unique members.

 

[Stuart Wright]

Alerts

In addition to standard Xenforo alerts, members are also sent an alert when

• A moderator changes the status of an advert
• An advert’s featuring or spotlighting has expired
• An advert is going to be auto archived in an admin set number of days
• An advert has been auto archived

Permissions
There will be

• Permissions to view own / other peoples’ adverts.
• Permissions to create and edit adverts should be based on whether the users can create and edit threads in the relevant forums with an optional check on their DOB that they are over 18.
• Permissions to determine who can view the advert contact information. We would invite people to enter their email, landline and mobile phone numbers, but not necessarily display those to the public. At AVForums, we’ll make these fields compulsory for security purposes, but only show them to moderators.
• Permission to publish own advert and other peoples’ adverts.
• Permission to archive own advert and other peoples’ adverts.

No doubt lots more.

 

[Kintaro]

Please consider a Xentrader importer too

 

[The Grand Potentate]

A couple of things I find handy:

-An easy way to mark an item sold as opposed to having to go in and edit the listing.

-An easy way to link all your classified listings via a single link.

-For classifieds that are image heavy, a simple way to view all the images as opposed to viewing them all individually.


When do you plan on releasing this @Stuart Wright?

 

[Stuart Wright]

Please consider a Xentrader importer too

People using Xentrader might need to club together to pay for that.

A couple of things I find handy:

-An easy way to mark an item sold as opposed to having to go in and edit the listing.

-An easy way to link all your classified listings via a single link.

-For classifieds that are image heavy, a simple way to view all the images as opposed to viewing them all individually.


When do you plan on releasing this @Stuart Wright?

There will be a button to take the ad out of the live list.
There will be a tab in the user profile that people can link to which lists live adverts to the public.
I imagine something like the XMG grid view of images would be a good way to see them all.
Releasing as soon as it's developed. Which depends on the developer.

 

[Kintaro]

Another thing (not in v1.0?) are transactional emails like:

your ad is going to expire in xx days. click here to renew
click here to mark it sold
click here to delete
​

People using Xentrader might need to club together to pay for that.

ok, how much do you think it will be needed?

 

[Stuart Wright]

Another thing (not in v1.0?) are transactional emails like:

your ad is going to expire in xx days. click here to renew
click here to mark it sold
click here to delete
​

ok, how much do you think it will be needed?

These would use the standard alerts system with optional emails.
Marking ads as sold isn't appropriate for Exchange or Wanted ads, so we have to plan better than that.
Adverts wouldn't be deleted, but archived.

 

[empire]

Is a Media tab necessary if the advertiser wants to embed images and/or video and/or attachments in the advert text?

I don't think a media tab is necessary as long as images can be displayed on the main listing page. However, we'd like to have custom fields that can accept an external image URL and display it as an image. (As opposed to just uploading all the images.)

Marking ads as sold isn't appropriate for Exchange or Wanted ads, so we have to plan better than that.

We have people mark their ads as Finished, which works for Exchange and Wanted ads too.

We would not use the Condition and Advertiser attributes. Would these be optional, or could we rename them with attributes that are more important to us?

One thing that would be helpful is a page (or profile tab or sidebar block) for advertiser info, so that the member doesn’t have to fill out general information more than once. It could include location but would also need custom fields. For example, we require advertisers to say if they are from a smoking household or if they are willing to mark international parcels as a gift.

I think you mentioned it in another thread, but it would help to have a Bump button with a time limit. Not for threads, but for the resource itself.

 

[iTuN3r]

Can auction have option to use forum points to bid on items instead of real money involved .

 

[0ptima]

I currently use custom thread fields for my classifieds. When browsing the forum that has the adverts, users can see the price and location custom fields. I would like to see an option to select which fields can be seen when browsing the forum that has the adverts (here is a mock-up ).

 

[0ptima]

Is a Media tab necessary if the advertiser wants to embed images and/or video and/or attachments in the advert text?

I don't think a media tab is necessary as long as images can be displayed on the main listing page.

A media tab is not needed. Here is a mockup of how it could look.