khanh.pndc/nextcloud-docs
1
0
Fork 0
mirror of https://github.com/nextcloud/documentation.git synced 2026-01-03 18:26:42 +07:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into rakekniven-patch-1

Browse Source
This commit is contained in:
rakekniven
2021-10-04 16:26:44 +02:00
parent d8e15157cb c29f30cb13
commit b0c8a7fd2d
634 changed files with 42946 additions and 6968 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
developer_manual/basics/backgroundjobs.rst
View File

@@ -56,7 +56,7 @@ As you can see our dependency injection also works just fine for background jobs
The ITimeFactory always needs to be passed to the parent constructor. Since it is
required to be set.
In this case it is a background job that runs every hour. And we take the ``uid`` arguemnt
In this case it is a background job that runs every hour. And we take the ``uid`` argument
to pass on to the service to run the background job.
The ``run`` function is the main thing you need to implement and where all the

6
developer_manual/basics/controllers.rst
View File

@@ -465,7 +465,7 @@ Public page templates
^^^^^^^^^^^^^^^^^^^^^
For public pages, that are rendered to users who are not logged in to the
Nextcloud instance, a :any:`PublicTemplateResponse <OCP\\AppFramework\\Http\\Template\\PublicTemplateResponse>` should be used, to load the
Nextcloud instance, a ``OCP\\AppFramework\\Http\\Template\\PublicTemplateResponse`` should be used, to load the
correct base template. It also allows adding an optional set of actions that
will be shown in the top right corner of the public page.
@@ -498,9 +498,9 @@ The header title and subtitle will be rendered in the header, next to the logo.
The action with the highest priority (lowest number) will be used as the
primary action, others will shown in the popover menu on demand.
A :any:`SimpleMenuAction <OCP\\AppFramework\\Http\\Template\\SimpleMenuAction>` will be a link with an icon added to the menu. App
A ``OCP\\AppFramework\\Http\\Template\\SimpleMenuAction`` will be a link with an icon added to the menu. App
developers can implement their own types of menu renderings by adding a custom
class implementing the :any:`IMenuAction <OCP\\AppFramework\\Http\\Template\\IMenuAction>` interface.
class implementing the ``OCP\\AppFramework\\Http\\Template\\IMenuAction`` interface.

18
developer_manual/basics/events.rst
View File

@@ -1,3 +1,5 @@
.. _Events:
======
Events
======
@@ -528,14 +530,14 @@ WARNING: Using this API incorrectly may make the instance more insecure. Do thin
*Available in Nextcloud 18 and later.*
``\OCP\Security\FeaturePolicy\AddFeaturePolicyEvent``
****************************************************
*****************************************************
*Available in Nextcloud 17 and later.*
Event that allows to register a feature policy header to a request.
``\OCP\Share\Events\ShareCreatedEvent``
*******************************************
***************************************
*Available in Nextcloud 18 and later.*
@@ -641,24 +643,24 @@ Emitted before a user is logged out.
Emitted when a user has been logged out successfully.
``\OCP\WorkflowEngine\LoadSettingsScriptsEvent``
***************************************
************************************************
*Available in Nextcloud 20 and later.*
Emitted when the workflow engine settings page is loaded.
``\OCP\WorkflowEngine\RegisterChecksEvent``
***************************************
*******************************************
*Available in Nextcloud 18 and later.*
``\OCP\WorkflowEngine\RegisterEntitiesEvent``
***************************************
*********************************************
*Available in Nextcloud 18 and later.*
``\OCP\WorkflowEngine\RegisterOperationsEvent``
***************************************
***********************************************
*Available in Nextcloud 18 and later.*
@@ -774,7 +776,7 @@ The following hooks are available:
Session
```````
Injectable from the ServerContainer by calling the method **getUserSession()**.
Injectable from the ServerContainer by calling the method **getUserSession()**.
Hooks available in scope **\\OC\\User**:
@@ -825,7 +827,7 @@ Injectable from the ServerContainer by calling the method **getRootFolder()**, *
To enable these events for your app you should add the following to your `info.xml` file:
.. code-block:: xml
<types>
<filesystem/>
</types>

15
developer_manual/basics/front-end/js.rst
View File

@@ -109,7 +109,7 @@ and a JS part (that fetches and parses the state).
Providing the initial state with PHP
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Providing state in PHP is done via the ``\OCP\IInitialStateService``. This service
Providing state in PHP is done via the ``OCP\AppFramework\Services\IInitialState``. This service
has two methods you can use to provide the initial state.
* ``provideInitialState(string $appName, string $key, $data)``:
@@ -130,6 +130,19 @@ Obtaining the initial state in JavaScript
To obtain the initial state in your JavaScript you have to only call one
function
- Vue way with `@nextcloud/initial-state <https://github.com/nextcloud/nextcloud-initial-state>`_:
.. code-block:: js
import { loadState } from '@nextcloud/initial-state'
const val = loadState('myapp', 'user_preference')
// Provide a fallback value to return when the state is not found
const valWithFallback = loadState('myapp', 'user_preference', 'no_preference')
- Legacy way:
.. code-block:: js
const state = OCP.InitialState.loadState('MyApp', 'MyState');

2
developer_manual/basics/front-end/l10n.rst
View File

@@ -119,7 +119,7 @@ There are global functions **t()** and **n()** available for translating strings
.. code-block:: js
t('myapp', 'Hello World!');
t('myapp', '{name} is available. Get {linkstart}more information{linkend}}', {name: 'Nextcloud 16', linkstart: '<a href="...">', linkend: '</a>'});
t('myapp', '{name} is available. Get {linkstart}more information{linkend}', {name: 'Nextcloud 16', linkstart: '<a href="...">', linkend: '</a>'});
n('myapp', 'Import %n calendar into {collection}', 'Import %n calendars into {collection}', selectionLength, {collection: 'Nextcloud'});

3
developer_manual/basics/index.rst
View File

@@ -14,4 +14,5 @@ Basic concepts
front-end/index
backgroundjobs
logging
storage/index
storage/index
testing

10
developer_manual/basics/request_lifecycle.rst
View File

@@ -2,12 +2,6 @@
Request lifecycle
=================
.. toctree::
:maxdepth: 1
container
api
.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>, Morris Jobke <hey@morrisjobke.de>
A typical HTTP request consists of the following:
@@ -28,11 +22,11 @@ In the beginning, all requests are sent to Nextcloud's :file:`index.php` which i
* Filesystem
* Logging
The type of the app is determined by inspecting the app's :doc:`configuration file <../info>` (:file:`appinfo/info.xml`). Loading apps means that the :doc:`main file <../init>` (:file:`appinfo/app.php`) of each installed app is being loaded and executed. That means that if you want to execute code before a specific app is being run, you can place code in your app's :doc:`../init` file.
The type of the app is determined by inspecting the app's :doc:`configuration file <../info>` (:file:`appinfo/info.xml`). Loading apps means that the :doc:`main file <../app_development/init>` (:file:`appinfo/app.php`) of each installed app is being loaded and executed. That means that if you want to execute code before a specific app is being run, you can place code in your app's :doc:`../app_development/init` file.
Afterwards the following steps are performed:
* Try to authenticate the user
* Load and execute all the remaining apps' :doc:`../init` files
* Load and execute all the remaining apps' :doc:`../app_development/init` files
* Load and run all the routes in the apps' :file:`appinfo/routes.php`
* Execute the router

27
developer_manual/basics/storage/database.rst
View File

@@ -45,6 +45,33 @@ Inside your database layer class you can now start running queries like:
}
Transactions
------------
Database operations can be run in a transaction to commit or roll back a group of changes in an atomic fashion.
.. code-block:: php
<?php
$this->db->startTransaction();
try {
// DB operations
$this->db->commit();
} catch (\Throwable $e) {
// Optional: handle the error
// Important: roll back (or commit) your changes when an error
// happens, so this transaction ends
$this->db->rollBack();
throw $e;
}
.. warning:: Omitting the error handling for transactions will lead to unexpected behavior as any database operations that come after your error will still run in your transaction and due to the lack of a commit PDO will automatically roll-back all changes at the end of the script.
Mappers
-------

4
developer_manual/basics/storage/filesystem.rst
View File

@@ -20,7 +20,7 @@ All methods return a Folder object on which files and folders can be accessed, o
<?php
namespace OCA\MyApp\Storage;
use OCP\Files\IRootFolder
use OCP\Files\IRootFolder;
class AuthorStorage {
@@ -64,7 +64,7 @@ Files and folders can also be accessed by id, by calling the **getById** method
<?php
namespace OCA\MyApp\Storage;
use OCP\Files\IRootFolder
use OCP\Files\IRootFolder;
class AuthorStorage {

1
developer_manual/basics/storage/index.rst
View File

@@ -6,7 +6,6 @@ Storage and database
:maxdepth: 2
migrations
schema
database
configuration
filesystem

28
developer_manual/basics/storage/migrations.rst
View File

@@ -70,14 +70,14 @@ With this step the new column gets created:
.. code-block:: php
public function changeSchema(IOutput $output, \Closure $schemaClosure, array $options) {
/** @var Schema $schema */
/** @var ISchemaWrapper $schema */
$schema = $schemaClosure();
$table = $schema->getTable('twofactor_backupcodes');
$table->addColumn('user_id', Type::STRING, [
$table->addColumn('user_id', \OCP\DB\Types::STRING, [
'notnull' => true,
'length' => 64,
'length' => 64,
]);
return $schema;
@@ -109,7 +109,7 @@ With this the old column gets removed.
.. code-block:: php
public function changeSchema(IOutput $output, \Closure $schemaClosure, array $options) {
/** @var Schema $schema */
/** @var ISchemaWrapper $schema */
$schema = $schemaClosure();
$table = $schema->getTable('twofactor_backupcodes');
@@ -118,30 +118,13 @@ With this the old column gets removed.
return $schema;
}
Migrate from database.xml
-------------------------
To migrate your app from a `database.xml` file to migrations run:
.. code-block:: bash
php ./occ migrations:generate-from-schema <app_id> <version>
This will create a new file under `lib/Migration` that results in the
same database table(s) as your database.xml file.
For version you should use your app versions. So if you app is at version
1.2.3 use 010203.
Don't forget to remove your `database.xml` file.
.. _migration_console_command:
Console commands
----------------
There are some console commands, which should help developers to create or deal
with migrations, which are sometimes only available if you are running your
with migrations, which are only available if you are running your
Nextcloud in debug mode:
* `migrations:execute`: Executes a single migration version manually.
@@ -154,6 +137,5 @@ Nextcloud in debug mode:
in another branch. Since you can’t change this retroactive, we recommend to
leave enough space in between and therefore map the numbers to 3 digits:
`1.0.x => 1000`, `2.34.x => 2034`, etc.
* `migrations:generate-from-schema`: Create a migration from the old `database.xml`.
* `migrations:migrate`: Execute a migration to a specified or the latest available version.
* `migrations:status`: View the status of a set of migrations.

56
developer_manual/basics/storage/schema.rst
View File

@@ -1,56 +0,0 @@
============================
Database schema (deprecated)
============================
.. warning:: Using the database.xml schema file is deprecated.
You should migrate to using :ref:`Database Migrations <app_db_migrations>`.
.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>
Nextcloud uses a database abstraction layer on top of either PDO, depending on the availability of PDO on the server.
The database schema is inside :file:`appinfo/database.xml` in MDB2's `XML scheme notation <http://www.wiltonhotel.com/_ext/pear/docs/MDB2/docs/xml_schema_documentation.html>`_ where the placeholders \*dbprefix* (\*PREFIX* in your SQL) and \*dbname* can be used for the configured database table prefix and database name.
An example database XML file would look like this:
.. code-block:: xml
<?xml version="1.0" encoding="UTF-8" ?>
<database>
<name>*dbname*</name>
<create>true</create>
<overwrite>false</overwrite>
<charset>utf8</charset>
<table>
<name>*dbprefix*yourapp_items</name>
<declaration>
<field>
<name>id</name>
<type>integer</type>
<default>0</default>
<notnull>true</notnull>
<autoincrement>1</autoincrement>
<length>4</length>
</field>
<field>
<name>user</name>
<type>text</type>
<notnull>true</notnull>
<length>64</length>
</field>
<field>
<name>name</name>
<type>text</type>
<notnull>true</notnull>
<length>100</length>
</field>
<field>
<name>path</name>
<type>clob</type>
<notnull>true</notnull>
</field>
</declaration>
</table>
</database>
To update the tables used by the app, simply adjust the database.xml file and increase the app version number in :file:`appinfo/info.xml` to trigger an update.