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