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