Store
Community Documentation

v3 Knowledgebase

Adding Sponsor support

In our version 2.0.5 we are providing a new beta feature which is to sponsor items. A sponsored item works like the previous spotlight feature for videos but this is available in more items (Photos, Forum thread, Music Album, Music Song, Videos, Marketplace, Group) and by default its located above the spotlight in the video section, another main difference is that users need to pay in order to get their item Sponsored.

As a developer you may be interested in providing the Sponsored feature for your new section, or simply extending it to another item.

Adding payment support

For this you will need to allow the admin to set the price for this item. So create a new user group setting, the variable name must have "_sponsor_price", so for example if you want sponsored polls this would be: poll_sponsor_price, the full variable includes the module as well (poll.poll_sponsor_price). The type can be anything, we set the default ones to be string and the actual values the word null. This will show the input for the available currencies when editing user group settings.

Creating the Callbacks

getToSponsorInfo

There needs to be a callback function (named getToSponsorInfo) to retrieve information about the item when confirming the purchase before creating an invoice, this function receives an item id which is an integer and is what you passed to the ad.sponsor controller. This callback function must return an array with the following items:

  • [Required] 'title' (string) A title to show
  • [Required] 'link' (string) A URL pointing to the item
  • [Required] 'paypal_msg' (string) A message to be sent to paypal, for example "Paying for sponsor space..."
  • [Required] 'item_id' (int) The item id.
  • [Required] 'user_id' (int) The owner of this item.
  • [Optional] 'error' (string) If there is an error (i.e. item not found), this is the message to show the user.
  • [Optional] 'extra' (string) More information about the item
  • [Optional] 'image' (string) Path from within image_dir to reach the image
  • [Optional] 'image_dir' (string) index for the file folder where to reach the image. (See include/setting/common.sett.php)

If you are sponsoring a second item in a module (like the music module which has songs and albums), the module name would be: music-album, as in index.php?do=/ad/sponsor/module_music-album/id_23 Then the callback function has a different name which is the second part of the module name, in this case: getToSponsorAlbumInfo

Before this function has been created, if the ad.sponsor controller gets a request it will return a "module not available" error.

enableSponsor

This function is the one in charge of toggling an item sponsor, for example it turns the field `phpfox_music_album`.`is_sponsor` when its time to show it as sponsor. This function is called automatically upon receiving information from the API gateway that the item has been successfully paid, it is also called when the admin has approved an item as sponsored.

getLink

For the modules that implement the Sponsor feature this function alrady exists, but if you're extending to another module you will need to have a callback function that returns the link to the item. This may or may not check for the existence of the item as this will be done by the controller anyways. This function receives one parameter (like any callback function) where there are 2 indexes: item_id => int section => string. The section is only used for modules that implement more than one item, for example the music module implements the Album and the Song items. A special case has been reserved for the forum where it can sponsor threads but not forums, third party developers may be interested in developing support for sponsoring forums so this feature was built so the sponsoring of forum threads should not interfere when they add their support for sponsoring complete forums. Returns according to makeUrl()