Directory

phpBB • Extending Advertisement Template Locations - Advertisement Management

phpBB • Free and Open Source Forum Software

RSS Facebook Twitter
Menu

Advertisement Management

Frequently Asked Questions

Extending Advertisement Template Locations

The Advertisement Management extension allows you, extension developers, to add new template locations for advertisements to display. To do this in your extensions, follow these simple instructions:
  1. In your config/services.yml, add new location declaration like this:

    Code: Select all

    demo.extension.location.type.location_name:
    class: demo\extension\location\type\location_name
    arguments:
        - '@user'
        - '@language'
    tags:
        - { name: phpbb.ads.location.type }
    • Always prefix the location type with your vendor and extension name.
    • Tag is crucial here and must be named phpbb.ads.location.type
  2. Add a location type class in location/type/ directory, for example location_name.php.
    • It must implement \phpbb\ads\location\type\type_interface.
    • We strongly encourage you to extend \phpbb\ads\location\type\base.
  3. Implement required methods.
    • See \phpbb\ads\location\type\type_interface for their descriptions.
    • Regarding get_id(), we strongly suggest using your vendor and extension name as a prefix, i.e.:

      Code: Select all

      public function get_id()
{
	return 'demo_extension_location_name';
}
    • Please note, that when you inherit from \phpbb\ads\location\type\base, you don’t need to bother with get_name() and get_desc() methods when you use proper language keys as such (where <location id> is a capitalized form of get_id()):
      • AD_<location id> for location name
      • AD_<location id>_EXPLAIN for location description
  4. Implement optional method will_display(). If your location is not present on every page, we strongly encourage you to implement this method.
    • You can use $this->user->page['page_name'], $this->user->page['query_string'] or any other techniques to decide whether your location should display on a given page.
    • Don’t perform resource-expensive calculations here, such as DB requests - the intention is to speed up the page load, not the opposite.
    • See our default locations for examples.
    • This can improve the extension’s performance and will be appreciated by the users.
  5. Load language file.
    • If inheriting from \phpbb\ads\location\type\base, the language file must contain two language keys:
      • AD_<location id>
      • AD_<location id>_EXPLAIN
    • You can define these in any language file and load your language file by any means in your extension.
    • If you do not already have any language files in your extension, or want to load a language file just for your ad locations, you may do so by adding it to your location class constructor, for example:

      Code: Select all

      public function __construct(\phpbb\user $user, \phpbb\language\language $language)
{
    parent::__construct($user, $language);
    $this->language->add_lang('locations', 'demo/extension');
}
  6. Add template event. Simply create a template event for the desired position and add this code into it:

    Code: Select all

    {% set PHPBB_ADS_STYLE = 'margin: 0;' %}
{% set PHPBB_ADS_CODE, PHPBB_ADS_ID = AD_DEMO_EXTENSION_LOCATION_NAME, AD_DEMO_EXTENSION_LOCATION_NAME_ID %}
{% include '@phpbb_ads/phpbb_ads_default.html' ignore missing %}
    • Use PHPBB_ADS_STYLE to give your advertisement container a customized set of CSS.
    • Regarding PHPBB_ADS_CODE and PHPBB_ADS_ID, you should not alter the logic of these variables as they are used internally within the default ads template file - simply use AD_ prefix, your capitalized result of get_id(), and append the second one with _ID.
    • Note the ignore missing is an important function that will allow your extension to work even if phpbb/ads is disabled or uninstalled.
  7. You are done!
    1. Enable your extension.
    2. Head to ACP -> Extensions -> Advertisement Management -> Manage Advertisements -> Add new advertisement, scroll down to Locations and you should see your new location present and functional.
  8. Bonus: If you want to prevent people from being able to install your extension if phpBB’s Advertisement Management extension is not installed yet, add the following to your ext.php:

    Code: Select all

    public function is_enableable()
{
	return $this->container->has('phpbb.ads.listener');
}
Attached is a sample extension based on this documentation that adds a location to the footer.
demo.zip
(20.29 KiB) Downloaded 1957 times
Top