3 namespace CoreFramework\Helper;
5 // Import framework stuff
6 use CoreFramework\Configuration\FrameworkConfiguration;
9 * A helper for web links
11 * @author Roland Haeder <webmaster@shipsimu.org>
13 * @copyright Copyright (c) 2007, 2008 Roland Haeder, 2009 - 2017 Core Developer Team
14 * @license GNU GPL 3.0 or any newer version
15 * @link http://www.shipsimu.org
17 * This program is free software: you can redistribute it and/or modify
18 * it under the terms of the GNU General Public License as published by
19 * the Free Software Foundation, either version 3 of the License, or
20 * (at your option) any later version.
22 * This program is distributed in the hope that it will be useful,
23 * but WITHOUT ANY WARRANTY; without even the implied warranty of
24 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
25 * GNU General Public License for more details.
27 * You should have received a copy of the GNU General Public License
28 * along with this program. If not, see <http://www.gnu.org/licenses/>.
30 class HtmlLinkHelper extends BaseHtmlHelper implements HelpableTemplate {
34 private $linkName = '';
39 private $linkBase = '';
42 * First parameter separator
44 const FIRST_PARAMETER_SEPARATOR = '?';
47 * SEPARATOR for more paraemters
49 const EXTRA_PARAMETER_SEPARATOR = '&';
52 * Protected constructor
56 protected function __construct () {
57 // Call parent constructor
58 parent::__construct(__CLASS__);
62 * Creates the helper class
64 * @param $templateInstance An instance of a template engine
65 * @param $linkName Name of the link we shall generate
66 * @param $linkBase Link base for the link. This parameter is deprecated.
67 * @return $helperInstance A prepared instance of this helper
68 * @throws NoConfigEntryException A deprecated exception at this point
70 public static final function createHtmlLinkHelper (CompileableTemplate $templateInstance, $linkName, $linkBase = NULL) {
72 $helperInstance = new HtmlLinkHelper();
74 // Set template instance
75 $helperInstance->setTemplateInstance($templateInstance);
78 $helperInstance->setLinkName($linkName);
80 // Get the application instance
81 $applicationInstance = Registry::getRegistry()->getInstance('application');
83 // Get the request instance
84 $requestInstance = $applicationInstance->getRequestInstance();
87 if (is_null($requestInstance)) {
88 // Throw an exception here
89 throw new NullPointerException($helperInstance, self::EXCEPTION_IS_NULL_POINTER);
92 // Get page (this will throw an exception if not set)
93 $command = $helperInstance->convertDashesToUnderscores($requestInstance->getRequestElement('command'));
95 // Construct config entry
96 $configEntry = $command . '_' . $linkName . '_action_url';
98 // Is the deprecated parameter set?
99 if (!is_null($linkBase)) {
100 // Then output a deprecation message
101 $helperInstance->deprecationWarning('[' . __METHOD__ . ':' . __LINE__ . ']: linkBase is deprecated. Please remove it from your templates and add a config entry ' . $configEntry . ' in your config.php file.');
104 // Determine link base from config now and 'command' request
106 $newLinkBase = $helperInstance->getConfigInstance()->getConfigEntry($configEntry);
107 $linkBase = $newLinkBase;
108 } catch (NoConfigEntryException $e) {
109 // Is the deprecated linkBase not set?
110 if (is_null($linkBase)) {
111 // Then throw again the exception
112 throw new NoConfigEntryException(array(__CLASS__, ($configEntry)), FrameworkConfiguration::EXCEPTION_CONFIG_ENTRY_WAS_NOT_FOUND);
117 $helperInstance->setLinkBase($linkBase);
120 $helperInstance->openGroupByIdContent('main', '', '');
122 // Return the prepared instance
123 return $helperInstance;
127 * Renders the link content (HTML code) with given link text and optional
130 * @param $linkText Link text to set in link
131 * @param $linkTitle Link title to set in link
132 * @param $extraContent Optional extra HTML content
133 * @return $linkContent Rendered text link content
135 private function renderLinkContentWithTextExtraContent ($linkText, $linkTitle, $extraContent='') {
136 // Construct link content
137 $linkContent = sprintf('<a href="{?base_url?}/%s%s" title="%s">%s</a>',
138 $this->getLinkBase(),
149 * Setter for link name
151 * @param $linkName Name of the link we shall generate
154 protected final function setLinkName ($linkName) {
155 $this->linkName = (string) $linkName;
159 * Getter for link name
161 * @return $linkName Name of the link we shall generate
163 public final function getLinkName () {
164 return $this->linkName;
168 * Setter for link base
170 * @param $linkBase Base of the link we shall generate
173 protected final function setLinkBase ($linkBase) {
174 $this->linkBase = (string) $linkBase;
178 * Getter for link base
180 * @return $linkBase Base of the link we shall generate
182 public final function getLinkBase () {
183 return $this->linkBase;
187 * Flush the content out,e g. to a template variable
190 * @todo Completely unimplemented
192 public function flushContent () {
193 // Is a previous opened group still open?
194 if ($this->ifGroupOpenedPreviously()) {
196 $this->closePreviousGroupByContent('');
200 $content = $this->renderContent();
202 // Get template engine
203 $templateInstance = $this->getTemplateInstance();
205 // Add content to variable
206 $templateInstance->assignVariable($this->getLinkName(), $content);
210 * Adds a link group (like the form group is) with some raw language to the
213 * @param $groupId Id string of the group
214 * @param $groupText Text for this group to add
215 * @param $groupCode Code to open and close groups
218 public function addLinkGroup ($groupId, $groupText, $groupCode = 'div') {
219 // Is a group with that name open?
220 if ($this->ifGroupOpenedPreviously()) {
221 // Then close it here
222 $this->closePreviousGroupByContent('');
225 // Generate the group content
226 $content = sprintf('<%s id="group_%s_%s">%s',
228 $this->getLinkName(),
233 // Open the new group
234 $this->openGroupByIdContent($groupId, $content, $groupCode);
238 * Adds text (note) to the previously opened group or throws an exception
239 * if no previous group was opened.
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
245 * @throws NoGroupOpenedException If no previous group was opened
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);
254 // Is a previous sub group open?
255 if ($this->ifSubGroupOpenedPreviously()) {
257 $this->closePreviousSubGroupByContent('</' . $groupCode . '>');
260 // Generate the group content
261 $content = sprintf('<%s id="subgroup_%s_%s">%s',
263 $this->getLinkName(),
268 // Open the sub group
269 $this->openSubGroupByIdContent($groupId, $content, $groupCode);
273 * Adds a link to the previously opened group or throws an exception if no group has been opened
275 * @param $linkAction Action (action=xxx) value for the link
276 * @param $linkText Link text and title (title="xxx") for the link
278 * @throws NoGroupOpenedException If no previous group was opened
280 protected function addActionLink ($linkAction, $linkText, $linkTitle) {
281 // Check if a previous group was opened
282 if ($this->ifGroupOpenedPreviously() === FALSE) {
283 // No group was opened before!
284 throw new NoGroupOpenedException(array($this, $linkAction . '(' . $linkText . ')'), self::EXCEPTION_GROUP_NOT_OPENED);
287 // Default parameter SEPARATOR is &
288 $separator = self::EXTRA_PARAMETER_SEPARATOR;
290 // Is there a question mark in?
291 $linkArray = explode(self::FIRST_PARAMETER_SEPARATOR, $this->getLinkBase());
292 if (count($linkArray) == 0) {
294 $separator = self::FIRST_PARAMETER_SEPARATOR;
298 $action = sprintf('%saction=%s',
303 // Renders the link content
304 $linkContent = $this->renderLinkContentWithTextExtraContent($linkText, $linkTitle, $action);
306 // Add the content to the previous group
307 $this->addContentToPreviousGroup($linkContent);
311 * Adds a link to the previously opened group with a text from language system
313 * @param $linkAction Action (action=xxx) value for the link
314 * @param $languageId Language id string to use
317 public function addActionLinkById ($linkAction, $languageId) {
318 // Resolve the language string
319 $languageResolvedText = $this->getLanguageInstance()->getMessage('link_' . $languageId . '_text');
321 // Resolve the language string
322 $languageResolvedTitle = $this->getLanguageInstance()->getMessage('link_' . $languageId . '_title');
324 // Add the action link
325 $this->addActionLink($linkAction, $languageResolvedText, $languageResolvedTitle);
329 * Adds a default link (no extra parameters) to the content with specified
330 * language id string.
332 * @param $languageId Language id string to use
335 public function addLinkWithTextById ($languageId) {
336 // Resolve the language string
337 $languageResolvedText = $this->getLanguageInstance()->getMessage('link_' . $languageId . '_text');
339 // Resolve the language string
340 $languageResolvedTitle = $this->getLanguageInstance()->getMessage('link_' . $languageId . '_title');
343 $linkContent = $this->renderLinkContentWithTextExtraContent($languageResolvedText, $languageResolvedTitle);
345 // Add the content to the previous group
346 $this->addContentToPreviousGroup($linkContent);