OC Templates
============
.. sectionauthor:: Bernhard Posselt <nukeawhale@gmail.com>

OC_Template
-----------

.. php:class:: OC_Template


  This class provides the templates for owncloud. It is used for loading template files, assign variables to it and render the whole template.

  .. php:method:: __construct($app, $name[, $renderas])

   :param string $app: the name of the app
   :param string $file: name of the template file (without suffix)
   :param string $renderas: If $renderas is set, OC_Template will try to produce a full page in the according layout. For now, renderas can be set to "guest", "user" or "admin"
   :returns: OC_Template object

   **Example:**

   .. code-block:: php

     <?php
     $mainTemplate = new OC_Template('news', 'main', 'user');
     ?>


  .. php:method:: addHeader($tag, $attributes[, $text=''])

   :param string $tag: tag name of the element
   :param array $attributes: array of attrobutes for the element
   :param string $text: the text content for the element

   Add a custom element to the html <head>

   **Example:**

   .. code-block:: php

     <?php
     $mainTemplate = new OC_Template('news', 'main', 'user');
     $mainTemplate->addHeader('title', array(), 'My new Page');
     ?>

  .. php:method:: append($key, $value)

   :param string $key: the key under which the variable can be accessed in the template
   :param $value: the value that we want to pass
   :returns: bool

   This function assigns a variable in an array context. If the key already exists, the value will be appended. It can be accessed via $_[$key][$position] in the template.

   **Example:**

   .. code-block:: php

     <?php
     $customers = array("john", "frank");

     $mainTemplate = new OC_Template('news', 'main', 'user');
     $mainTemplate->assign('customers', $customers);
     $mainTemplate->append('customers', 'hanna');
     ?>


  .. php:method:: assign($key, $value)

   :param string $key: the key under which the variable can be accessed in the template
   :param $value: the value that we want to pass
   :returns: bool

   This function assigns a variable. It can be accessed via $_[$key] in the template. If the key existed before, it will be overwritten

   **Example:**

   .. code-block:: php

     <?php
     $customers = array("john", "frank");

     $mainTemplate = new OC_Template('news', 'main', 'user');
     $mainTemplate->assign('customers', $customers);
     ?>


  .. php:method:: detectFormfactor()

   :returns: The mode of the client as a string. **default** -> the normal desktop browser interface, **mobile** -> interface for smartphones, **tablet** -> interface for tablets, **standalone** -> the default interface but without header, footer and sidebar, just the application. Useful to use just a specific app on the desktop in a standalone window.

   **Example:**

   .. code-block:: php

     <?php
     $mainTemplate = new OC_Template('news', 'main', 'user');
     $formFactor = $mainTemplate->detectFormfactor();
     ?>


  .. php:method:: fetchPage()

   :returns: the HTML of the template as string

   This function proceeds the template and but prints no output.

   **Example:**

   .. todo:: provide example


  .. php:method:: getFormFactorExtension()

   :returns: Returns the formfactor extension for current formfactor (like .mobile or .tablet)


   **Example:**

   .. code-block:: php

     <?php
     $mainTemplate = new OC_Template('news', 'main', 'user');
     $formFactorExtension = $mainTemplate->detectFormfactorExtension();
     ?>


  .. php:method:: inc($file[, $additionalparams])

   :param string $file: the name of the template
   :param array $additionalparams: an array with additional variables which should be used for the included template
   :returns: returns content of included template as a string

   Includes another template. use <?php print_unescaped($this->inc('template')); ?> to do this. The included template has access to all parent template variables!

   **Example:**

   .. code-block:: php

     <div>
         <?php print_unescaped($this->inc('nav.inc', array('active' => 'nav_entry_1')); ?>
     </div>


  .. php:method:: printPage()

   :returns: true when there is content to print

   This function proceeds the template and prints its output.

   **Example:**

   .. code-block:: php

     <?php
     $mainTemplate = new OC_Template('news', 'main', 'user');
     $mainTemplate->assign('test', array("test", "test2"));
     $mainTemplate->printPage();
     ?>

  .. php:method:: printAdminPage($application, $name[, $parameters])

   :param string $application: The application we render the template for
   :param string $name: Name of the template
   :param array $parameters: Parameters for the template
   :returns: bool

   Shortcut to print a simple page for admin

   **Example:**

   .. todo:: provide example


  .. php:method:: printGuestPage($application, $name[, $parameters])

   :param string $application: The application we render the template for
   :param string $name: Name of the template
   :param array $parameters: Parameters for the template
   :returns: bool

   Shortcut to print a simple page for guests

   **Example:**

   .. todo:: provide example


  .. php:method:: printUserPage($application, $name[, $parameters])

   :param string $application: The application we render the template for
   :param string $name: Name of the template
   :param array $parameters: Parameters for the template
   :returns: bool

   Shortcut to print a simple page for users

   **Example:**

   .. todo:: provide example



Template functions
------------------

These functions are automatically available in all templates.

html_select_options
~~~~~~~~~~~~~~~~~~~
.. php:function::  html_select_options($options, $selected[, $params])

  :param array $options: an array of the form value => label
  :param string/array $selected: an array containing strings or a simple string which sets a value as selected
  :param array $params: optional parameters that are done in key => value
  :returns: the html as string of preset <option> tags

.. todo:: Fix parameters and add example



human_file_size
~~~~~~~~~~~~~~~
.. php:function:: human_file_size($bytes)

  :param int $bytes: the bytes that we want to convert to a more readable format
  :returns: the human readable size as string

Turns bytes into human readable formats, for instance 1024 bytes get turned into 1kb, 1024*1024 bytes get turned into 1mb

.. code-block:: php

  <?php
  // this would print <li>2kB</li>
  ?>
  <li><?php p($this->human_file_size('2048')); ?></li>



image_path
~~~~~~~~~~
.. php:function:: image_path($app, $image)

  :param string $app: the name of your app as a string. If the string is empty, ownCloud looks for the image in core
  :param array $image: the filename of the image
  :returns: the absolute URL to the image as a string

This function looks up images in several common directories and returns the full link to it. The following directories are being searched:

- /themes/$theme/apps/$app/img/$image
- /themes/$theme/$app/img/$image
- /$app/img/$image

When you pass an empty string for $app, the following directories will be searched:

- /themes/$theme/apps/$app/img/$image
- /themes/$theme/core/img/$image
- /core/img/$image

**Example:**

.. code-block:: php

  <img src="<?php print_unescaped(
    image_path('news', 'starred.svg');
  ); ?>" />




link_to
~~~~~~~
.. php:function:: link_to($app, $file, [$args])

  :param string $app: the name of your app as a string. If the string is empty, ownCloud asumes that the file is in /core/
  :param string $file: the relative path from your apps root to the file you want to access
  :param array $args: the GET parameters that you want set in the URL in form key => value. The value will be run through urlencode()
  :returns: the absolute URL to the file

This function is used to produce generate clean and absolute links to your files or pages.

**Example:**

.. code-block:: php

  <?php
  // this will produce the link:
  // index.php/news/pages/weather.php?show=berlin
  ?>
  <ul>
    <li><a href="<?php
            print_unescaped(
                link_to('news', 'pages/weather.php', array("show" => "berlin"));
            );
         ?>">Show Weather for Berlin</a></li>
  </ul>



mimetype_icon
~~~~~~~~~~~~~
.. php:function:: mimetype_icon($mimetype)

  :param array $mimetype: the mimetype for which we want to look up the icon
  :returns: the absolute URL to the icon

A shortcut for getting a mimetype icon.

**Example:**

.. code-block:: php

  <img src="<?php print_unescaped(
    mimetype_icon('application/xml');
  ); ?>" />



p
~
.. php:function:: p($data)

  :param $data: the variable/array/object that should be printed

.. versionadded:: 5.0

This is the print statement which prints out XSS escaped values. ownCloud does not allow the direct usage of echo or print but enforces wrapper functions to prevent unwanted XSS vulnerabilities. If you want to print unescaped data, look at print_unescaped

**Example:**

.. code-block:: php

  <?php $names = array("John", "Jakob", "Tom"); ?>
  <div>
    <ul>
      <?php foreach($names as $name){ ?>
        <li><?php p($name); ?></li>
      <?php } ?>
    </ul>
  </div>



print_unescaped
~~~~~~~~~~~~~~~
.. php:function:: print_unescaped($data)

  :param $data: the variable/array/object that should be printed

.. versionadded:: 5.0

This function does not escape the content for XSS. This would typically be used to print HTML or JavaScript that is generated by the server and **checked for XSS** vulnerabilities.


**Example:**

.. code-block:: php

  <?php $html = "<div>Some HTML</div>"; ?>
  <div>
    <?php print_unescaped($html); ?>
  </div>



relative_modified_date
~~~~~~~~~~~~~~~~~~~~~~
.. php:function::  relative_modified_date($timestamp)

  :param int $timestamp: the timestamp from whom we compute the time span until now
  :returns: a relative date as string

Instead of displaying a date, it is often better to give a relative date like: "2 days ago" or "3 hours ago". This function turns a timestamp into a relative date.

.. code-block:: php

  <?php
  // this would print <span>5 minutes ago</span>
  ?>
  <span><?php p(relative_modified_date('29393992912')); ?></span>



simple_file_size
~~~~~~~~~~~~~~~~
.. php:function::  simple_file_size($bytes)

  :param int $bytes: the bytes that we want to convert to a more readable format in megabytes
  :returns: the human readable size as string

A more simpler function that only turns bytes into megabytes. If its smaller than 0.1 megabytes, < 0.1 is being returned. If its bigger than 1000 megabytes, > 1000 is being returned.

.. code-block:: php

  <?php
  // this would print <li>&lt 0.1</li>
  ?>
  <li><?php p(simple_file_size('2048')); ?></li>



Further reading
---------------
- http://en.wikipedia.org/wiki/Cross-site_scripting
- https://www.owasp.org/index.php/XSS_Filter_Evasion_Cheat_Sheet
- https://www.owasp.org/index.php/Cross-site_Scripting_%28XSS%29
