Develop new widget - Part 2 - Integrate the Link Provider

From TomatoCMS Documentation

In the first part, we knew how to add the link to and remove the link from the collections. But we have to enter the label and URL manually.
In most cases, the URLs are internal links which might be the links to categories, pages or so on.
In this part, we will show you how to use the Link Provider to input the link quickly and automatically.

Step 1: Show the Link Provider in the configuration form

First, we will show a link for toggling the Link Provider (1) right after the button which is used to add new link:

/application/modules/utility/widgets/links/config.phtml

...
<div class="t_a_bottom">
   <button id="utilityLinksButton" class="t_a_ui_button_link"><span><?php echo $this->translator()->widget('config_add_button'); ?></span></button>
</div>
 
<div class="clearfix t_a_bottom"></div>
 
<!-- Toggle the Link Provider (1) -->
<div class="t_a_bottom">
   <a href="javascript: void(0);" onclick="javascript: $('#linkProvider').toggle();"><?php echo $this->translator()->widget('config_use_link_provider'); ?></a>
</div>
 
<!-- Show the Link Provider (2) -->
<div class="t_a_bottom" style="display: none" id="linkProvider">
   <?php echo $this->linkProvider(array('jsCallback' => 'addLink')); ?>
</div>
 
<div class="t_a_top">
   <table id="utilityLinksTable" class="t_a_ui_table">
      ...
   </table>
</div>

Second, to show the Link Provider, we use the linkProvider view helper provided by core module (2):

<?php echo $this->linkProvider(array('jsCallback' => 'addLink')); ?>

The linkProvider view helper calling requires a parameter as an array which consist of jsCallback property.
The value of this property is the name of Javascript function which will be used to handle when user click on the link in the Link Provider.
The callback function has three parameters:

• route: The route associating with the selected link,
• href: The URL of the selected link,
• title: The title of the selected link.

Here, we will create a callback function named addLink. This function has three parameters which are described as above, and is used to add the selected link to the collection:

/application/modules/utility/widgets/links/config.phtml

<script type="text/javascript">
function addLink(route, url, title) {
 
};
 
function removeLink(link) {
   ...
};
 
function getLinks() {
   ...
};
 
$(document).ready(function() {
   ...
});
</script>

We will implement the addLink function at the later section of this tutorial.

Step 2: Add the CSS, Javascript libraries to render the Link Provider

At this step, you will see that the Link Provider is not rendered correctly.

The issue caused by missing the CSS and javascript libraries.
Open the script /application/modules/core/views/scripts/_partial/_linkProvider.phtml which is used to render the Link Provider, you will see that there are two CSS and two Javascript files need to be included:

/application/modules/core/views/scripts/_partial/_linkProvider.phtml

<?php 
$this->headLink()
   ->appendStylesheet($this->APP_STATIC_SERVER . '/js/jquery.ui/themes/base/ui.core.css')
   ->appendStylesheet($this->APP_STATIC_SERVER . '/js/jquery.ui/themes/base/ui.accordion.css');
 
$this->headScript()
   ->appendFile($this->APP_STATIC_SERVER . '/js/jquery.ui/ui.core.js')
   ->appendFile($this->APP_STATIC_SERVER . '/js/jquery.ui/ui.accordion.js')   
?>
...

So, we have to add theses files to the top of the widget configuration file:

/application/modules/utility/widgets/links/config.phtml

<link href="<?php echo $this->APP_STATIC_SERVER; ?>/js/jquery.ui/themes/base/ui.core.css" media="screen" rel="stylesheet" type="text/css" />
<link href="<?php echo $this->APP_STATIC_SERVER; ?>/js/jquery.ui/themes/base/ui.accordion.css" media="screen" rel="stylesheet" type="text/css" />
<script type="text/javascript" src="<?php echo $this->APP_STATIC_SERVER; ?>/js/jquery.ui/ui.core.js"></script>
<script type="text/javascript" src="<?php echo $this->APP_STATIC_SERVER; ?>/js/jquery.ui/ui.accordion.js"></script>
...

Refresh the layout editor page. Now, the Link Provider is rendered correctly:

Step 3: Handle the event when user click on the link in the Link Provider

Last step, we need to insert the link taken from the Link Provider to the links collection.
Note that we already have the code for adding the link when user click on the Add button, therefore, we just make a small refactoring here: Moving the code inside the $('#utilityLinksButton').click(function() {...}) function to the addLink function:

/application/modules/utility/widgets/links/config.phtml

...
<script type="text/javascript">
function addLink(route, url, title) {
   var tr = $('<tr/>');
   var td = $('<td/>');
   var a  = $('<a/>').attr('href', url)
      .html(title)
      .click(function() {
         return removeLink($(this));
      });
 
   $(td).append($(a));
   $(tr).append($(td)).appendTo($('#utilityLinksTable tbody'));
 
   $('#utilityLinks').val($.toJSON(getLinks()));
};
 
function removeLink(link) {
   ...
};
 
function getLinks() {
   ...
};
 
$(document).ready(function() {
   $('#utilityLinksButton').click(function() {
      $('#utilityLinksButton').click(function() {
         addLink(null, $('#utilityLinksUrl').val(), $('#utilityLinksLabel').val());
      });
   });
});
</script>

Now, refresh the layout editor page and try to click on the link in the Link Provider. The selected link will be added to the links collection: