How to Create an OSMap Plugin

Our OSMap extension creates sitemaps for other components via plugins.

You may find some of them in your plugins manager once you install OSMap.

How to Create an OSMap Plugin

For the complete list of extensions for which there is an OSMap plugin already exists, please take a look at our What Extensions Does OSMap Support? document.

If there is no plugin listed in that docoment for your extension, please consider creating one yourself or hire a developer. You will find some useful guidelines for developers below.

Architecture

OSMap plugins are built using the standard Joomla plugin architecture. At a minimum, you will need to create an installation manifest xml file, and the plugin php script file with the proper class definition for a plugin.

This document assumes you already know the basics of creating a Joomla plugin. The free version of OSMap contains all the classes your plugin will need to utilize. You can use it to explore the mechanics in more detail.

example.xml

<?xml version="1.0" encoding="UTF-8"?>
<extension type="plugin" group="osmap" version="3.7" method="upgrade">
    <name>OSMap - Example</name>
    <creationDate>February 28, 2018</creationDate>
    <copyright>Copyright (C) 2018 Example Developer</copyright>
    <license>GNU General Public License version 2 or later</license>
    <author>Example Developer</author>
    <authorEmail>developer@example.com</authorEmail>
    <authorUrl>https://www.example.com</authorUrl>
    <version>1.0.0</version>
    <description>This is an example OSMap Plugin</description>
       
    <files>
        <filename plugin="example">example.php</filename>
    </files>
</extension>

Of course you can include any plugin parameters you need to use in your code with a standard <config> section of the manifest.

Note that if you intend to use language translation files, we prefer to keep the translations with the extension. So don’t include a <language> tag, but do be sure to include a language folder in the <files> tag.

example.php


use Alledia\OSMap\Plugin\Base;
use Alledia\OSMap\Sitemap\Collector;
use Alledia\OSMap\Sitemap\Item;
use Joomla\Registry\Registry;

class PlgOsmapName extends Base
{
    public function getComponentElement()
    {
        return 'com_mycomponent';
    }

    /**
     * @param Collector $collector
     * @param Item      $parent
     * @param Registry  $params
     *
     * @return void
     */
    public function getTree(Collector $collector, Item $parent, Registry $params)
    {
        // your code goes here
    }
}

OSMap will call the getTree() method where your code will generate any non-menu items that belong under the menuitem represented by $parent.

Use other OSMap plugins to get a feel for what your code needs to do. But here are some essentials:

Your code will create new nodes that should be displayed under the parent menuitem. So for example, creating a single new node under the current $parent:


$collector->changeLevel(1);
$node = (object)array(
    'id'         => $parent->id,
    'name'       => 'This Node Title',
    'uid'        => $parent->uid . '_' . 'UniqueNodeId',
    'modified'   => '2018-02-28 12:00:00',
    'browserNav' => $parent->browserNav,
    'priority'   => .5,
    'changefreq' => 'weekly',
    'link'       => 'index.php?option=com_mycomponent'
);
$collector->printNode($node);
$collector->changeLevel(-1);

What’s happening:

  1. Advance 1 display level under the current item
  2. Create the node object
  3. Send the node to OSMap for printing
  4. Return to the previous display level

The node object consists of:

id Required Usually the parent id
name Required The title of the item being displayed
uid Required A unique ID. Duplicates are determined from this
link Required The full raw link to the item.
modified Optional Last modified date (needed for news sitemaps)
browserNav Optional For the target attribute of the generated link
priority Optional Inherits from parent if not provided
changefreq Optional Inherits from parent if not provided