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