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