Merge branch 'master' of github.com:owncloud/documentation

This commit is contained in:
Thomas Tanghus
2012-10-31 23:51:41 +01:00
17 changed files with 601 additions and 1866 deletions

View File

@@ -164,9 +164,11 @@
<div class="sidebar">
<div class="well">
<div class="menu-support-container">
<a href="{{ pathto(master_doc) }}">Overview</a>
<ul id="menu-support" class="menu">
{{ toctree(maxdepth=2) }}
<ul>
<li><a href="{{ pathto(master_doc) }}">Overview</a></li>
</ul>
{{ toctree(maxdepth=3) }}
</ul>
</div>
</div>

File diff suppressed because it is too large Load Diff

Before

Width:  |  Height:  |  Size: 55 KiB

View File

@@ -0,0 +1,103 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="32px"
height="32px"
id="svg3144"
version="1.1"
inkscape:version="0.48.3.1 r9886"
sodipodi:docname="note.svg">
<defs
id="defs3146" />
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="15.836083"
inkscape:cx="22.624214"
inkscape:cy="19.106159"
inkscape:current-layer="layer1"
showgrid="true"
inkscape:grid-bbox="true"
inkscape:document-units="px"
inkscape:window-width="1363"
inkscape:window-height="795"
inkscape:window-x="1774"
inkscape:window-y="204"
inkscape:window-maximized="0"
showguides="true"
inkscape:guide-bbox="true">
<inkscape:grid
type="xygrid"
id="grid3160"
empspacing="5"
visible="true"
enabled="true"
snapvisiblegridlinesonly="true" />
</sodipodi:namedview>
<metadata
id="metadata3149">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title></dc:title>
</cc:Work>
</rdf:RDF>
</metadata>
<g
id="layer1"
inkscape:label="Layer 1"
inkscape:groupmode="layer">
<g
style="font-size:22.75667953px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#808080;fill-opacity:1;stroke:none;font-family:Umpush;-inkscape-font-specification:Umpush"
id="text3156" />
<path
sodipodi:type="arc"
style="fill:none;stroke:#333333;stroke-width:2.81128564999999986;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="path4025"
sodipodi:cx="-1"
sodipodi:cy="6"
sodipodi:rx="11"
sodipodi:ry="11"
d="M 10,6 A 11,11 0 1 1 -12,6 11,11 0 1 1 10,6 z"
transform="matrix(1.2727273,0,0,1.2727273,17.272727,8.363636)" />
<g
id="g4637"
transform="matrix(0.92719971,0,0,0.92719971,1.1648051,1.7655471)">
<g
id="g4660"
style="fill:#333333;fill-opacity:1">
<path
sodipodi:type="arc"
style="fill:#333333;fill-opacity:1"
id="path4605"
sodipodi:cx="16"
sodipodi:cy="23"
sodipodi:rx="2"
sodipodi:ry="2"
d="m 18,23 c 0,1.104569 -0.895431,2 -2,2 -1.104569,0 -2,-0.895431 -2,-2 0,-1.104569 0.895431,-2 2,-2 1.104569,0 2,0.895431 2,2 z"
transform="matrix(1.1176471,0,0,1.1176471,-1.8823536,-1.9705883)" />
<path
style="fill:#333333;fill-opacity:1"
d="m 18.240641,12 c -0.357431,3.993456 -1.000776,7.264706 -2.235294,7.264706 -1.234518,0 -1.833524,-3.2762 -2.235294,-7.264706 C 13.243883,6.7765275 13.896254,4.6647937 16.005347,4.735294 18.522001,4.819419 18.614239,7.8259215 18.240641,12 z"
id="path4605-7"
inkscape:connector-curvature="0"
sodipodi:nodetypes="sssss" />
</g>
</g>
</g>
</svg>

After

Width:  |  Height:  |  Size: 3.5 KiB

View File

@@ -0,0 +1,114 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="32px"
height="32px"
id="svg3144"
version="1.1"
inkscape:version="0.48.3.1 r9886"
sodipodi:docname="todo.svg">
<defs
id="defs3146" />
<sodipodi:namedview
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="5.5989008"
inkscape:cx="-8.2783935"
inkscape:cy="22.714444"
inkscape:current-layer="layer1"
showgrid="true"
inkscape:grid-bbox="true"
inkscape:document-units="px"
inkscape:window-width="1855"
inkscape:window-height="1056"
inkscape:window-x="1431"
inkscape:window-y="24"
inkscape:window-maximized="1"
showguides="true"
inkscape:guide-bbox="true">
<inkscape:grid
type="xygrid"
id="grid3160"
empspacing="5"
visible="true"
enabled="true"
snapvisiblegridlinesonly="true" />
</sodipodi:namedview>
<metadata
id="metadata3149">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title />
</cc:Work>
</rdf:RDF>
</metadata>
<g
id="layer1"
inkscape:label="Layer 1"
inkscape:groupmode="layer">
<g
style="font-size:22.75667953px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#808080;fill-opacity:1;stroke:none;font-family:Umpush;-inkscape-font-specification:Umpush"
id="text3156" />
<path
sodipodi:type="arc"
style="fill:none;stroke:#333333;stroke-width:2.81128564999999986;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="path4025"
sodipodi:cx="-1"
sodipodi:cy="6"
sodipodi:rx="11"
sodipodi:ry="11"
d="M 10,6 A 11,11 0 1 1 -12,6 11,11 0 1 1 10,6 z"
transform="matrix(1.2727273,0,0,1.2727273,17.272727,8.363636)" />
<path
style="fill:none;stroke:#333333;stroke-width:1.91485417;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
d="m 13,10 11,0"
id="path3837"
inkscape:connector-curvature="0" />
<path
style="fill:none;stroke:#333333;stroke-width:1.91485417;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
d="m 13,13 11,0"
id="path3837-1"
inkscape:connector-curvature="0" />
<g
id="g3974">
<path
inkscape:connector-curvature="0"
id="path3837-5"
d="m 13,18 11,0"
style="fill:none;stroke:#333333;stroke-width:1.91485417;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
<path
inkscape:connector-curvature="0"
id="path3837-1-0"
d="m 13,21 11,0"
style="fill:none;stroke:#333333;stroke-width:1.91485417;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" />
</g>
<rect
style="fill:none;stroke:#333333;stroke-width:1.35426927;stroke-linecap:square;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
id="rect3970"
width="3.5617309"
height="3.6617308"
x="7.7481356"
y="17.690134" />
<path
style="fill:none;stroke:#333333;stroke-width:1.5875386;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
d="M 7.8660408,12.100275 8.999997,13.234231 11.267912,9.8323651"
id="path3980"
inkscape:connector-curvature="0" />
</g>
</svg>

After

Width:  |  Height:  |  Size: 4.2 KiB

View File

@@ -95,16 +95,11 @@ ul{list-style:disc;}
ol{list-style:decimal;}
li{line-height:18px;}
ul.unstyled,ol.unstyled{margin-left:0;list-style:none;}
dl{margin-bottom:18px; padding-top: 15px;}
dl:first-child{
margin-top: 0;
}
dl{margin-bottom:18px;}
dt,dd{line-height:18px;}
dt{font-weight:bold;line-height:17px;}
dd{margin-left: 0; padding:5px; background: #f5f5f5; border: 1px solid rgba(0, 0, 0, 0.15);}
.dl-horizontal dt{float:left;clear:left;width:120px;text-align:right;}
.dl-horizontal dd{margin-left:130px;}
dl > dt {background-color: #1D2D44; color: #fefefe; padding: 5px; border-top-left-radius: 3px; border-top-right-radius: 3px;};
hr{margin:18px 0;border:0;border-top:1px solid #eeeeee;border-bottom:1px solid #ffffff;}
strong{font-weight:bold;}
em{font-style:italic;}
@@ -1031,6 +1026,11 @@ img.lang-icon{ vertical-align: 0.05em; margin-right: 0.3em; }
#menu-about li.current-menu-item a{ color: #404040; font-weight: bold; }
img.alignleft{ margin-right: 20px; }
/**
* Above css is a copy from the main homepage
* The following rules are the changes for documentation
*/
.footer {
padding-top: 10px;
}
@@ -1039,37 +1039,144 @@ img.alignleft{ margin-right: 20px; }
margin: 0 -20px;
}
.note {
.admonition {
border: 1px solid rgba(0, 0, 0, 0.15);
border-radius: 5px;
margin: 15px 0;
padding-top: 15px;
}
.note .first {
background-color: #f5f5f5;
.admonition .first {
border-bottom: 1px solid rgba(0, 0, 0, 0.15);
font-weight: bold;
padding: 5px;
display: none;
}
.admonition .last {
background-position: 15px 0;
background-size: 32px;
background-repeat: no-repeat;
padding: 0 15px 5px 60px;
min-height: 36px;
}
.admonition .versionchanged, .admonition .versionadded {
padding-left: 60px;
}
.admonition-todo .first {
background-color: #edd400;
}
.admonition-todo .last {
background-image: url('img/todo.svg');
}
.note .first {
background-color: #f5f5f5;
}
.note .last {
padding: 5px 5px 5px 50px;
background-image: url('img/info.svg');
background-position: 5px 5px;
background-size: 30px;
background-repeat: no-repeat;
background-image: url('img/note.svg');
}
.indextable a {
color: #fefefe;
.warning .first {
color: #fefefe;
background-color: #ef2929;
}
.warning .last {
background-image: url('img/note.svg');
}
.versionchanged, .versionadded {
color: #0088CC;
}
.versionchanged, .versionadded > span {
font-weight: bold;
}
.indextable dt {
border-radius: 5px;
border-radius: 0;
background-color: #fefefe !important;
}
.section:hover > * > .headerlink {
display: inline-block;
}
.section:hover > dl > dt > .headerlink {
display: inline-block;
}
.method:hover .headerlink {
display: inline-block;
}
.headerlink {
color: #dedede;
color: #ccc;
margin-left: 5px;
}
display: none;
}
tt.file {
font-weight: bold;
}
tt.file:before {
content: "file: ";
}
.fixed_table_of_contents {
position: fixed;
top: 132px;
}
.documentation_content {
margin-left: 260px;
}
#menu-support > ul {
margin-left: 15px;
padding-left: 0;
}
#menu-support > ul ul {
margin-left: 15px;
}
h3 {
margin-top: 25px;
}
dl.class > dt, dl.function > dt, dl.method > dt {
background-color: #1D2D44;
color: #fefefe;
padding: 5px;
border-top-left-radius: 3px;
border-top-right-radius: 3px;
}
dd {
padding:5px;
}
dl.function > dd, dl.method > dd {
margin-left: 0;
background: #f5f5f5;
border: 1px solid rgba(0, 0, 0, 0.15);
}
dl.method {
margin-left: 25px;
}
dl.class > dd {
margin-left: 0;
}

View File

@@ -33,20 +33,20 @@ filling out the settings.
Settings Details
~~~~~~~~~~~~~~~~
:Host:
Host:
The hostname of the LDAP server. It can also be a ``ldaps://`` URI, for
instance.
* *Example: directory.my-company.com*
:Base DN:
Base DN:
The base DN of LDAP, from where all users and groups can be reached.
Seperated Base DNs for users and groups can be set in the Advanced
tab. Nevertheless, this field is mandatory.
* *Example: dc=my-company,dc=com*
:User DN:
User DN:
The name as DN of a user who is able to do searches in the LDAP
directory. Let it empty for anonymous access. It is recommended to have a
special system user for ownCloud.
@@ -54,22 +54,22 @@ Settings Details
* *Example: uid=owncloudsystemuser,cn=sysusers,dc=my-company,dc=com*
* formerly ``Name`` in oC 4.0
:Password:
Password:
The password for the user given above. Empty for anonymous access.
:User Login Filter:
User Login Filter:
The filter to use when a users tries to login. Use ``%uid`` as placeholder
for the username. Note, that login applies this filter only, but not User
List Filter. This may change in future.
* Example (allows login with username and email adress): ``(|(uid=%uid)(email=$uid))``
:User List Filter:
User List Filter:
The filter to use when a search for users will be executed.
* Example: ``objectClass=posixAccount``
:Group Filter:
Group Filter:
The filter to use when a search for groups will be executed. In
case you do not want to use LDAP groups in ownCloud, leave it empty.
@@ -90,44 +90,44 @@ to specifiy distinguished bases for user and group searches.
Settings Details
~~~~~~~~~~~~~~~~
:Port:
Port:
The port LDAP server Example: 389 Base User Tree: The base DN of LDAP,
from where all users can be reached. It needs to be given completely despite
to the Base DN from the Basic settings.
* Example: ``cn=users,dc=my-company,dc=com``
:Base Group Tree:
Base Group Tree:
The base DN of LDAP, from where all groups can be reached.
It needs to be given completely despite to the Base DN from the Basic
settings.
* Example: ``cn=groups,dc=my-company,dc=com``
:Group Member association:
Group Member association:
The attribute that is used to indicate group memberships, i.e. the attribute
used by LDAP groups to refer to their users.
* Example: uniquemember
:Use TLS:
Use TLS:
Wether to use TLS encrypted connection to the LDAP server.
In case you use SSL connections (via ldaps) do not check it, it will fail.
* Example: [ ]
:Case insensitive LDAP server (Windows):
Case insensitive LDAP server (Windows):
Wether theLDAP server is running on a Windows Host
* Example: [ ]
:Turn off SSL certificate validation:
Turn off SSL certificate validation:
Turns of check of valid SSL certificates. Use it if needed
for testing, only!
* Example: [ ]
:User Display Name Field:
User Display Name Field:
The attribute that should be used as ownCloud username. ownCloud allows
a limited set of characters ``(a-zA-Z0-9.-_@)``, every other character
will be replaced in ownCloud. Once a username is assigned, it will not be
@@ -137,7 +137,7 @@ Settings Details
* Example: displayName
:Group Display Name Field:
Group Display Name Field:
The attribute that should be used as ownCloud
groupname. ownCloud allows a limited set of characters (a-zA-Z0-9.-_@), every
other character will be replaced in ownCloud. Once a groupname is assigned, it
@@ -146,26 +146,26 @@ Settings Details
* Example: ``cn``
:Quota Attribute:
Quota Attribute:
ownCloud can read an LDAP attribute and set the user quota
there from. Specify the attribute here, otherwise keep it empty.
* Example: ownCloudQuota
* formerly Quota Field in oC 4.0
:Quota Default:
Quota Default:
Override ownCloud default quota for LDAP users who do not
have a quota set in the attribute given above.
* Example: 15 GB
:Email Attribute:
Email Attribute:
ownCloud can read an LDAP attribute and set the user email
there from. Specify the attribute here, otherwise keep it empty.
* Example: email
:Cache Time-To-Live:
Cache Time-To-Live:
We introduced a cache to avoid unnecessary LDAP traffic,
for example lookups check wether the users exists on every page request or
WebDAV interaction. It is also supposed to speed up the Admin → User page or
@@ -174,7 +174,7 @@ Settings Details
* Example (10 min): 600
:User Home Folder Naming Rule:
User Home Folder Naming Rule:
By default, the ownCloud creates the user
directory, where all files and meta data are kept, according to the ownCloud
username. You may want to override this setting and name it after an

Binary file not shown.

After

Width:  |  Height:  |  Size: 43 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 28 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 6.2 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.6 KiB

19
developer_manual/apps.rst Normal file
View File

@@ -0,0 +1,19 @@
Apps Development
================
Supported App Types
-------------------
ownCloud allows to specify three kind of "types" in the info.xml of a app. The
type doesn't have to be specified if the app doesn't match any of them.
Currently supported "types":
**filesystem**
apps which provides filesystem functionality (e.g. files sharing app)
**authentication**
apps which provided authentication backends
**logging**
apps which implement a logging system

View File

@@ -25,7 +25,7 @@ import sys, os
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
extensions = ['sphinxcontrib.phpdomain']
extensions = ['sphinxcontrib.phpdomain', 'sphinx.ext.todo']
# Add any paths that contain templates here, relative to this directory.
templates_path = ['../_shared_assets/templates']

View File

@@ -1,6 +1,126 @@
App config
==========
.. code-block:: php
<?php
define("DEBUG", true);
$CONFIG = array(
/* Flag to indicate ownCloud is successfully installed (true = installed) */
"installed" => false,
/* Type of database, can be sqlite, mysql or pgsql */
"dbtype" => "sqlite",
/* Name of the ownCloud database */
"dbname" => "owncloud",
/* User to access the ownCloud database */
"dbuser" => "",
/* Password to access the ownCloud database */
"dbpassword" => "",
/* Host running the ownCloud database */
"dbhost" => "",
/* Prefix for the ownCloud tables in the database */
"dbtableprefix" => "",
/* Define the salt used to hash the user passwords. All your user passwords are lost if you lose this string. */
"passwordsalt" => "",
/* Force use of HTTPS connection (true = use HTTPS) */
"forcessl" => false,
/* Enhanced auth forces users to enter their password again when performing potential sensitive actions like creating or deleting users */
"enhancedauth" => true,
/* Time in seconds how long an user is authenticated without entering his password again before performing sensitive actions like creating or deleting users etc...*/
"enhancedauthtime" => 15 * 60,
/* Theme to use for ownCloud */
"theme" => "",
/* Path to the 3rdparty directory */
"3rdpartyroot" => "",
/* URL to the 3rdparty directory, as seen by the browser */
"3rdpartyurl" => "",
/* Default app to load on login */
"defaultapp" => "files",
/* Enable the help menu item in the settings */
"knowledgebaseenabled" => true,
/* URL to use for the help page, server should understand OCS */
"knowledgebaseurl" => "http://api.apps.owncloud.com/v1",
/* Enable installing apps from the appstore */
"appstoreenabled" => true,
/* URL of the appstore to use, server should understand OCS */
"appstoreurl" => "http://api.apps.owncloud.com/v1",
/* Mode to use for sending mail, can be sendmail, smtp, qmail or php, see PHPMailer docs */
"mail_smtpmode" => "sendmail",
/* Host to use for sending mail, depends on mail_smtpmode if this is used */
"mail_smtphost" => "127.0.0.1",
/* authentication needed to send mail, depends on mail_smtpmode if this is used
* (false = disable authentication)
*/
"mail_smtpauth" => false,
/* Username to use for sendmail mail, depends on mail_smtpauth if this is used */
"mail_smtpname" => "",
/* Password to use for sendmail mail, depends on mail_smtpauth if this is used */
"mail_smtppassword" => "",
/* Check 3rdparty apps for malicious code fragments */
"appcodechecker" => "",
/* Check if ownCloud is up to date */
"updatechecker" => true,
/* Place to log to, can be owncloud and syslog (owncloud is log menu item in admin menu) */
"log_type" => "owncloud",
/* File for the owncloud logger to log to, (default is ownloud.log in the data dir */
"logfile" => "",
/* Loglevel to start logging at. 0=DEBUG, 1=INFO, 2=WARN, 3=ERROR (default is WARN) */
"loglevel" => "",
/* Lifetime of the remember login cookie, default is 15 days */
"remember_login_cookie_lifetime" => 60*60*24*15,
/* The directory where the user data is stored, default to data in the owncloud
* directory. The sqlite database is also stored here, when sqlite is used.
*/
// "datadirectory" => "",
"apps_paths" => array(
/* Set an array of path for your apps directories
key 'path' is for the fs path and the key 'url' is for the http path to your
applications paths. 'writable' indicate if the user can install apps in this folder.
You must have at least 1 app folder writable or you must set the parameter : appstoreenabled to false
*/
array(
'path'=> '/var/www/owncloud/apps',
'url' => '/apps',
'writable' => true,
),
),
);
Using alternative app directories
---------------------------------

View File

@@ -4,7 +4,7 @@ Debugging
Debug mode
----------
When debug mode is enabled ownCloud, a variety of debugging features are enabled - see debugging documentation. Add the following to the very end of /config/config.php to enable it::
When debug mode is enabled ownCloud, a variety of debugging features are enabled - see debugging documentation. Add the following to the very end of :file:`/config/config.php` to enable it::
define( "DEBUG", 1);
@@ -12,7 +12,7 @@ When debug mode is enabled ownCloud, a variety of debugging features are enabled
Identifying errors
------------------
ownCloud uses custom error PHP handling that prevents errors being printed to webserver log files or command line output. Instead, errors are generally stored in ownCloud's own log file, located at: **/data/owncloud.log**
ownCloud uses custom error PHP handling that prevents errors being printed to webserver log files or command line output. Instead, errors are generally stored in ownCloud's own log file, located at: :file:`/data/owncloud.log`
Debugging variables
@@ -50,4 +50,4 @@ By default ownCloud caches HTML generated by templates. This may prevent changes
Using alternative app directories
---------------------------------
It may be useful to have multiple app directories for testing purposes, so you can conveniently switch between different versions of applications. See the configuration file documentation for details.
It may be useful to have multiple app directories for testing purposes, so you can conveniently switch between different versions of applications. See the configuration file documentation for details.

View File

@@ -10,10 +10,10 @@ Contents
:maxdepth: 2
tutorial
debugging
configfile
templates
unittests
debugging
configfile
security

View File

@@ -1,42 +1,50 @@
Templates
=========
.. sectionauthor:: Bernhard Posselt <nukeawhale@gmail.com>
ownCloud uses its own templating system. The templating system basically works by defining main template files. Those template files then include their own templates.
.. warning::
.. versionchanged:: 5.0
.. note::
Templates must not contain database queries! All data should be passed to the template via $template->assign($key, $value).
To prevent XSS the following PHP **functions for printing are forbidden: echo, print() and <?=**. Instead use ``p($data)`` for printing your values. Should you require unescaped printing, **double check for XSS** and use: ``print_unescaped($data)``.
It's actually pretty simple. For instance take a look at this example:
**index.php**
.. warning::
Templates **must not contain database queries**! All data should be passed to the template via ``$template->assign($key, $value)``.
ownCloud uses its own templating system. Templates reside in the ``template/`` folder. To use them you'll need to instantiate the ``OC_Template`` class with the name of the template. If you want to pass values to it, use the ``assign`` method.
:file:`index.php`
.. code-block:: php
<?php
$allEntries = array('entry1', 'entry2');
$mainTemplate = new OC_Template('news', 'main.inc', 'user');
$mainTemplate = new OC_Template('news', 'main', 'user');
$mainTemplate->assign('entries', $allEntries);
$mainTemplate->assign('name', "john doe");
$mainTemplate->printPage();
?>
To access the assigned variables in the template, use the $_[] array. The variable will be availabe under the key that you defined (e.g. $_['key']).
**templates/main.inc.php**
:file:`templates/main.php`
.. code-block:: php
<?php
$allEntries = $_['entries'];
foreach($allEntries as $entry){
?>
<?php foreach($_['entries'] as $entry){ ?>
<p><?php p($entry); ?></p>
<?php
}
$this->inc('sub.inc');
print_unescaped($this->inc('sub.inc'));
?>
Templates can also include other templates by using the $this->inc('templateName') method. Use this if you find yourself repeating a lot of the same HTML constructs. The parent variables will also be available in the included templates, but should you require it, you can also pass new variables to it by using the second optional parameter for $this->inc.
**templates/sub.inc.php**
:file:`templates/sub.inc.php`
.. code-block:: php
@@ -45,11 +53,12 @@ It's actually pretty simple. For instance take a look at this example:
Template class
--------------
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])
@@ -64,7 +73,7 @@ Template class
.. code-block:: php
<?php
$mainTemplate = new OC_Template('news', 'main.inc', 'user');
$mainTemplate = new OC_Template('news', 'main', 'user');
?>
@@ -81,7 +90,7 @@ Template class
.. code-block:: php
<?php
$mainTemplate = new OC_Template('news', 'main.inc', 'user');
$mainTemplate = new OC_Template('news', 'main', 'user');
$mainTemplate->addHeader('title', array(), 'My new Page');
?>
@@ -100,7 +109,7 @@ Template class
<?php
$customers = array("john", "frank");
$mainTemplate = new OC_Template('news', 'main.inc', 'user');
$mainTemplate = new OC_Template('news', 'main', 'user');
$mainTemplate->assign('customers', $customers);
$mainTemplate->append('customers', 'hanna');
?>
@@ -122,7 +131,7 @@ Template class
<?php
$customers = array("john", "frank");
$mainTemplate = new OC_Template('news', 'main.inc', 'user');
$mainTemplate = new OC_Template('news', 'main', 'user');
$mainTemplate->assign('customers', $customers);
?>
@@ -136,7 +145,7 @@ Template class
.. code-block:: php
<?php
$mainTemplate = new OC_Template('news', 'main.inc', 'user');
$mainTemplate = new OC_Template('news', 'main', 'user');
$formFactor = $mainTemplate->detectFormfactor();
?>
@@ -149,11 +158,7 @@ Template class
**Example:**
.. code-block:: php
<?php
// FIXME: provide an example please
?>
.. todo:: provide example
.. php:method:: getFormFactorExtension()
@@ -166,7 +171,7 @@ Template class
.. code-block:: php
<?php
$mainTemplate = new OC_Template('news', 'main.inc', 'user');
$mainTemplate = new OC_Template('news', 'main', 'user');
$formFactorExtension = $mainTemplate->detectFormfactorExtension();
?>
@@ -177,7 +182,7 @@ Template class
: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 echo $this->inc('template'); ?> to do this. The included template has access to all parent template variables!
Includes another template. use <?php print_unescaped($this->inc('template')); ?> to do this. The included template has access to all parent template variables!
**Example:**
@@ -199,7 +204,7 @@ Template class
.. code-block:: php
<?php
$mainTemplate = new OC_Template('news', 'main.inc', 'user');
$mainTemplate = new OC_Template('news', 'main', 'user');
$mainTemplate->assign('test', array("test", "test2"));
$mainTemplate->printPage();
?>
@@ -211,16 +216,12 @@ Template class
:param array $parameters: Parameters for the template
:returns: bool
Shortcut to print a simple page for admin
**Example:**
.. code-block:: php
<?php
// FIXME: provide an example please
?>
Shortcut to print a simple page for admin
.. todo:: provide example
.. php:method:: printGuestPage($application, $name[, $parameters])
@@ -229,15 +230,11 @@ Template class
:param array $parameters: Parameters for the template
:returns: bool
Shortcut to print a simple page for guests
**Example:**
.. code-block:: php
<?php
// FIXME: provide an example please
?>
Shortcut to print a simple page for guests
.. todo:: provide example
.. php:method:: printUserPage($application, $name[, $parameters])
@@ -251,15 +248,17 @@ Template class
**Example:**
.. code-block:: php
<?php
// FIXME: provide an example please
?>
.. todo:: provide example
Template syntax
---------------
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
@@ -267,9 +266,12 @@ Template syntax
:param array $params: optional parameters that are done in key => value
:returns: the html as string of preset <option> tags
FIXME: explain parameters
.. 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
@@ -285,6 +287,9 @@ Turns bytes into human readable formats, for instance 1024 bytes get turned into
<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
@@ -311,6 +316,11 @@ When you pass an empty string for $app, the following directories will be search
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/
@@ -338,6 +348,8 @@ This function is used to produce generate clean and absolute links to your files
mimetype_icon
~~~~~~~~~~~~~
.. php:function:: mimetype_icon($mimetype)
:param array $mimetype: the mimetype for which we want to look up the icon
@@ -354,10 +366,14 @@ A shortcut for getting a mimetype icon.
); ?>" />
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
@@ -375,10 +391,15 @@ This is the print statement which prints out XSS escaped values. ownCloud does n
</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.
@@ -393,6 +414,8 @@ This function does not escape the content for XSS. This would typically be used
relative_modified_date
~~~~~~~~~~~~~~~~~~~~~~
.. php:function:: relative_modified_date($timestamp)
:param int $timestamp: the timestamp from whom we compute the time span until now
@@ -408,6 +431,9 @@ Instead of displaying a date, it is often better to give a relative date like: "
<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
@@ -422,6 +448,8 @@ A more simpler function that only turns bytes into megabytes. If its smaller tha
?>
<li><?php p(simple_file_size('2048')); ?></li>
Further reading
---------------
- http://en.wikipedia.org/wiki/Cross-site_scripting

View File

@@ -1,5 +1,5 @@
How To Do Unittests In Owncloud
===============================
Unittests
=========
Getting PHPUnit
---------------
@@ -30,7 +30,7 @@ Then you can simply run the created test with phpunit.
An example for a simple test would be:
**/srv/http/owncloud/apps/myapp/tests/testsuite.php**
:file:`/srv/http/owncloud/apps/myapp/tests/testsuite.php`
.. code-block:: php
@@ -46,7 +46,7 @@ An example for a simple test would be:
}
?>
**/srv/http/owncloud/apps/myapp/tests/testsuite.php**
:file:`/srv/http/owncloud/apps/myapp/tests/testsuite.php`
.. code-block:: php
@@ -56,7 +56,7 @@ An example for a simple test would be:
}
?>
In **/srv/http/owncloud/apps/myapp/** you run the test with::
In :file:`/srv/http/owncloud/apps/myapp/` you run the test with::
phpunit tests/testsuite.php
@@ -69,18 +69,18 @@ If you use Owncloud functions or classes in your code, you'll need to make them
To do this, you'll need to provide the ``--bootstrap`` argument when running PHPUnit
**/srv/http/owncloud**::
:file:`/srv/http/owncloud`::
phpunit --bootstrap tests/bootstrap.php apps/myapp/tests/testsuite.php
If you run the test under a different user than your webserver, you'll have to
adjust your php.ini and file rights.
**/etc/php/php.ini**::
:file:`/etc/php/php.ini`::
open_basedir = none
**/srv/http/owncloud**::
:file:`/srv/http/owncloud`::
su -c "chmod a+r config/config.php"
su -c "chmod a+rx data/"