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