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