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

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