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

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