lib/htmloutputter.php

   1 <?php
   2 /**
   3  * StatusNet, the distributed open-source microblogging tool
   4  *
   5  * Low-level generator for HTML
   6  *
   7  * PHP version 5
   8  *
   9  * LICENCE: This program is free software: you can redistribute it and/or modify
  10  * it under the terms of the GNU Affero General Public License as published by
  11  * the Free Software Foundation, either version 3 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * This program is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU Affero General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Affero General Public License
  20  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  21  *
  22  * @category  Output
  23  * @package   StatusNet
  24  * @author    Evan Prodromou <evan@status.net>
  25  * @author    Sarven Capadisli <csarven@status.net>
  26  * @copyright 2008 StatusNet, Inc.
  27  * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
  28  * @link      http://status.net/
  29  */
  30
  31 if (!defined('STATUSNET') && !defined('LACONICA')) {
  32     exit(1);
  33 }
  34
  35 require_once INSTALLDIR.'/lib/xmloutputter.php';
  36
  37 // Can include XHTML options but these are too fragile in practice.
  38 define('PAGE_TYPE_PREFS', 'text/html');
  39
  40 /**
  41  * Low-level generator for HTML
  42  *
  43  * Abstracts some of the code necessary for HTML generation. Especially
  44  * has methods for generating HTML form elements. Note that these have
  45  * been created kind of haphazardly, not with an eye to making a general
  46  * HTML-creation class.
  47  *
  48  * @category Output
  49  * @package  StatusNet
  50  * @author   Evan Prodromou <evan@status.net>
  51  * @author   Sarven Capadisli <csarven@status.net>
  52  * @license  http://www.fsf.org/licensing/licenses/agpl-3.0.html GNU Affero General Public License version 3.0
  53  * @link     http://status.net/
  54  *
  55  * @see      Action
  56  * @see      XMLOutputter
  57  */
  58
  59 class HTMLOutputter extends XMLOutputter
  60 {
  61     /**
  62      * Constructor
  63      *
  64      * Just wraps the XMLOutputter constructor.
  65      *
  66      * @param string  $output URI to output to, default = stdout
  67      * @param boolean $indent Whether to indent output, default true
  68      */
  69
  70     function __construct($output='php://output', $indent=true)
  71     {
  72         parent::__construct($output, $indent);
  73     }
  74
  75     /**
  76      * Start an HTML document
  77      *
  78      * If $type isn't specified, will attempt to do content negotiation.
  79      *
  80      * Attempts to do content negotiation for language, also.
  81      *
  82      * @param string $type MIME type to use; default is to do negotation.
  83      *
  84      * @todo extract content negotiation code to an HTTP module or class.
  85      *
  86      * @return void
  87      */
  88
  89     function startHTML($type=null)
  90     {
  91         if (!$type) {
  92             $httpaccept = isset($_SERVER['HTTP_ACCEPT']) ?
  93               $_SERVER['HTTP_ACCEPT'] : null;
  94
  95             // XXX: allow content negotiation for RDF, RSS, or XRDS
  96
  97             $cp = common_accept_to_prefs($httpaccept);
  98             $sp = common_accept_to_prefs(PAGE_TYPE_PREFS);
  99
 100             $type = common_negotiate_type($cp, $sp);
 101
 102             if (!$type) {
 103                 throw new ClientException(_('This page is not available in a '.
 104                                             'media type you accept'), 406);
 105             }
 106         }
 107
 108         header('Content-Type: '.$type);
 109
 110         $this->extraHeaders();
 111         if (preg_match("/.*\/.*xml/", $type)) {
 112             // Required for XML documents
 113             $this->xw->startDocument('1.0', 'UTF-8');
 114         }
 115         $this->xw->writeDTD('html',
 116                             '-//W3C//DTD XHTML 1.0 Strict//EN',
 117                             'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd');
 118
 119         $language = $this->getLanguage();
 120
 121         $this->elementStart('html', array('xmlns' => 'http://www.w3.org/1999/xhtml',
 122                                           'xml:lang' => $language,
 123                                           'lang' => $language));
 124     }
 125
 126     function getLanguage()
 127     {
 128         // FIXME: correct language for interface
 129         return common_language();
 130     }
 131
 132     /**
 133     *  Ends an HTML document
 134     *
 135     *  @return void
 136     */
 137     function endHTML()
 138     {
 139         $this->elementEnd('html');
 140         $this->endXML();
 141     }
 142
 143     /**
 144     *  To specify additional HTTP headers for the action
 145     *
 146     *  @return void
 147     */
 148     function extraHeaders()
 149     {
 150         // Needs to be overloaded
 151     }
 152
 153     /**
 154      * Output an HTML text input element
 155      *
 156      * Despite the name, it is specifically for outputting a
 157      * text input element, not other <input> elements. It outputs
 158      * a cluster of elements, including a <label> and an associated
 159      * instructions span.
 160      *
 161      * @param string $id           element ID, must be unique on page
 162      * @param string $label        text of label for the element
 163      * @param string $value        value of the element, default null
 164      * @param string $instructions instructions for valid input
 165      *
 166      * @todo add a $name parameter
 167      * @todo add a $maxLength parameter
 168      * @todo add a $size parameter
 169      *
 170      * @return void
 171      */
 172
 173     function input($id, $label, $value=null, $instructions=null)
 174     {
 175         $this->element('label', array('for' => $id), $label);
 176         $attrs = array('name' => $id,
 177                        'type' => 'text',
 178                        'id' => $id);
 179         if ($value) {
 180             $attrs['value'] = $value;
 181         }
 182         $this->element('input', $attrs);
 183         if ($instructions) {
 184             $this->element('p', 'form_guide', $instructions);
 185         }
 186     }
 187
 188     /**
 189      * output an HTML checkbox and associated elements
 190      *
 191      * Note that the value is default 'true' (the string), which can
 192      * be used by Action::boolean()
 193      *
 194      * @param string $id           element ID, must be unique on page
 195      * @param string $label        text of label for the element
 196      * @param string $checked      if the box is checked, default false
 197      * @param string $instructions instructions for valid input
 198      * @param string $value        value of the checkbox, default 'true'
 199      * @param string $disabled     show the checkbox disabled, default false
 200      *
 201      * @return void
 202      *
 203      * @todo add a $name parameter
 204      */
 205
 206     function checkbox($id, $label, $checked=false, $instructions=null,
 207                       $value='true', $disabled=false)
 208     {
 209         $attrs = array('name' => $id,
 210                        'type' => 'checkbox',
 211                        'class' => 'checkbox',
 212                        'id' => $id);
 213         if ($value) {
 214             $attrs['value'] = $value;
 215         }
 216         if ($checked) {
 217             $attrs['checked'] = 'checked';
 218         }
 219         if ($disabled) {
 220             $attrs['disabled'] = 'true';
 221         }
 222         $this->element('input', $attrs);
 223         $this->text(' ');
 224         $this->element('label', array('class' => 'checkbox',
 225                                       'for' => $id),
 226                        $label);
 227         $this->text(' ');
 228         if ($instructions) {
 229             $this->element('p', 'form_guide', $instructions);
 230         }
 231     }
 232
 233     /**
 234      * output an HTML combobox/select and associated elements
 235      *
 236      * $content is an array of key-value pairs for the dropdown, where
 237      * the key is the option value attribute and the value is the option
 238      * text. (Careful on the overuse of 'value' here.)
 239      *
 240      * @param string $id           element ID, must be unique on page
 241      * @param string $label        text of label for the element
 242      * @param array  $content      options array, value => text
 243      * @param string $instructions instructions for valid input
 244      * @param string $blank_select whether to have a blank entry, default false
 245      * @param string $selected     selected value, default null
 246      *
 247      * @return void
 248      *
 249      * @todo add a $name parameter
 250      */
 251
 252     function dropdown($id, $label, $content, $instructions=null,
 253                       $blank_select=false, $selected=null)
 254     {
 255         $this->element('label', array('for' => $id), $label);
 256         $this->elementStart('select', array('id' => $id, 'name' => $id));
 257         if ($blank_select) {
 258             $this->element('option', array('value' => ''));
 259         }
 260         foreach ($content as $value => $option) {
 261             if ($value == $selected) {
 262                 $this->element('option', array('value' => $value,
 263                                                'selected' => 'selected'),
 264                                $option);
 265             } else {
 266                 $this->element('option', array('value' => $value), $option);
 267             }
 268         }
 269         $this->elementEnd('select');
 270         if ($instructions) {
 271             $this->element('p', 'form_guide', $instructions);
 272         }
 273     }
 274
 275     /**
 276      * output an HTML hidden element
 277      *
 278      * $id is re-used as name
 279      *
 280      * @param string $id    element ID, must be unique on page
 281      * @param string $value hidden element value, default null
 282      * @param string $name  name, if different than ID
 283      *
 284      * @return void
 285      */
 286
 287     function hidden($id, $value, $name=null)
 288     {
 289         $this->element('input', array('name' => ($name) ? $name : $id,
 290                                       'type' => 'hidden',
 291                                       'id' => $id,
 292                                       'value' => $value));
 293     }
 294
 295     /**
 296      * output an HTML password input and associated elements
 297      *
 298      * @param string $id           element ID, must be unique on page
 299      * @param string $label        text of label for the element
 300      * @param string $instructions instructions for valid input
 301      *
 302      * @return void
 303      *
 304      * @todo add a $name parameter
 305      */
 306
 307     function password($id, $label, $instructions=null)
 308     {
 309         $this->element('label', array('for' => $id), $label);
 310         $attrs = array('name' => $id,
 311                        'type' => 'password',
 312                        'class' => 'password',
 313                        'id' => $id);
 314         $this->element('input', $attrs);
 315         if ($instructions) {
 316             $this->element('p', 'form_guide', $instructions);
 317         }
 318     }
 319
 320     /**
 321      * output an HTML submit input and associated elements
 322      *
 323      * @param string $id    element ID, must be unique on page
 324      * @param string $label text of the button
 325      * @param string $cls   class of the button, default 'submit'
 326      * @param string $name  name, if different than ID
 327      *
 328      * @return void
 329      *
 330      * @todo add a $name parameter
 331      */
 332
 333     function submit($id, $label, $cls='submit', $name=null, $title=null)
 334     {
 335         $this->element('input', array('type' => 'submit',
 336                                       'id' => $id,
 337                                       'name' => ($name) ? $name : $id,
 338                                       'class' => $cls,
 339                                       'value' => $label,
 340                                       'title' => $title));
 341     }
 342
 343     /**
 344      * output a script (almost always javascript) tag
 345      *
 346      * @param string $src          relative or absolute script path
 347      * @param string $type         'type' attribute value of the tag
 348      *
 349      * @return void
 350      */
 351     function script($src, $type='text/javascript')
 352     {
 353         if(Event::handle('StartScriptElement', array($this,&$src,&$type))) {
 354             $url = parse_url($src);
 355             if( empty($url->scheme) && empty($url->host) && empty($url->query) && empty($url->fragment))
 356             {
 357                 $src = common_path($src) . '?version=' . STATUSNET_VERSION;
 358             }
 359             $this->element('script', array('type' => $type,
 360                                                    'src' => $src),
 361                                    ' ');
 362             Event::handle('EndScriptElement', array($this,$src,$type));
 363         }
 364     }
 365
 366     /**
 367      * output a script (almost always javascript) tag with inline
 368      * code.
 369      *
 370      * @param string $code         code to put in the script tag
 371      * @param string $type         'type' attribute value of the tag
 372      *
 373      * @return void
 374      */
 375
 376     function inlineScript($code, $type='text/javascript')
 377     {
 378         if(Event::handle('StartInlineScriptElement', array($this,&$code,&$type))) {
 379             $this->elementStart('script', array('type' => $type));
 380             if($type == 'text/javascript') {
 381                 $this->raw('/*<![CDATA[*/ '); // XHTML compat
 382             }
 383             $this->raw($code);
 384             if($type == 'text/javascript') {
 385                 $this->raw(' /*]]>*/'); // XHTML compat
 386             }
 387             $this->elementEnd('script');
 388             Event::handle('EndInlineScriptElement', array($this,$code,$type));
 389         }
 390     }
 391
 392     /**
 393      * output a css link
 394      *
 395      * @param string $src     relative path within the theme directory, or an absolute path
 396      * @param string $theme        'theme' that contains the stylesheet
 397      * @param string media         'media' attribute of the tag
 398      *
 399      * @return void
 400      */
 401     function cssLink($src,$theme=null,$media=null)
 402     {
 403         if(Event::handle('StartCssLinkElement', array($this,&$src,&$theme,&$media))) {
 404             $url = parse_url($src);
 405             if( empty($url->scheme) && empty($url->host) && empty($url->query) && empty($url->fragment))
 406             {
 407                 if(file_exists(Theme::file($src,$theme))){
 408                    $src = Theme::path($src, $theme) . '?version=' . STATUSNET_VERSION;
 409                 }else{
 410                    $src = common_path($src);
 411                 }
 412             }
 413             $this->element('link', array('rel' => 'stylesheet',
 414                                     'type' => 'text/css',
 415                                     'href' => $src,
 416                                     'media' => $media));
 417             Event::handle('EndCssLinkElement', array($this,$src,$theme,$media));
 418         }
 419     }
 420
 421     /**
 422      * output a style (almost always css) tag with inline
 423      * code.
 424      *
 425      * @param string $code         code to put in the style tag
 426      * @param string $type         'type' attribute value of the tag
 427      * @param string $media        'media' attribute value of the tag
 428      *
 429      * @return void
 430      */
 431
 432     function style($code, $type = 'text/css', $media = null)
 433     {
 434         if(Event::handle('StartStyleElement', array($this,&$code,&$type,&$media))) {
 435             $this->elementStart('style', array('type' => $type, 'media' => $media));
 436             $this->raw($code);
 437             $this->elementEnd('style');
 438             Event::handle('EndStyleElement', array($this,$code,$type,$media));
 439         }
 440     }
 441
 442     /**
 443      * output an HTML textarea and associated elements
 444      *
 445      * @param string $id           element ID, must be unique on page
 446      * @param string $label        text of label for the element
 447      * @param string $content      content of the textarea, default none
 448      * @param string $instructions instructions for valid input
 449      *
 450      * @return void
 451      *
 452      * @todo add a $name parameter
 453      * @todo add a $cols parameter
 454      * @todo add a $rows parameter
 455      */
 456
 457     function textarea($id, $label, $content=null, $instructions=null)
 458     {
 459         $this->element('label', array('for' => $id), $label);
 460         $this->element('textarea', array('rows' => 3,
 461                                          'cols' => 40,
 462                                          'name' => $id,
 463                                          'id' => $id),
 464                        ($content) ? $content : '');
 465         if ($instructions) {
 466             $this->element('p', 'form_guide', $instructions);
 467         }
 468     }
 469
 470     /**
 471     * Internal script to autofocus the given element on page onload.
 472     *
 473     * @param string $id element ID, must refer to an existing element
 474     *
 475     * @return void
 476     *
 477     */
 478     function autofocus($id)
 479     {
 480         $this->inlineScript(
 481                    ' $(document).ready(function() {'.
 482                    ' var el = $("#' . $id . '");'.
 483                    ' if (el.length) { el.focus(); }'.
 484                    ' });');
 485     }
 486 }