inc/classes/main/helper/web/links/class_WebLinkHelper.php

   1 <?php
   2 /**
   3  * A helper for web links
   4  *
   5  * @author              Roland Haeder <webmaster@ship-simu.org>
   6  * @version             0.0.0
   7  * @copyright   Copyright (c) 2007, 2008 Roland Haeder, 2009 Core Developer Team
   8  * @license             GNU GPL 3.0 or any newer version
   9  * @link                http://www.ship-simu.org
  10  *
  11  * This program is free software: you can redistribute it and/or modify
  12  * it under the terms of the GNU General Public License as published by
  13  * the Free Software Foundation, either version 3 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  23  */
  24 class WebLinkHelper extends BaseWebHelper implements HelpableTemplate {
  25         /**
  26          * Name of the link
  27          */
  28         private $linkName = '';
  29
  30         /**
  31          * Base of the link
  32          */
  33         private $linkBase = '';
  34
  35         /**
  36          * First parameter seperator
  37          */
  38         private $firstParameter = '?';
  39
  40         /**
  41          * Seperator for more paraemters
  42          */
  43         private $parameterSeperator = '&amp;';
  44
  45         /**
  46          * Protected constructor
  47          *
  48          * @return      void
  49          */
  50         protected function __construct () {
  51                 // Call parent constructor
  52                 parent::__construct(__CLASS__);
  53         }
  54
  55         /**
  56          * Creates the helper class
  57          *
  58          * @param       $templateInstance       An instance of a template engine
  59          * @param       $linkName                       Name of the link we shall generate
  60          * @param       $linkBase                       Link base for the link. This parameter is deprecated.
  61          * @return      $helperInstance         A prepared instance of this helper
  62          * @throws      NullPointerException    Thrown if an instance is null
  63          * @throws      ConfigEntryNotFoundException    A deprecated exception at this point
  64          */
  65         public final static function createWebLinkHelper (CompileableTemplate $templateInstance, $linkName, $linkBase = null) {
  66                 // Get new instance
  67                 $helperInstance = new WebLinkHelper();
  68
  69                 // Set template instance
  70                 $helperInstance->setTemplateInstance($templateInstance);
  71
  72                 // Set link name
  73                 $helperInstance->setLinkName($linkName);
  74
  75                 // Get the application instance
  76                 $applicationInstance = Registry::getRegistry()->getInstance('application');
  77
  78                 // Sanity-check on it
  79                 if (is_null($applicationInstance)) {
  80                         // Throw an exception here
  81                         throw new NullPointerException($helperInstance, self::EXCEPTION_IS_NULL_POINTER);
  82                 } // END - if
  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                 $page = $helperInstance->convertDashesToUnderscores($requestInstance->getRequestElement('page'));
  95
  96                 // Construct config entry
  97                 $configEntry = $page . '_' . $linkName;
  98
  99                 // Is the deprecated parameter set?
 100                 if (!is_null($linkBase)) {
 101                         // Then output a deprecation message
 102                         $helperInstance->deprecationWarning(__METHOD__ . ': linkBase is deprecated. Please remove it from your templates and add a config entry ' . $configEntry . '_action in your config.php file.');
 103                 } // END - if
 104
 105                 // Determine link base from config now and 'page' request
 106                 try {
 107                         $newLinkBase = $helperInstance->getConfigInstance()->getConfigEntry($configEntry);
 108                         $linkBase = $newLinkBase;
 109                 } catch (ConfigEntryNotFoundException $e) {
 110                         // Is the deprecated linkBase not set?
 111                         if (is_null($linkBase)) {
 112                                 // Then throw again the exception
 113                                 throw new ConfigEntryNotFoundException(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=\"%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("<{$groupCode} id=\"group_%s_%s\">%s",
 228                         $this->getLinkName(),
 229                         $groupId,
 230                         $groupText
 231                 );
 232
 233                 // Open the new group
 234                 $this->openGroupByIdContent($groupId, $content, $groupCode);
 235         }
 236
 237         /**
 238          * Adds text (note) to the previously opened group or throws an exception
 239          * if no previous group was opened.
 240          *
 241          * @param       $groupId        Group id to set
 242          * @param       $groupNote      Note to be added to a group
 243          * @param       $groupCode      Code to open and close groups
 244          * @return      void
 245          * @throws      NoGroupOpenedException  If no previous group was opened
 246          */
 247         public function addLinkNote ($groupId, $groupNote, $groupCode = "div") {
 248                 // Check if a previous group was opened
 249                 if ($this->ifGroupOpenedPreviously() === false) {
 250                         // No group was opened before!
 251                         throw new NoGroupOpenedException(array($this, $groupNote), self::EXCEPTION_GROUP_NOT_OPENED);
 252                 } // END - if
 253
 254                 // Is a previous sub group open?
 255                 if ($this->ifSubGroupOpenedPreviously()) {
 256                         // Then close it
 257                         $this->closePreviousSubGroupByContent("</{$groupCode}>");
 258                 } // END - if
 259
 260                 // Generate the group content
 261                 $content = sprintf("<{$groupCode} id=\"subgroup_%s_%s\">%s",
 262                         $this->getLinkName(),
 263                         $groupId,
 264                         $groupNote
 265                 );
 266
 267                 // Open the sub group
 268                 $this->openSubGroupByIdContent($groupId, $content, $groupCode);
 269         }
 270
 271         /**
 272          * Adds a link to the previously opened group or throws an exception if no group has been opened
 273          *
 274          * @param       $linkAction             Action (action=xxx) value for the link
 275          * @param       $linkText               Link text and title (title="xxx") for the link
 276          * @return      void
 277          * @throws      NoGroupOpenedException  If no previous group was opened
 278          */
 279         protected function addActionLink ($linkAction, $linkText, $linkTitle) {
 280                 // Check if a previous group was opened
 281                 if ($this->ifGroupOpenedPreviously() === false) {
 282                         // No group was opened before!
 283                         throw new NoGroupOpenedException(array($this, $linkAction . '(' . $linkText . ')'), self::EXCEPTION_GROUP_NOT_OPENED);
 284                 } // END - if
 285
 286                 // Default parameter seperator is &amp;
 287                 $seperator = $this->parameterSeperator;
 288
 289                 // Is there a question mark in?
 290                 $linkArray = explode($this->firstParameter, $this->getLinkBase());
 291                 if (count($linkArray) == 0) {
 292                         // No question mark
 293                         $seperator = $this->firstParameter;
 294                 } // END - if
 295
 296                 // Prepare action
 297                 $action = sprintf("%saction=%s",
 298                         $seperator,
 299                         $linkAction
 300                 );
 301
 302                 // Renders the link content
 303                 $linkContent = $this->renderLinkContentWithTextExtraContent($linkText, $linkTitle, $action);
 304
 305                 // Add the content to the previous group
 306                 $this->addContentToPreviousGroup($linkContent);
 307         }
 308
 309         /**
 310          * Adds a link to the previously opened group with a text from language system
 311          *
 312          * @param       $linkAction             Action (action=xxx) value for the link
 313          * @param       $languageId             Language id string to use
 314          * @return      void
 315          */
 316         public function addActionLinkById ($linkAction, $languageId) {
 317                 // Resolve the language string
 318                 $languageResolvedText = $this->getLanguageInstance()->getMessage("link_" . $languageId . "_text");
 319
 320                 // Resolve the language string
 321                 $languageResolvedTitle = $this->getLanguageInstance()->getMessage("link_" . $languageId . "_title");
 322
 323                 // Add the action link
 324                 $this->addActionLink($linkAction, $languageResolvedText, $languageResolvedTitle);
 325         }
 326
 327         /**
 328          * Adds a default link (no extra parameters) to the content with specified
 329          * language id string.
 330          *
 331          * @param       $languageId             Language id string to use
 332          * @return      void
 333          */
 334         public function addLinkWithTextById ($languageId) {
 335                 // Resolve the language string
 336                 $languageResolvedText = $this->getLanguageInstance()->getMessage("link_" . $languageId . "_text");
 337
 338                 // Resolve the language string
 339                 $languageResolvedTitle = $this->getLanguageInstance()->getMessage("link_" . $languageId . "_title");
 340
 341                 // Now add the link
 342                 $linkContent = $this->renderLinkContentWithTextExtraContent($languageResolvedText, $languageResolvedTitle);
 343
 344                 // Add the content to the previous group
 345                 $this->addContentToPreviousGroup($linkContent);
 346         }
 347 }
 348
 349 // [EOF]
 350 ?>