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