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