1: <?php
  2: /**
  3:  * The Horde_Help:: class provides an interface to the online help subsystem.
  4:  *
  5:  * Copyright 1999-2012 Horde LLC (http://www.horde.org/)
  6:  *
  7:  * See the enclosed file COPYING for license information (LGPL). If you
  8:  * did not receive this file, see http://www.horde.org/licenses/lgpl21.
  9:  *
 10:  * @author   Jon Parise <jon@horde.org>
 11:  * @category Horde
 12:  * @package  Core
 13:  */
 14: class Horde_Help
 15: {
 16:     /* Raw help in the string. */
 17:     const SOURCE_RAW = 0;
 18: 
 19:     /* Help text is in a file. */
 20:     const SOURCE_FILE = 1;
 21: 
 22:     /**
 23:      * Handle for the XML object.
 24:      *
 25:      * @var SimpleXMLElement
 26:      */
 27:     protected $_xml;
 28: 
 29:     /**
 30:      * String containing the charset of the XML data source.
 31:      *
 32:      * @var string
 33:      */
 34:     protected $_charset = 'iso-8859-1';
 35: 
 36:     /**
 37:      * Constructor.
 38:      *
 39:      * @param integer $source  The source of the XML help data, based on the
 40:      *                         SOURCE_* constants.
 41:      * @param array $data      The list of data sources to use.
 42:      *
 43:      * @throws Horde_Exception
 44:      */
 45:     public function __construct($source, $data = array())
 46:     {
 47:         if (!Horde_Util::extensionExists('SimpleXML')) {
 48:             throw new Horde_Exception('SimpleXML not available.');
 49:         }
 50: 
 51:         if ($charset = $GLOBALS['registry']->nlsconfig->curr_charset) {
 52:             $this->_charset = $charset;
 53:         }
 54: 
 55:         switch ($source) {
 56:         case self::SOURCE_RAW:
 57:             $this->_xml = new SimpleXMLElement($data[0]);
 58:             break;
 59: 
 60:         case self::SOURCE_FILE:
 61:             foreach ($data as $val) {
 62:                 if (@is_file($val)) {
 63:                     $this->_xml = new SimpleXMLElement($val, null, true);
 64:                     break;
 65:                 }
 66:             }
 67:             break;
 68:         }
 69:         /* SimpleXML cannot deal with mixed text/data nodes. Convert all text descendants of para to <text> tags */
 70:         $dom = dom_import_simplexml($this->_xml);
 71:         $xpath = new DOMXpath($dom->ownerDocument);
 72:         $textnodes = $xpath->query('//para/text()');
 73:         foreach ($textnodes as $text) {
 74:             $text->parentNode->replaceChild(new DOMElement('text', $text->nodeValue), $text);
 75:         }
 76:         $this->_xml = simplexml_import_dom($dom);
 77:     }
 78: 
 79:     /**
 80:      * Looks up the requested entry in the XML help buffer.
 81:      *
 82:      * @param string $id  String containing the entry ID.
 83:      *
 84:      * @return string  The HTML formatted help entry.
 85:      */
 86:     public function lookup($id)
 87:     {
 88:         $out = '';
 89: 
 90:         foreach ($this->_xml->entry as $entry) {
 91:             if ($entry->attributes()->id == $id) {
 92:                 foreach ($entry->children() as $child) {
 93:                     switch ($child->getName()) {
 94:                     case 'heading':
 95:                         $out .= '<h2>' . $this->_processNode($child) . '</h2>';
 96:                         break;
 97: 
 98:                     case 'para':
 99:                         $out .= '<p>' . $this->_processNode($child) . '</p>';
100:                         break;
101: 
102:                     case 'raw':
103:                         $out .= '<p class="fixed">' . htmlentities($this->_processNode($child)) . '</p>';
104:                         break;
105: 
106:                     case 'title':
107:                         $out .= '<h1>' . $this->_processNode($child) . '</h1>';
108:                         break;
109:                     }
110:                 }
111:             }
112:         }
113: 
114:         return $out;
115:     }
116: 
117:     /**
118:      * Process a help node
119:      * @param SimpleXMLElement An XML help node representation
120:      * @return string an output string with HTML
121:      */
122:     protected function _processNode($node)
123:     {
124:         if (!count($node->children())) {
125:             return strval($node);
126:         }
127: 
128:         $out = '';
129: 
130:         foreach ($node->children() as $child) {
131:             switch ($child->getName()) {
132:             case 'ref':
133:                 $out .= Horde::link(Horde::selfUrl()->add(array(
134:                     'module' => $child->attributes()->module,
135:                     'show' => 'entry',
136:                     'topic'  => $child->attributes()->entry
137:                 ))) . strval($child) . '</a>';
138:                 break;
139:             case 'text':
140:                 $out .= strval($child);
141:                 break;
142:             case 'eref':
143:                 $out .= Horde::link($child->attributes()->url, null, '', '_blank') . strval($child) . '</a>';
144:                 break;
145: 
146:             case 'href':
147:                 $out .= Horde::link(Horde::url($GLOBALS['registry']->get('webroot', $child->attributes()->app) . '/' . $child->attributes()->url), null, '', '_blank') . strval($child) . '</a>';
148:                 break;
149: 
150:             case 'b':
151:                 $out .= '<strong>' . strval($child) . '</strong>';
152:                 break;
153: 
154:             case 'i':
155:                 $out .= '<em>' . strval($child) . '</em>';
156:                 break;
157: 
158:             case 'pre':
159:                 $out .= '<pre>' . strval($child) . '</pre>';
160:                 break;
161: 
162:             case 'tip':
163:                 $out .= '<em class="helpTip">' . strval($child) . '</em>';
164:                 break;
165: 
166:             case 'warn':
167:                 $out .= '<em class="helpWarn">' . strval($child) . '</em>';
168:                 break;
169:             }
170:         }
171: 
172:         return $out;
173:     }
174: 
175:     /**
176:      * Returns a hash of all of the topics in this help buffer
177:      * containing the keyword specified.
178:      *
179:      * @return array  Hash of all of the search results.
180:      */
181:     public function search($keyword)
182:     {
183:         $results = array();
184: 
185:         foreach ($this->_xml->entry as $entry) {
186:             foreach ($entry as $elt) {
187:                 if (stripos(strval($elt), $keyword) !== false) {
188:                     $results[strval($entry->attributes()->id)] = strval($entry->title);
189:                     break;
190:                 }
191:             }
192:         }
193: 
194:         return $results;
195:     }
196: 
197:     /**
198:      * Returns a hash of all of the topics in this help buffer.
199:      *
200:      * @return array  Hash of all of the topics in this buffer (keys are IDs,
201:      *                values are the title names).
202:      */
203:     public function topics()
204:     {
205:         $topics = array();
206: 
207:         foreach ($this->_xml->entry as $elt) {
208:             $topics[strval($elt->attributes()->id)] = strval($elt->title);
209:         }
210: 
211:         return $topics;
212:     }
213: 
214: 
215:     /**
216:      * Generates the HTML link that will pop up a help window for the
217:      * requested topic.
218:      *
219:      * @param string $module  The name of the current Horde module.
220:      * @param string $topic   The help topic to be displayed.
221:      *
222:      * @return string  The HTML to create the help link.
223:      */
224:     static public function link($module, $topic)
225:     {
226:         if (!Horde_Menu::showService('help')) {
227:             return '';
228:         }
229: 
230:         $url = Horde::getServiceLink('help', $module)->add('topic', $topic);
231:         return $url->link(array('title' => Horde_Core_Translation::t("Help"), 'class' => 'helplink', 'target' => 'hordehelpwin', 'onclick' => Horde::popupJs($url, array('urlencode' => true)) . 'return false;'))
232:             . Horde::img('help.png', Horde_Core_Translation::t("Help")) . '</a>';
233:     }
234: 
235: }
236: