How to make my Editor plugin (type: editors-xtd) survive after updates?

Question

I have a project that I am writing a component, module, and editor plugin for.

I have managed to piece together a rudimentary plugin that works with TinyMCE (at least) which:

1. Displays a custom button
2. Triggers a popup modal window containing a dynamic table of buttons using db data
3. Inserts a custom, curly-braced placeholder into an article.

The part that I am concerned with is making my solution "upgrade proof".

I followed https://mrgott.com/13-joomla/17-how-to-create-joomla-editors-xtd-plugin-button-and-open-modal-popup as much as I could, until I needed to break away and build beyond what is mentioned. That resource warns:

NOTE: Yes, the first question that arises is: What if after each update your file will be removed as it’s not a part of Joomla’s com_content component. Yeah, that’s right, but actually I’m fine by keeping this file, and uploading it after each system update, rather then doing plugin development in the wrong and dirty way.

If you are building this plugin for your client, you should better build a component, or maybe you already built some component and just add a new view file there for your editors-xtd plugin.

I feel like my component will need more than just a new file in views. I would rather learn "the right way". I don't want to "give up" like Philippe. What files do I need to create (copy into my component and modify) to make my plugin long-lasting? I could also use a tip on how to add a little icon to my custom button in the editor; right now I only have text with an empty space on its left side.

The onDisplay() function in /plugins/editors-xtd/picturelinkcode/picturelinkcode.php:

public function onDisplay($name)
{       
    $query_string = [
        "option" => "com_content",      // I want this to be "com_picture",
        "view"   => "article",
        "layout" => "picturelinkcode",  // some examples use "modal" here
        "tmpl"   => "component",
        "editor" => $name
    ];

    $link = 'index.php?' . http_build_query($query_string);

    $button = new JObject;
    $button->modal = true;
    $button->class = 'btn';
    $button->link  = $link;
    $button->text  = JText::_('Linkcode');
    $button->name  = 'picturelinkcode';
    $button->options = "{handler: 'iframe', size: {x: 600, y: 400}}";

    return $button;
}

The /administrator/components/com_content/views/article/tmpl/picturelinkcode.php file:

<?php
defined('_JEXEC') or die;

$document     = JFactory::getDocument();
$this->editor = JFactory::getApplication()->input->getCmd('editor', '');
$this->editor = preg_replace('~[^\w[\]-]+~', '', $this->editor);  // sanitize

/**
 * ...better coding practice would probably be
 * to store the js and the data processing
 * outside of this tmpl file
 *   --apologies while sprinting
 */
$script  = 'function insertPictureLinkcode(linkcode) {' . "\n";
$script .= '  var tag = "{loadpicture " + linkcode + "}";' . "\n";
$script .= '  window.parent.jInsertEditorText(tag, ' . json_encode($this->editor) . ');' . "\n"; // "jform_articletext"
$script .= '  window.parent.jModalClose();' . "\n";
$script .= '  return false;' . "\n";
$script .= '}' . "\n";

JFactory::getDocument()->addScriptDeclaration($script);

?><h3>Picture Linkcodes</h3><?php

// Retrieve all linkcodes and their associated counts
$db = JFactory::getDBO();
$subquery = $db->getQuery(true)
               ->select("id")
               ->from("#__fields")
               ->where([
                   "context = 'com_picture.picture'",
                   "name = 'linkcode'"
                 ]);
$query = $db->getQuery(true)
            ->select("value AS linkcode, COUNT(*) AS picturecount")
            ->from("#__fields_values")
            ->where("field_id = ($subquery)")
            ->group("value");
$db->setQuery($query);

try
{
    $resultset = $db->loadObjectList();
    if (!$resultset)
    {
        echo "No Linkcodes Available Yet<br>";
    }
    else
    {
        ?>
        <form class="form">
            <table>
                <?php
                foreach ($resultset as $row)
                {
                    ?>
                    <tr>
                        <td>
                            <button onclick="insertPictureLinkcode('<?php echo $row->linkcode; ?>');" class="btn btn-primary">
                                <?php echo $row->linkcode; ?>
                            </button>
                        </td>
                        <td>
                            (<?php echo $row->picturecount; ?>)
                        </td>
                    </tr>
                    <?php
                }
                ?>
            </table>
        </form>
        <?php
    }
} catch (Exception $e) {
    echo "<div class='bg-danger'>Picture Linkcode Query Error - Contact Developer</div>";
    //echo "<div class='bg-danger'>" , $query->dump() , "<br>" , $e->getMessage() , "</div>";
}

Screenshots of my currently functional coding attempt: https://i.sstatic.net/OabHq.jpg (I should ask @Eoin what tech he uses to make those nifty animated gifs)

In case it matters, my component is nearly identical to the core's adminstistrator/components/com_contact and my module will only have one job -- to replace placeholders in articles with dynamic content. My plugin will eventually have greater functionality than I am showing in this question.

Answer 1

Normally, the plugin would open a list of items. In this case, the component doesn't have the model/view for the items. So you have to create them.

As a bare minimum, the model must contain getListQuery() method which returns the query used to retrieve the items.

administrator/components/com_picture/models/items.php:

defined('_JEXEC') or die;

class PictureModelItems extends JModelList
{
    protected function getListQuery()
    {
        // Retrieve all linkcodes and their associated counts
        $db = $this->_db;
        $subQuery = $db->getQuery(true)
            ->select($db->quoteName('id'))
            ->from($db->quoteName('#__fields'))
            ->where(
                [
                    $db->quoteName('context') . ' = ' . $db->quote('com_picture.picture'),
                    $db->quoteName('name') . ' = ' . $db->quote('linkcode'),
                ]
            );

        $query = $db->getQuery(true)
            ->select([$db->quoteName('value', 'linkcode'), 'COUNT(*) AS picturecount'])
            ->from($db->quoteName('#__fields_values'))
            ->where($db->quoteName('field_id') . ' = (' . $subQuery . ')')
            ->group($db->quoteName('value'));

        return $query;
    }
}

The view, as a bare minimum, must retrieve the items.

administrator/components/com_picture/views/items/view.html.php:

defined('_JEXEC') or die;

class PictureViewItems extends JViewLegacy
{
    protected $items;

    public function display($tpl = null)
    {
        $this->items = $this->get('Items');

        return parent::display($tpl);
    }
}

Then, in the view layout output the list of items in a table or whatever other format you prefer.

In the button plugin, change link property to point to your new view:

$button->link = 'index.php?option=com_picture&view=items&layout=modal&tmpl=component&editor=' . $name . '&' . JSession::getFormToken() . '=1';

I could also use a tip on how to add a little icon to my custom button in the editor

The icon is coming from button's name property. It gets icon- added in front to form a IcoMoon icon class. E.g. if you set it to joomla the resulting class will be icon-joomla. See all icons here.