1 <?php
2 /**
3 * @package Joomla.Libraries
4 * @subpackage Help
5 *
6 * @copyright Copyright (C) 2005 - 2017 Open Source Matters, Inc. All rights reserved.
7 * @license GNU General Public License version 2 or later; see LICENSE.txt
8 */
9
10 defined('JPATH_PLATFORM') or die;
11
12 /**
13 * Help system class
14 *
15 * @since 1.5
16 */
17 class JHelp
18 {
19 /**
20 * Create a URL for a given help key reference
21 *
22 * @param string $ref The name of the help screen (its key reference)
23 * @param boolean $useComponent Use the help file in the component directory
24 * @param string $override Use this URL instead of any other
25 * @param string $component Name of component (or null for current component)
26 *
27 * @return string
28 *
29 * @since 1.5
30 */
31 public static function createUrl($ref, $useComponent = false, $override = null, $component = null)
32 {
33 $local = false;
34 $app = JFactory::getApplication();
35
36 if ($component === null)
37 {
38 $component = JApplicationHelper::getComponentName();
39 }
40
41 // Determine the location of the help file. At this stage the URL
42 // can contain substitution codes that will be replaced later.
43
44 if ($override)
45 {
46 $url = $override;
47 }
48 else
49 {
50 // Get the user help URL.
51 $user = JFactory::getUser();
52 $url = $user->getParam('helpsite');
53
54 // If user hasn't specified a help URL, then get the global one.
55 if ($url == '')
56 {
57 $url = $app->get('helpurl');
58 }
59
60 // Component help URL overrides user and global.
61 if ($useComponent)
62 {
63 // Look for help URL in component parameters.
64 $params = JComponentHelper::getParams($component);
65 $url = $params->get('helpURL');
66
67 if ($url == '')
68 {
69 $local = true;
70 $url = 'components/{component}/help/{language}/{keyref}';
71 }
72 }
73
74 // Set up a local help URL.
75 if (!$url)
76 {
77 $local = true;
78 $url = 'help/{language}/{keyref}';
79 }
80 }
81
82 // If the URL is local then make sure we have a valid file extension on the URL.
83 if ($local)
84 {
85 if (!preg_match('#\.html$|\.xml$#i', $ref))
86 {
87 $url .= '.html';
88 }
89 }
90
91 /*
92 * Replace substitution codes in the URL.
93 */
94 $lang = JFactory::getLanguage();
95 $version = new JVersion;
96 $jver = explode('.', $version->getShortVersion());
97 $jlang = explode('-', $lang->getTag());
98
99 $debug = $lang->setDebug(false);
100 $keyref = JText::_($ref);
101 $lang->setDebug($debug);
102
103 // Replace substitution codes in help URL.
104 $search = array(
105 // Application name (eg. 'Administrator')
106 '{app}',
107 // Component name (eg. 'com_content')
108 '{component}',
109 // Help screen key reference
110 '{keyref}',
111 // Full language code (eg. 'en-GB')
112 '{language}',
113 // Short language code (eg. 'en')
114 '{langcode}',
115 // Region code (eg. 'GB')
116 '{langregion}',
117 // Joomla major version number
118 '{major}',
119 // Joomla minor version number
120 '{minor}',
121 // Joomla maintenance version number
122 '{maintenance}',
123 );
124
125 $replace = array(
126 // {app}
127 $app->getName(),
128 // {component}
129 $component,
130 // {keyref}
131 $keyref,
132 // {language}
133 $lang->getTag(),
134 // {langcode}
135 $jlang[0],
136 // {langregion}
137 $jlang[1],
138 // {major}
139 $jver[0],
140 // {minor}
141 $jver[1],
142 // {maintenance}
143 $jver[2],
144 );
145
146 // If the help file is local then check it exists.
147 // If it doesn't then fallback to English.
148 if ($local)
149 {
150 $try = str_replace($search, $replace, $url);
151
152 if (!is_file(JPATH_BASE . '/' . $try))
153 {
154 $replace[3] = 'en-GB';
155 $replace[4] = 'en';
156 $replace[5] = 'GB';
157 }
158 }
159
160 $url = str_replace($search, $replace, $url);
161
162 return $url;
163 }
164
165 /**
166 * Builds a list of the help sites which can be used in a select option.
167 *
168 * @param string $pathToXml Path to an XML file.
169 *
170 * @return array An array of arrays (text, value, selected).
171 *
172 * @since 1.5
173 */
174 public static function createSiteList($pathToXml)
175 {
176 $list = array();
177 $xml = false;
178
179 if (!empty($pathToXml))
180 {
181 $xml = simplexml_load_file($pathToXml);
182 }
183
184 if (!$xml)
185 {
186 $option['text'] = 'English (GB) help.joomla.org';
187 $option['value'] = 'http://help.joomla.org';
188
189 $list[] = $option;
190 }
191 else
192 {
193 $option = array();
194
195 foreach ($xml->sites->site as $site)
196 {
197 $option['text'] = (string) $site;
198 $option['value'] = (string) $site->attributes()->url;
199
200 $list[] = $option;
201 }
202 }
203
204 return $list;
205 }
206 }
207