inc/classes/main/helper/html/links/class_HtmlLinkHelper.php

   1 <?php
   2 /**
   3  * A helper for web links
   4  *
   5  * @author              Roland Haeder <webmaster@shipsimu.org>
   6  * @version             0.0.0
   7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2015 Core Developer Team
   8  * @license             GNU GPL 3.0 or any newer version
   9  * @link                http://www.shipsimu.org
  10  *
  11  * This program is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU General Public License as published by
  13  * the Free Software Foundation, either version 3 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  23  */
  24 class HtmlLinkHelper extends BaseHtmlHelper implements HelpableTemplate {
  25         /**
  26          * Name of the link
  27          */
  28         private $linkName = '';
  29
  30         /**
  31          * Base of the link
  32          */
  33         private $linkBase = '';
  34
  35         /**
  36          * First parameter separator
  37          */
  38         const FIRST_PARAMETER_SEPARATOR = '?';
  39
  40         /**
  41          * SEPARATOR for more paraemters
  42          */
  43         const EXTRA_PARAMETER_SEPARATOR = '&amp;';
  44
  45         /**
  46          * Protected constructor
  47          *
  48          * @return      void
  49          */
  50         protected function __construct () {
  51                 // Call parent constructor
  52                 parent::__construct(__CLASS__);
  53         }
  54
  55         /**
  56          * Creates the helper class
  57          *
  58          * @param       $templateInstance       An instance of a template engine
  59          * @param       $linkName                       Name of the link we shall generate
  60          * @param       $linkBase                       Link base for the link. This parameter is deprecated.
  61          * @return      $helperInstance         A prepared instance of this helper
  62          * @throws      NoConfigEntryException  A deprecated exception at this point
  63          */
  64         public static final function createHtmlLinkHelper (CompileableTemplate $templateInstance, $linkName, $linkBase = NULL) {
  65                 // Get new instance
  66                 $helperInstance = new HtmlLinkHelper();
  67
  68                 // Set template instance
  69                 $helperInstance->setTemplateInstance($templateInstance);
  70
  71                 // Set link name
  72                 $helperInstance->setLinkName($linkName);
  73
  74                 // Get the application instance
  75                 $applicationInstance = Registry::getRegistry()->getInstance('application');
  76
  77                 // Get the request instance
  78                 $requestInstance = $applicationInstance->getRequestInstance();
  79
  80                 // Sanity-check on it
  81                 if (is_null($requestInstance)) {
  82                         // Throw an exception here
  83                         throw new NullPointerException($helperInstance, self::EXCEPTION_IS_NULL_POINTER);
  84                 } // END - if
  85
  86                 // Get page (this will throw an exception if not set)
  87                 $command = $helperInstance->convertDashesToUnderscores($requestInstance->getRequestElement('command'));
  88
  89                 // Construct config entry
  90                 $configEntry = $command . '_' . $linkName . '_action_url';
  91
  92                 // Is the deprecated parameter set?
  93                 if (!is_null($linkBase)) {
  94                         // Then output a deprecation message
  95                         $helperInstance->deprecationWarning('[' . __METHOD__ . ':' . __LINE__ . ']:  linkBase is deprecated. Please remove it from your templates and add a config entry ' . $configEntry . ' in your config.php file.');
  96                 } // END - if
  97
  98                 // Determine link base from config now and 'command' request
  99                 try {
 100                         $newLinkBase = $helperInstance->getConfigInstance()->getConfigEntry($configEntry);
 101                         $linkBase = $newLinkBase;
 102                 } catch (NoConfigEntryException $e) {
 103                         // Is the deprecated linkBase not set?
 104                         if (is_null($linkBase)) {
 105                                 // Then throw again the exception
 106                                 throw new NoConfigEntryException(array(__CLASS__, ($configEntry)), FrameworkConfiguration::EXCEPTION_CONFIG_ENTRY_WAS_NOT_FOUND);
 107                         } // END - if
 108                 }
 109
 110                 // Set link base
 111                 $helperInstance->setLinkBase($linkBase);
 112
 113                 // Add default group
 114                 $helperInstance->openGroupByIdContent('main', '', '');
 115
 116                 // Return the prepared instance
 117                 return $helperInstance;
 118         }
 119
 120         /**
 121          * Renders the link content (HTML code) with given link text and optional
 122          * extra content
 123          *
 124          * @param       $linkText               Link text to set in link
 125          * @param       $linkTitle              Link title to set in link
 126          * @param       $extraContent   Optional extra HTML content
 127          * @return      $linkContent    Rendered text link content
 128          */
 129         private function renderLinkContentWithTextExtraContent ($linkText, $linkTitle, $extraContent='') {
 130                 // Construct link content
 131                 $linkContent = sprintf('<a href="{?base_url?}/%s%s" title="%s">%s</a>',
 132                         $this->getLinkBase(),
 133                         $extraContent,
 134                         $linkTitle,
 135                         $linkText
 136                 );
 137
 138                 // Return it
 139                 return $linkContent;
 140         }
 141
 142         /**
 143          * Setter for link name
 144          *
 145          * @param       $linkName       Name of the link we shall generate
 146          * @return      void
 147          */
 148         protected final function setLinkName ($linkName) {
 149                 $this->linkName = (string) $linkName;
 150         }
 151
 152         /**
 153          * Getter for link name
 154          *
 155          * @return      $linkName       Name of the link we shall generate
 156          */
 157         public final function getLinkName () {
 158                 return $this->linkName;
 159         }
 160
 161         /**
 162          * Setter for link base
 163          *
 164          * @param       $linkBase       Base of the link we shall generate
 165          * @return      void
 166          */
 167         protected final function setLinkBase ($linkBase) {
 168                 $this->linkBase = (string) $linkBase;
 169         }
 170
 171         /**
 172          * Getter for link base
 173          *
 174          * @return      $linkBase       Base of the link we shall generate
 175          */
 176         public final function getLinkBase () {
 177                 return $this->linkBase;
 178         }
 179
 180         /**
 181          * Flush the content out,e g. to a template variable
 182          *
 183          * @return      void
 184          * @todo        Completely unimplemented
 185          */
 186         public function flushContent () {
 187                 // Is a previous opened group still open?
 188                 if ($this->ifGroupOpenedPreviously()) {
 189                         // Then close it
 190                         $this->closePreviousGroupByContent('');
 191                 } // END - if
 192
 193                 // Get the content
 194                 $content = $this->renderContent();
 195
 196                 // Get template engine
 197                 $templateInstance = $this->getTemplateInstance();
 198
 199                 // Add content to variable
 200                 $templateInstance->assignVariable($this->getLinkName(), $content);
 201         }
 202
 203         /**
 204          * Adds a link group (like the form group is) with some raw language to the
 205          * helper.
 206          *
 207          * @param       $groupId        Id string of the group
 208          * @param       $groupText      Text for this group to add
 209          * @param       $groupCode      Code to open and close groups
 210          * @return      void
 211          */
 212         public function addLinkGroup ($groupId, $groupText, $groupCode = 'div') {
 213                 // Is a group with that name open?
 214                 if ($this->ifGroupOpenedPreviously()) {
 215                         // Then close it here
 216                         $this->closePreviousGroupByContent('');
 217                 } // END - if
 218
 219                 // Generate the group content
 220                 $content = sprintf('<%s id="group_%s_%s">%s',
 221                         $groupCode,
 222                         $this->getLinkName(),
 223                         $groupId,
 224                         $groupText
 225                 );
 226
 227                 // Open the new group
 228                 $this->openGroupByIdContent($groupId, $content, $groupCode);
 229         }
 230
 231         /**
 232          * Adds text (note) to the previously opened group or throws an exception
 233          * if no previous group was opened.
 234          *
 235          * @param       $groupId        Group id to set
 236          * @param       $groupNote      Note to be added to a group
 237          * @param       $groupCode      Code to open and close groups
 238          * @return      void
 239          * @throws      NoGroupOpenedException  If no previous group was opened
 240          */
 241         public function addLinkNote ($groupId, $groupNote, $groupCode = 'div') {
 242                 // Check if a previous group was opened
 243                 if ($this->ifGroupOpenedPreviously() === FALSE) {
 244                         // No group was opened before!
 245                         throw new NoGroupOpenedException(array($this, $groupNote), self::EXCEPTION_GROUP_NOT_OPENED);
 246                 } // END - if
 247
 248                 // Is a previous sub group open?
 249                 if ($this->ifSubGroupOpenedPreviously()) {
 250                         // Then close it
 251                         $this->closePreviousSubGroupByContent('</' . $groupCode . '>');
 252                 } // END - if
 253
 254                 // Generate the group content
 255                 $content = sprintf('<%s id="subgroup_%s_%s">%s',
 256                         $groupCode,
 257                         $this->getLinkName(),
 258                         $groupId,
 259                         $groupNote
 260                 );
 261
 262                 // Open the sub group
 263                 $this->openSubGroupByIdContent($groupId, $content, $groupCode);
 264         }
 265
 266         /**
 267          * Adds a link to the previously opened group or throws an exception if no group has been opened
 268          *
 269          * @param       $linkAction             Action (action=xxx) value for the link
 270          * @param       $linkText               Link text and title (title="xxx") for the link
 271          * @return      void
 272          * @throws      NoGroupOpenedException  If no previous group was opened
 273          */
 274         protected function addActionLink ($linkAction, $linkText, $linkTitle) {
 275                 // Check if a previous group was opened
 276                 if ($this->ifGroupOpenedPreviously() === FALSE) {
 277                         // No group was opened before!
 278                         throw new NoGroupOpenedException(array($this, $linkAction . '(' . $linkText . ')'), self::EXCEPTION_GROUP_NOT_OPENED);
 279                 } // END - if
 280
 281                 // Default parameter SEPARATOR is &amp;
 282                 $separator = self::EXTRA_PARAMETER_SEPARATOR;
 283
 284                 // Is there a question mark in?
 285                 $linkArray = explode(self::FIRST_PARAMETER_SEPARATOR, $this->getLinkBase());
 286                 if (count($linkArray) == 0) {
 287                         // No question mark
 288                         $separator = self::FIRST_PARAMETER_SEPARATOR;
 289                 } // END - if
 290
 291                 // Prepare action
 292                 $action = sprintf('%saction=%s',
 293                         $separator,
 294                         $linkAction
 295                 );
 296
 297                 // Renders the link content
 298                 $linkContent = $this->renderLinkContentWithTextExtraContent($linkText, $linkTitle, $action);
 299
 300                 // Add the content to the previous group
 301                 $this->addContentToPreviousGroup($linkContent);
 302         }
 303
 304         /**
 305          * Adds a link to the previously opened group with a text from language system
 306          *
 307          * @param       $linkAction             Action (action=xxx) value for the link
 308          * @param       $languageId             Language id string to use
 309          * @return      void
 310          */
 311         public function addActionLinkById ($linkAction, $languageId) {
 312                 // Resolve the language string
 313                 $languageResolvedText = $this->getLanguageInstance()->getMessage('link_' . $languageId . '_text');
 314
 315                 // Resolve the language string
 316                 $languageResolvedTitle = $this->getLanguageInstance()->getMessage('link_' . $languageId . '_title');
 317
 318                 // Add the action link
 319                 $this->addActionLink($linkAction, $languageResolvedText, $languageResolvedTitle);
 320         }
 321
 322         /**
 323          * Adds a default link (no extra parameters) to the content with specified
 324          * language id string.
 325          *
 326          * @param       $languageId             Language id string to use
 327          * @return      void
 328          */
 329         public function addLinkWithTextById ($languageId) {
 330                 // Resolve the language string
 331                 $languageResolvedText = $this->getLanguageInstance()->getMessage('link_' . $languageId . '_text');
 332
 333                 // Resolve the language string
 334                 $languageResolvedTitle = $this->getLanguageInstance()->getMessage('link_' . $languageId . '_title');
 335
 336                 // Now add the link
 337                 $linkContent = $this->renderLinkContentWithTextExtraContent($languageResolvedText, $languageResolvedTitle);
 338
 339                 // Add the content to the previous group
 340                 $this->addContentToPreviousGroup($linkContent);
 341         }
 342 }
 343
 344 // [EOF]
 345 ?>