diff --git a/developer_manual/android_library/examples.rst b/developer_manual/android_library/examples.rst index c1f4a477b..d9be7cbc6 100644 --- a/developer_manual/android_library/examples.rst +++ b/developer_manual/android_library/examples.rst @@ -80,14 +80,14 @@ Code example private void startFolderCreation(String newFolderPath) { CreateRemoteFolderOperation createOperation = new CreateRemoteFolderOperation(newFolderPath, false); - createOperation.execute( mClient , this , mHandler); + createOperation.execute(mClient, this, mHandler); } @Override public void onRemoteOperationFinish(RemoteOperation operation, RemoteOperationResult result) { if (operation instanceof CreateRemoteFolderOperation) { if (result.isSuccess()) { - // do your stuff here + // do your stuff here } } … @@ -107,7 +107,7 @@ Code example .. code-block:: java private void startReadRootFolder() { - ReadRemoteFolderOperation refreshOperation = new ReadRemoteFolderOperation(FileUtils.PATH_SEPARATOR);  + ReadRemoteFolderOperation refreshOperation = new ReadRemoteFolderOperation(FileUtils.PATH_SEPARATOR); // root folder refreshOperation.execute(mClient, this, mHandler); } @@ -164,7 +164,7 @@ Code example private void startRemoveFile(String filePath) { RemoveRemoteFileOperation removeOperation = new RemoveRemoteFileOperation(remotePath); - removeOperation.execute( mClient , this , mHandler); + removeOperation.execute(mClient, this, mHandler); } @Override @@ -197,7 +197,7 @@ Code example } @Override - public void onRemoteOperationFinish( RemoteOperation operation, RemoteOperationResult result) { + public void onRemoteOperationFinish(RemoteOperation operation, RemoteOperationResult result) { if (operation instanceof DownloadRemoteFileOperation) { if (result.isSuccess()) { // do your stuff here @@ -206,7 +206,7 @@ Code example } @Override - public void onTransferProgress( long progressRate, long totalTransferredSoFar, long totalToTransfer, String fileName) { + public void onTransferProgress(long progressRate, long totalTransferredSoFar, long totalToTransfer, String fileName) { mHandler.post( new Runnable() { @Override public void run() { @@ -227,8 +227,8 @@ Code example .. code-block:: java - private void startUpload (File fileToUpload, String remotePath, String mimeType) { - UploadRemoteFileOperation uploadOperation = new UploadRemoteFileOperation( fileToUpload.getAbsolutePath(), remotePath, mimeType); + private void startUpload(File fileToUpload, String remotePath, String mimeType) { + UploadRemoteFileOperation uploadOperation = new UploadRemoteFileOperation(fileToUpload.getAbsolutePath(), remotePath, mimeType); uploadOperation.addDatatransferProgressListener(this); uploadOperation.execute(mClient, this, mHandler); } @@ -244,7 +244,7 @@ Code example @Override public void onTransferProgress(long progressRate, long totalTransferredSoFar, long totalToTransfer, String fileName) { - mHandler.post( new Runnable() { + mHandler.post(new Runnable() { @Override public void run() { // do your UI updates about progress here @@ -269,14 +269,14 @@ Code example private void startFileMove(String filePath, String newFilePath, boolean overwrite) { MoveRemoteFileOperation moveOperation = new MoveRemoteFileOperation(filePath, newFilePath, overwrite); - moveOperation.execute( mClient , this , mHandler); + moveOperation.execute(mClient, this, mHandler); } @Override public void onRemoteOperationFinish(RemoteOperation operation, RemoteOperationResult result) { if (operation instanceof MoveRemoteFileOperation) { if (result.isSuccess()) { - // do your stuff here + // do your stuff here } } … @@ -286,7 +286,7 @@ Read shared items by link ------------------------- Get information about what files and folder are shared by link (the object -mClient contains the information about the server url and account) +mClient contains the information about the server URL and account). Code example ~~~~~~~~~~~~ @@ -295,16 +295,16 @@ Code example private void startAllSharesRetrieval() { GetRemoteSharesOperation getSharesOp = new GetRemoteSharesOperation(); - getSharesOp.execute( mClient , this , mHandler); + getSharesOp.execute(mClient, this, mHandler); } @Override - public void onRemoteOperationFinish( RemoteOperation operation, RemoteOperationResult result) { + public void onRemoteOperationFinish(RemoteOperation operation, RemoteOperationResult result) { if (operation instanceof GetRemoteSharesOperation) { if (result.isSuccess()) { ArrayList< OCShare > shares = new ArrayList< OCShare >(); for (Object obj: result.getData()) { - shares.add(( OCShare) obj); + shares.add((OCShare) obj); } // do your stuff here } @@ -327,21 +327,21 @@ Code example private void startSharesRetrievalForFileOrFolder(String filePath, boolean getReshares) { GeteRemoteSharesForFileOperation operation = new GetRemoteSharesForFileOperation(filePath, getReshares, false); - operation.execute( mClient, this, mHandler); + operation.execute(mClient, this, mHandler); } private void startSharesRetrievalForFilesInFolder(String folderPath, boolean getReshares) { GetRemoteSharesForFileOperation operation = new GetRemoteSharesForFileOperation(folderPath, getReshares, true); - operation.execute( mClient, this, mHandler); + operation.execute(mClient, this, mHandler); } @Override - public void onRemoteOperationFinish( RemoteOperation operation, RemoteOperationResult result) { + public void onRemoteOperationFinish(RemoteOperation operation, RemoteOperationResult result) { if (operation instanceof GetRemoteSharesForFileOperation) { if (result.isSuccess()) { ArrayList< OCShare > shares = new ArrayList< OCShare >(); for (Object obj: result.getData()) { - shares.add(( OCShare) obj); + shares.add((OCShare) obj); } // do your stuff here } @@ -367,7 +367,7 @@ Code example private void startCreationOfPublicShareForFile(String filePath, String password) { CreateRemoteShareOperation operation = new CreateRemoteShareOperation(filePath, ShareType.PUBLIC_LINK, "", false, password, 1); - operation.execute( mClient , this , mHandler); + operation.execute(mClient, this, mHandler); } private void startCreationOfGroupShareForFile(String filePath, String groupId) { @@ -381,10 +381,10 @@ Code example } @Override - public void onRemoteOperationFinish( RemoteOperation operation, RemoteOperationResult result) { + public void onRemoteOperationFinish(RemoteOperation operation, RemoteOperationResult result) { if (operation instanceof CreateRemoteShareOperation) { if (result.isSuccess()) { - OCShare share = (OCShare) result.getData ().get(0); + OCShare share = (OCShare) result.getData().get(0); // do your stuff here } } @@ -405,14 +405,14 @@ Code example private void startShareRemoval(OCShare share) { RemoveRemoteShareOperation operation = new RemoveRemoteShareOperation((int) share.getIdRemoteShared()); - operation.execute( mClient, this, mHandler); + operation.execute(mClient, this, mHandler); } @Override - public void onRemoteOperationFinish( RemoteOperation operation, RemoteOperationResult result) { + public void onRemoteOperationFinish(RemoteOperation operation, RemoteOperationResult result) { if (operation instanceof RemoveRemoteShareOperation) { if (result.isSuccess()) { - // do your stuff here + // do your stuff here } } } @@ -425,6 +425,6 @@ Tips * Paths must not be on URL Encoding * Correct path: ``https://example.com/nextcloud/remote.php/dav/PopMusic`` * Wrong path: ``https://example.com/nextcloud/remote.php/dav/Pop%20Music/`` -* There are some forbidden characters to be used in folder and files names on the server, same on the Nextcloud Android Library "\","/","<",">",":",""","|","?","*" +* There are some forbidden characters to be used in folder and file names on the server, same on the Nextcloud Android Library "\","/","<",">",":",""","|","?","*" * Upload and download actions may be cancelled thanks to the objects uploadOperation.cancel(), downloadOperation.cancel() -* Unit tests, before launching unit tests you have to enter your account information (server url, user and password) on TestActivity.java +* Unit tests, before launching unit tests you have to enter your account information (server URL, user and password) on TestActivity.java diff --git a/developer_manual/android_library/index.rst b/developer_manual/android_library/index.rst index dc96e4250..474ef61ee 100644 --- a/developer_manual/android_library/index.rst +++ b/developer_manual/android_library/index.rst @@ -13,13 +13,13 @@ library under the MIT license. Android Nextcloud Client development ------------------------------------ -If you are interested in working on the Nextcloud android client, you can find -the source code `in github `_. The +If you are interested in working on the Nextcloud Android client, you can find +the source code `in GitHub `_. The setup and process of contribution is `documented here `_. -You might want to start with doing one or two `starter issue `_ -to get into the code and note our :doc:`../general/index` +You might want to start with doing one or two `starter issues `_ +to get into the code and note our :doc:`../general/index`. Nextcloud Android Library ------------------------- @@ -27,12 +27,12 @@ Nextcloud Android Library This document will describe how to the use Nextcloud Android Library. The Nextcloud Android Library allows a developer to communicate with any Nextcloud server; among the features included are file synchronization, upload and -download of files, delete rename files and folders, etc. +download of files, delete or rename files and folders, etc. This library may be added to a project and seamlessly integrates any application with Nextcloud. -The tool needed is any IDE for Android preferred IDE at the moment is Android Studio. +The tool needed is any IDE for Android; the preferred IDE at the moment is Android Studio. .. toctree:: :maxdepth: 2 diff --git a/developer_manual/android_library/library_installation.rst b/developer_manual/android_library/library_installation.rst index 76d5fd252..716e9b0d8 100644 --- a/developer_manual/android_library/library_installation.rst +++ b/developer_manual/android_library/library_installation.rst @@ -5,11 +5,11 @@ Obtaining the library --------------------- -The Nextcloud Android library may be obtained from the following Github repository: +The Nextcloud Android library may be obtained from the following GitHub repository: `https://github.com/nextcloud/android-library `_ -Once obtained, this code should be compiled. The Github repository not only contains the library, but also a sample project, sample_client +Once obtained, this code should be compiled. The GitHub repository not only contains the library, but also a sample project, sample_client sample_client properties/android/librerias , which will assist in learning how to use the library. @@ -19,14 +19,14 @@ Add the library to a project There are different methods to add an external library to a project, we will describe two. -#. Add the library as a gradle dependency via jitpack +#. Add the library as a Gradle dependency via JitPack -#. Add the library repo to your Android project as a git submodule +#. Add the library repo to your Android project as a Git submodule -Add the library as a gradle dependency +Add the library as a Gradle dependency ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Simply open your:: @@ -37,15 +37,16 @@ and add the dependency:: compile 'com.github.nextcloud:android-library:' - refers to the exact version you would like to include in your application. This could be -SNAPSHOT for always using the latest code revision of the master branch. Alternatively you can also specifiy a version number which refers to a fixed release, e.g. 1.0.0. (compile 'com.github.nextcloud:android-library:1.0.0') + refers to the exact version you would like to include in your application. This could be -SNAPSHOT for always using the latest code revision of the master branch. Alternatively you can also specifiy a version number which refers to a fixed release, e.g. 1.0.0. (compile 'com.github.nextcloud:android-library:1.0.0'). -Add the library project to your project as a git submodule +Add the library project to your project as a Git submodule ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Basically get the code and compile it having it integrated via a git submodule +Basically get the code and compile it having it integrated via a Git submodule. Go into your own apps directory on the command line and add the Nextcloud Android library as a submodule:: + git submodule add https://github.com/nextcloud/android-library nextcloud-android-library Import/Open your app in Android Studio and you are done. All the public classes and methods of the library will be available for your own app. diff --git a/developer_manual/app/backgroundjobs.rst b/developer_manual/app/backgroundjobs.rst index 032a24296..125a8ccd0 100644 --- a/developer_manual/app/backgroundjobs.rst +++ b/developer_manual/app/backgroundjobs.rst @@ -11,7 +11,7 @@ Background/cron jobs are usually registered in the :file:`appinfo/app.php` by us query('AuthorService') ); -* The **AppName** is queried and returned from the baseclass +* The **AppName** is queried and returned from the base class * The **Request** is queried and returned from the server container * **AuthorService** is queried:: diff --git a/developer_manual/app/controllers.rst b/developer_manual/app/controllers.rst index 68eac0303..b376edb72 100644 --- a/developer_manual/app/controllers.rst +++ b/developer_manual/app/controllers.rst @@ -319,7 +319,7 @@ Cookies can be set or modified directly on the response class: Responses ========= -Similar to how every controller receives a request object, every controller method has to to return a Response. This can be in the form of a Response subclass or in the form of a value that can be handled by a registered responder. +Similar to how every controller receives a request object, every controller method has to return a Response. This can be in the form of a Response subclass or in the form of a value that can be handled by a registered responder. JSON ---- @@ -342,7 +342,7 @@ Returning JSON is simple, just pass an array to a JSONResponse: } -Because returning JSON is such an common task, there's even a shorter way to do this: +Because returning JSON is such a common task, there's even a shorter way to do this: .. code-block:: php @@ -525,7 +525,7 @@ A file download can be triggered by returning a DownloadResponse: Creating custom responses ------------------------- -If no premade Response fits the needed usecase, its possible to extend the Response baseclass and custom Response. The only thing that needs to be implemented is the **render** method which returns the result as string. +If no premade Response fits the needed usecase, it is possible to extend the Response base class and custom Response. The only thing that needs to be implemented is the **render** method which returns the result as string. Creating a custom XMLResponse class could look like this: @@ -600,7 +600,7 @@ If you want to use a custom, lazily rendered response simply implement the inter Modifying the Content Security Policy ------------------------------------- -By default Nextcloud disables all resources which are not served on the same domain, forbids cross domain requests and disables inline CSS and JavaScript by setting a `Content Security Policy `_. However if an app relies on thirdparty media or other features which are forbidden by the current policy the policy can be relaxed. +By default Nextcloud disables all resources which are not served on the same domain, forbids cross domain requests and disables inline CSS and JavaScript by setting a `Content Security Policy `_. However if an app relies on third-party media or other features which are forbidden by the current policy the policy can be relaxed. .. note:: Double check your content and edge cases before you relax the policy! Also read the `documentation provided by MDN `_ @@ -653,7 +653,7 @@ OCS --- .. note:: This is purely for compatibility reasons. If you are planning to offer an external API, go for a :doc:`api` instead. -In order to ease migration from OCS API routes to the App Framework, an additional controller and response have been added. To migrate your API you can use the **OCP\\AppFramework\\OCSController** baseclass and return your data in the form of a DataResponse in the following way: +In order to ease migration from OCS API routes to the App Framework, an additional controller and response have been added. To migrate your API you can use the **OCP\\AppFramework\\OCSController** base class and return your data in the form of a DataResponse in the following way: .. code-block:: php @@ -742,7 +742,7 @@ Most of the time though it makes sense to also allow normal users to access the To turn off checks the following *Annotations* can be added before the controller: * **@NoAdminRequired**: Also users that are not admins can access the page -* **@NoCSRFRequired**: Don't check the CSRF token (use this wisely since you might create a security hole, to understand what it does see :doc:`../general/security`) +* **@NoCSRFRequired**: Don't check the CSRF token (use this wisely since you might create a security hole; to understand what it does see :doc:`../general/security`) * **@PublicPage**: Everyone can access the page without having to log in A controller method that turns off all checks would look like this: diff --git a/developer_manual/app/css.rst b/developer_manual/app/css.rst index ceef04adc..444a5321a 100644 --- a/developer_manual/app/css.rst +++ b/developer_manual/app/css.rst @@ -15,7 +15,7 @@ The CSS files reside in the **css/** folder and should be included in the templa // include multiple files for the same app style('myapp', array('style', 'navigation')); // adds css/style.css, css/navigation.css - // include vendor file (also allows vendor syntax) + // include vendor file (also allows array syntax) vendor_style('myapp', 'style'); // adds vendor/style.css Web Components go into the **component/** folder and can be imported like this: @@ -30,7 +30,7 @@ Web Components go into the **component/** folder and can be imported like this: component('myapp', array('tabs', 'forms')); // adds component/tabs.html, component/forms.html -.. note:: Keep in mind that Web Components are still very new and you `might need to add polyfills using Polymer `_ +.. note:: Keep in mind that Web Components are still very new and you `might need to add polyfills `_ Standard layout =============== @@ -71,7 +71,7 @@ Nextcloud provides a default CSS navigation layout. If list entries should have Folders ------- -Folders are like normal entries and are only supported for the first level. In contrast to normal entries, the links which show the title of the folder need to have the **icon-folder** css class. +Folders are like normal entries and are only supported for the first level. In contrast to normal entries, the links which show the title of the folder need to have the **icon-folder** CSS class. If the folder should be collapsible, the **collapsible** class and a button with the class **collapse** are needed. After adding the collapsible class the folder's child entries can be toggled by adding the **open** class to the list element: @@ -116,7 +116,7 @@ Menus .. versionadded:: 8 -To add actions that affect the current list element you can add a menu for second and/or first level elements by adding the button and menu inside the corresponding **li** element and adding the **with-menu** css class: +To add actions that affect the current list element you can add a menu for second and/or first level elements by adding the button and menu inside the corresponding **li** element and adding the **with-menu** CSS class: .. code-block:: html @@ -153,7 +153,7 @@ To add actions that affect the current list element you can add a menu for secon -The div with the class **app-navigation-entry-utils** contains only the button (class: **app-navigation-entry-utils-menu-button**) to display the menu but in many cases another entry is needed to display some sort of count (mails count, unread feed count, etc.). In that case add the **with-counter** class to the list entry to adjust the correct padding and text-oveflow of the entry's title. +The div with the class **app-navigation-entry-utils** contains only the button (class: **app-navigation-entry-utils-menu-button**) to display the menu but in many cases another entry is needed to display some sort of count (mails count, unread feed count, etc.). In that case add the **with-counter** class to the list entry to adjust the correct padding and text-overflow of the entry's title. The count should be limitted to 999 and turn to 999+ if any higher number is given. If AngularJS is used the following filter can be used to get the correct behaviour: @@ -274,7 +274,7 @@ If you want to undo a performed action on a navigation entry such as deletion, y Settings Area ============= -To create a settings area create a div with the id **app-settings** inside the **app-navgiation** div: +To create a settings area create a div with the id **app-settings** inside the **app-navigation** div: .. code-block:: html diff --git a/developer_manual/app/database.rst b/developer_manual/app/database.rst index 5be71c522..5875e4dba 100644 --- a/developer_manual/app/database.rst +++ b/developer_manual/app/database.rst @@ -48,7 +48,7 @@ The aforementioned example is the most basic way to write a simple database quer To generalize and simplify the problem, split code into resources and create an **Entity** and a **Mapper** class for it. The mapper class provides a way to run SQL queries and maps the result onto the related entities. -To create a mapper, inherit from the mapper baseclass and call the parent constructor with the following parameters: +To create a mapper, inherit from the mapper base class and call the parent constructor with the following parameters: * Database connection * Table name @@ -100,7 +100,7 @@ To create a mapper, inherit from the mapper baseclass and call the parent constr } -.. note:: The cursor is closed automatically for all **INSERT**, **DELETE**, **UPDATE** queries and when calling the methods **findOneQuery**, **findEntities**, **findEntity**, **delete**, **insert** and **update**. For custom calls using execute you should always close the cursor after you are done with the fetching to prevent database lock problems on SqLite +.. note:: The cursor is closed automatically for all **INSERT**, **DELETE**, **UPDATE** queries and when calling the methods **findOneQuery**, **findEntities**, **findEntity**, **delete**, **insert** and **update**. For custom calls using execute you should always close the cursor after you are done with the fetching to prevent database lock problems on SQLite Every mapper also implements default methods for deleting and updating an entity based on its id:: @@ -114,7 +114,7 @@ or:: Entities ======== -Entities are data objects that carry all the table's information for one row. Every Entity has an **id** field by default that is set to the integer type. Table rows are mapped from lower case and underscore separated names to pascal case attributes: +Entities are data objects that carry all the table's information for one row. Every Entity has an **id** field by default that is set to the integer type. Table rows are mapped from lower case and underscore separated names to *lowerCamelCase* attributes: * **Table column name**: phone_number * **Property name**: phoneNumber @@ -141,7 +141,7 @@ Entities are data objects that carry all the table's information for one row. Ev Types ----- -The following properties should be annotated by types, to not only assure that the types are converted correctly for storing them in the database (e.g. PHP casts false to the empty string which fails on postgres) but also for casting them when they are retrieved from the database. +The following properties should be annotated by types, to not only assure that the types are converted correctly for storing them in the database (e.g. PHP casts false to the empty string which fails on PostgreSQL) but also for casting them when they are retrieved from the database. The following types can be added for a field: @@ -204,7 +204,7 @@ mapping, simply override the **columnToProperty** and **propertyToColumn** metho } public function propertyToColumn($property) { - if ($column === 'phoneNumber') { + if ($property === 'phoneNumber') { return 'phonenumber'; } else { return parent::propertyToColumn($property); @@ -216,7 +216,7 @@ mapping, simply override the **columnToProperty** and **propertyToColumn** metho Slugs ----- -Slugs are used to identify resources in the URL by a string rather than integer id. Since the URL allows only certain values, the entity baseclass provides a slugify method for it: +Slugs are used to identify resources in the URL by a string rather than integer id. Since the URL allows only certain values, the entity base class provides a slugify method for it: .. code-block:: php diff --git a/developer_manual/app/hooks.rst b/developer_manual/app/hooks.rst index b33d6b423..5369d2e1f 100644 --- a/developer_manual/app/hooks.rst +++ b/developer_manual/app/hooks.rst @@ -14,7 +14,7 @@ Hooks are used to execute code before or after an event has occurred. This is fo $app = new Application(); $app->getContainer()->query('UserHooks')->register(); -The hook logic should be in a separate class that is being registered in the :doc:`container` +The hook logic should be in a separate class that is being registered in the :doc:`container`: .. code-block:: php diff --git a/developer_manual/app/info.rst b/developer_manual/app/info.rst index 88946275c..9857a269f 100644 --- a/developer_manual/app/info.rst +++ b/developer_manual/app/info.rst @@ -175,7 +175,7 @@ specified. Valid values for the 'os' attribute are as returned by the PHP functi lib === Defines a required PHP extension with required minimum and/or maximum version. The names for the libraries have to match the result as returned by the PHP function `get_loaded_extensions `_. -The explicit version of an extension is read from `phpversion `_ - with some exception as to be read up in the `code base `_ +The explicit version of an extension is read from `phpversion `_ - with some exception as to be read up in the `code base `_. os == @@ -185,7 +185,7 @@ owncloud ======== **Required**: Defines minimum and maximum versions of the Nextcloud core. In case undefined the values will be taken from the tag `requiremin`_. -.. note:: Currently this tag is also used to check for the nextcloud version number. +.. note:: Currently this tag is also used to check for the Nextcloud version number. Thereby the following "translation" is made: * ownCloud 9.0 matches Nextcloud 9 diff --git a/developer_manual/app/init.rst b/developer_manual/app/init.rst index e414aab5e..80cbec9f2 100644 --- a/developer_manual/app/init.rst +++ b/developer_manual/app/init.rst @@ -13,7 +13,7 @@ The :file:`appinfo/app.php` is the first file that is loaded and executed in Nex \OC::$server->getNavigationManager()->add(function () { $urlGenerator = \OC::$server->getURLGenerator(); return [ - // the string under which your app will be referenced in nextcloud + // the string under which your app will be referenced in Nextcloud 'id' => 'myapp', // sorting weight for the navigation. The higher the number, the higher diff --git a/developer_manual/app/l10n.rst b/developer_manual/app/l10n.rst index 23e9be550..3fccb8f05 100644 --- a/developer_manual/app/l10n.rst +++ b/developer_manual/app/l10n.rst @@ -4,11 +4,11 @@ Translation .. sectionauthor:: Bernhard Posselt -Nextcloud's translation system is powered by `Transifex `_. To start translating sign up and enter a group. If your community app should be added to Transifex contact one of the translation team `in the forums `_ to set it up for you. +Nextcloud's translation system is powered by `Transifex `_. To start translating sign up and enter a group. If your community app should be added to Transifex contact one of the translation teams `in the forums `_ to set it up for you. PHP === -Should it ever be needed to use localized strings on the server-side, simply inject the L10N service from the ServerContainer into the needed constructor +Should it ever be needed to use localized strings on the server-side, simply inject the L10N service from the ServerContainer into the needed constructor: .. code-block:: php @@ -103,7 +103,7 @@ There is a global function **t()** available for translating strings. The first t('myapp', 'Hello World!'); -For advanced usage, refer to the source code **core/js/l10n.js**, **t()** is bind to **OC.L10N.translate()**. +For advanced usage, refer to the source code **core/js/l10n.js**; **t()** is bind to **OC.L10N.translate()**. Hints ===== diff --git a/developer_manual/app/middleware.rst b/developer_manual/app/middleware.rst index 1a73053eb..102e68bf5 100644 --- a/developer_manual/app/middleware.rst +++ b/developer_manual/app/middleware.rst @@ -8,7 +8,7 @@ Middleware is logic that is run before and after each request and is modelled af * **beforeController**: This is executed before a controller method is being executed. This allows you to plug additional checks or logic before that method, like for instance security checks * **afterException**: This is being run when either the beforeController method or the controller method itself is throwing an exception. The middleware is asked in reverse order to handle the exception and to return a response. If the middleware can't handle the exception, it throws the exception again -* **afterController**: This is being run after a successful controllermethod call and allows the manipulation of a Response object. The middleware is run in reverse order +* **afterController**: This is being run after a successful controller method call and allows the manipulation of a Response object. The middleware is run in reverse order * **beforeOutput**: This is being run after the response object has been rendered and allows the manipulation of the outputted text. The middleware is run in reverse order To generate your own middleware, simply inherit from the Middleware class and overwrite the methods that should be used. @@ -77,7 +77,7 @@ The middleware can be registered in the :doc:`container` and added using the **r Parsing annotations =================== -Sometimes its useful to conditionally execute code before or after a controller method. This can be done by defining custom annotations. An example would be to add a custom authentication method or simply add an additional header to the response. To access the parsed annotations, inject the **ControllerMethodReflector** class: +Sometimes it is useful to conditionally execute code before or after a controller method. This can be done by defining custom annotations. An example would be to add a custom authentication method or simply add an additional header to the response. To access the parsed annotations, inject the **ControllerMethodReflector** class: .. code-block:: php diff --git a/developer_manual/app/publishing.rst b/developer_manual/app/publishing.rst index dd9b29154..cd4dc0170 100644 --- a/developer_manual/app/publishing.rst +++ b/developer_manual/app/publishing.rst @@ -6,7 +6,7 @@ App store publishing The Nextcloud App Store ----------------------- -The Nextcloud app store is build into Nextcloud to allow you to get your apps to users as easily and safely as possible. The app store and the process of publishing apps aims to be: +The Nextcloud app store is built into Nextcloud to allow you to get your apps to users as easily and safely as possible. The app store and the process of publishing apps aims to be: * secure * transparent @@ -24,11 +24,11 @@ With each level come requirements and a position in the store. Official ^^^^^^^^ -Official apps are developed by and within the Nextcloud community and its `Github `_ repository and offer functionality central to Nextcloud. They are ready for serious use and can be considered a part of Nextcloud. +Official apps are developed by and within the Nextcloud community and its `GitHub `_ repository and offer functionality central to Nextcloud. They are ready for serious use and can be considered a part of Nextcloud. Requirements: -* developed in Nextcloud github repo +* developed in Nextcloud GitHub repo * minimum of 2 active maintainers and contributions from others * security audited and design reviewed * app is at least 6 months old and has seen regular releases @@ -45,8 +45,7 @@ App store: * major releases optionally featured on nextcloud.com * new versions/updates approved by at least one other person -note: -Official apps include those that are part of the release tarball. We'd like to keep the tarball minimal so most official apps are not part of the standard installation. +.. note:: Official apps include those that are part of the release tarball. We'd like to keep the tarball minimal so most official apps are not part of the standard installation. Approved ^^^^^^^^ @@ -54,7 +53,7 @@ Approved apps are developed by trusted developers and have passed a cursory secu Requirements: -* code is developed in an open and version-managed code repository, ideally github with git but other scm/hosting is OK. +* code is developed in an open and version-managed code repository, ideally GitHub with Git but other SCM/hosting is OK * minimum of one active developer/maintainer * minimum 5 ratings, average score 60/100 or better * app is at least 3 months old @@ -65,8 +64,8 @@ Requirements: .. * app is signed, at least domain verified -.. note:: **Developer trust**: The developer(s) is/are known in community; he/she has/have been active for a while, have met others at events and/or worked with others in various areas. -.. note:: **security audits**: in practice this means that at least some of the code of this developer has been audited; either through another app by the same developer or with an earlier version of the app. And that the attitude of the developer towards these audits has been positive. +.. note:: **Developer trust**: the developer(s) is/are known in community; he/she has/have been active for a while, have met others at events and/or worked with others in various areas. +.. note:: **Security audits**: in practice this means that at least some of the code of this developer has been audited; either through another app by the same developer or with an earlier version of the app. And that the attitude of the developer towards these audits has been positive. App store: @@ -91,13 +90,13 @@ Requirements: App store: -* show up in Apps page provided user has enabled "allow installation of experimental apps" in the settings. -* Warning about security and stability risks is shown for app -* sorted below all others. +* show up in Apps page provided user has enabled "allow installation of experimental apps" in the settings +* warning about security and stability risks is shown for app +* sorted below all others Getting an app approved ----------------------- -If you want your app to be approved, make sure you fulfill all the requirements and then create an issue in the `app approval github repository `_ using `this template `_. A team of Nextcloud contributors will review your application. Updates to an app require re-review but, of course, an initial review takes more effort and time than the checking of an update. +If you want your app to be approved, make sure you fulfill all the requirements and then create an issue in the `app approval GitHub repository `_ using `this template `_. A team of Nextcloud contributors will review your application. Updates to an app require re-review but, of course, an initial review takes more effort and time than the checking of an update. You are encouraged to help review other contributors' apps as well! Every app requires at least two independent reviews so your review of at least 2 (more is better!) other apps will ensure the process continues smoothly. Thank you for participating in this process and being a great Nextcloud Community member! @@ -124,28 +123,28 @@ These are the app guidelines an app has to comply with to have a chance to be ap Legal and security ^^^^^^^^^^^^^^^^^^ -* Apps can not use 'Nextcloud' in their name +* Apps can not use 'Nextcloud' in their name. * Irregular and unannounced security audits of all apps can and will take place. * If any indication of malicious intent or bad faith is found the developer(s) in question can count on a minimum 2 year ban from any Nextcloud infrastructure. * Malicious intent includes deliberate spying on users by leaking user data to a third party system or adding a back door (like a hard-coded user account) to Nextcloud. An unintentional security bug that gets fixed in time won't be considered bad faith. * Apps do not violate any laws; it has to comply with copyright- and trademark law. * App authors have to respond timely to security concerns and not make Nextcloud more vulnerable to attack. -.. note:: distributing malicious or illegal applications can have legal consequences including, but not limited to Nextcloud or affected users taking legal action. +.. note:: Distributing malicious or illegal applications can have legal consequences including, but not limited to Nextcloud or affected users taking legal action. Be technically sound ^^^^^^^^^^^^^^^^^^^^ -* Apps can only use the public Nextcloud API -* At time of the release of an app it can only be configured to be compatible with the latest Nextcloud release +1 -* Apps should not cause Nextcloud to break, consume excessive memory or slow Nextcloud down -* Apps should not hamper functionality of Nextcloud unless that is explicitly the goal of the app +* Apps can only use the public Nextcloud API. +* At time of the release of an app it can only be configured to be compatible with the latest Nextcloud release +1. +* Apps should not cause Nextcloud to break, consume excessive memory or slow Nextcloud down. +* Apps should not hamper functionality of Nextcloud unless that is explicitly the goal of the app. Respect the users ^^^^^^^^^^^^^^^^^ -* Apps have to follow design and `HTML/CSS layout guidelines <../app/css.html>`_ -* Apps correctly clean up after themselves on uninstall and correctly handle up- and downgrades +* Apps have to follow design and `HTML/CSS layout guidelines <../app/css.html>`_. +* Apps correctly clean up after themselves on uninstall and correctly handle up- and downgrades. * Apps clearly communicate their intended purpose and active features, including features introduced through updates. * Apps respect the users' choices and do not make unexpected changes, or limit users' ability to revert them. For example, they do not remove other apps or disable settings. * Apps must respect user privacy. IF user data is sent anywhere, this must be clearly explained and be kept to a minimum for the functioning of an app. Use proper security measures when needed. diff --git a/developer_manual/app/request.rst b/developer_manual/app/request.rst index 445f3932e..7753490e9 100644 --- a/developer_manual/app/request.rst +++ b/developer_manual/app/request.rst @@ -6,7 +6,7 @@ Request lifecycle A typical HTTP request consists of the following: -* **An URL**: e.g. /index.php/apps/myapp/something +* **A URL**: e.g. /index.php/apps/myapp/something * **Request Parameters**: e.g. ?something=true&name=tom * **A Method**: e.g. GET * **Request headers**: e.g. Accept: application/json @@ -15,7 +15,7 @@ The following sections will present an overview over how that request is being p Front controller ================ -In the beginning, all requests are sent to Nextcloud's :file:`index.php` which in turn executes :file:`lib/base.php`. This file inspects the HTTP headers and abstracts away differences between different Web servers and initializes the basic classes. Afterwards the basic apps are being loaded in the following order: +In the beginning, all requests are sent to Nextcloud's :file:`index.php` which in turn executes :file:`lib/base.php`. This file inspects the HTTP headers, abstracts away differences between different Web servers and initializes the basic classes. Afterwards the basic apps are being loaded in the following order: * Authentication backends * Filesystem diff --git a/developer_manual/app/routes.rst b/developer_manual/app/routes.rst index 93575fe59..93120cb7c 100644 --- a/developer_manual/app/routes.rst +++ b/developer_manual/app/routes.rst @@ -4,7 +4,7 @@ Routing .. sectionauthor:: Bernhard Posselt -Routes map an URL and a method to a controller method. Routes are defined inside :file:`appinfo/routes.php` by passing a configuration array to the registerRoutes method. An example route would look like this: +Routes map a URL and a method to a controller method. Routes are defined inside :file:`appinfo/routes.php` by passing a configuration array to the registerRoutes method. An example route would look like this: .. code-block:: php @@ -21,7 +21,7 @@ Routes map an URL and a method to a controller method. Routes are defined inside The route array contains the following parts: -* **url**: The url that is matched after */index.php/apps/myapp* +* **url**: The URL that is matched after */index.php/apps/myapp* * **name**: The controller and the method to call; *page#index* is being mapped to *PageController->index()*, *articles_api#drop_latest* would be mapped to *ArticlesApiController->dropLatest()*. The controller that matches the page#index name would have to be registered in the following way inside :file:`appinfo/application.php`: .. code-block:: php @@ -54,9 +54,9 @@ The route array contains the following parts: } * **method** (Optional, defaults to GET): The HTTP method that should be matched, (e.g. GET, POST, PUT, DELETE, HEAD, OPTIONS, PATCH) -* **requirements** (Optional): lets you match and extract URLs that have slashes in them (see **Matching suburls**) -* **postfix** (Optional): lets you define a route id postfix. Since each route name will be transformed to a route id (**page#method** -> **myapp.page.method**) and the route id can only exist once you can use the postfix option to alter the route id creation by adding a string to the route id e.g.: **'name' => 'page#method', 'postfix' => 'test'** will yield the route id **myapp.page.methodtest**. This makes it possible to add more than one route/url for a controller method -* **defaults** (Optional): If this setting is given, a default value will be assumed for each url parameter which is not present. The default values are passed in as a key => value par array +* **requirements** (Optional): lets you match and extract URLs that have slashes in them (see **Matching subURLs**) +* **postfix** (Optional): lets you define a route id postfix. Since each route name will be transformed to a route id (**page#method** -> **myapp.page.method**) and the route id can only exist once you can use the postfix option to alter the route id creation by adding a string to the route id, e.g., **'name' => 'page#method', 'postfix' => 'test'** will yield the route id **myapp.page.methodtest**. This makes it possible to add more than one route/URL for a controller method +* **defaults** (Optional): If this setting is given, a default value will be assumed for each URL parameter which is not present. The default values are passed in as a key => value par array Extracting values from the URL ============================== @@ -83,9 +83,9 @@ It is possible to extract values from the URL to allow RESTful URL design. To ex The identifier used inside the route is being passed into controller method by reflecting the method parameters. So basically if you want to get the value **{id}** in your method, you need to add **$id** to your method parameters. -Matching suburls +Matching subURLs ================ -Sometimes its needed to match more than one URL fragment. An example would be to match a request for all URLs that start with **OPTIONS /index.php/apps/myapp/api**. To do this, use the **requirements** parameter in your route which is an array containing pairs of **'key' => 'regex'**: +Sometimes it is needed to match more than one URL fragment. An example would be to match a request for all URLs that start with **OPTIONS /index.php/apps/myapp/api**. To do this, use the **requirements** parameter in your route which is an array containing pairs of **'key' => 'regex'**: .. code-block:: php @@ -106,9 +106,9 @@ Sometimes its needed to match more than one URL fragment. An example would be to } -Default values for suburl +Default values for subURL ========================== -Apart from matching requirements, a suburl may also have a default value. Say you want to support pagination (a 'page' parameter) for your **/posts** suburl that displays posts entries list. You may set a default value for the 'page' parameter, that will be used if not already set in the url. Use the **defaults** parameter in your route which is an array containing pairs of **'urlparameter' => 'defaultvalue'**: +Apart from matching requirements, a subURL may also have a default value. Say you want to support pagination (a 'page' parameter) for your **/posts** subURL that displays posts entries list. You may set a default value for the 'page' parameter, that will be used if not already set in the URL. Use the **defaults** parameter in your route which is an array containing pairs of **'urlparameter' => 'defaultvalue'**: .. code-block:: php @@ -121,7 +121,7 @@ Apart from matching requirements, a suburl may also have a default value. Say yo 'name' => 'post#index', 'url' => '/post/{page}', 'verb' => 'GET', - 'defaults' => array('page' => 1) // this allows same url as /index.php/myapp/post/1 + 'defaults' => array('page' => 1) // this allows same URL as /index.php/myapp/post/1 ), // controller/postcontroller.php @@ -181,7 +181,7 @@ can be abbreviated by using the **resources** key: Using the URLGenerator ======================== -Sometimes its useful to turn a route into a URL to make the code independent from the URL design or to generate an URL for an image in **img/**. For that specific use case, the ServerContainer provides a service that can be used in your container: +Sometimes it is useful to turn a route into a URL to make the code independent from the URL design or to generate a URL for an image in **img/**. For that specific use case, the ServerContainer provides a service that can be used in your container: .. code-block:: php @@ -216,7 +216,7 @@ Sometimes its useful to turn a route into a URL to make the code independent fro } -Inside the PageController the URL generator can now be used to generate an URL for a redirect: +Inside the PageController the URL generator can now be used to generate a URL for a redirect: .. code-block:: php diff --git a/developer_manual/app/settings.rst b/developer_manual/app/settings.rst index 96a06ed42..d91f65e9d 100644 --- a/developer_manual/app/settings.rst +++ b/developer_manual/app/settings.rst @@ -12,16 +12,16 @@ Admin For Nextcloud 10 the admin settings page got reworked. It is not a long list anymore, but divided into sections, where related settings forms are grouped. For example, in the **Sharing** section are only settings (built-in and of apps) -relate to sharing. +related to sharing. Settings Form ============= -For the settings form, three things are necessary +For the settings form, three things are necessary: 1. A class implementing ``\OCP\Settings\ISettings`` 2. A template -3. The implementing class specified in the apps`s info.xml +3. The implementing class specified in the app's info.xml Below is an example for an implementor of the ISettings interface. It is based on the survey_client solution. @@ -202,8 +202,8 @@ implementation of the **user_ldap** app. Section ======= -It is also possible, that an app registers its own section. This should be done -only, if there is not fitting corresponding section and the apps settings form +It is also possible that an app registers its own section. This should be done +only if there is not fitting corresponding section and the apps settings form takes a lot of screen estate. Otherwise, register to "additional". Basically, it works the same way as with the settings form. There are only two @@ -260,7 +260,7 @@ An example implementation of the ISection interface: } -Also the section must be registered in the apps`s info.xml. +Also the section must be registered in the app's info.xml. Personal -------- diff --git a/developer_manual/app/startapp.rst b/developer_manual/app/startapp.rst index bc73379b9..af12d1a2a 100644 --- a/developer_manual/app/startapp.rst +++ b/developer_manual/app/startapp.rst @@ -12,7 +12,7 @@ Then create a skeleton app in the `app store `_. -Download the extracted the downloaded file and move it into your ``apps/`` directory. Afterwards the application can be enabled on the `apps page `_. +Download the compressed file that contains the generated app and extract it into your ``apps/`` directory. Afterwards the application can be enabled on the `apps page `_. The first basic app is now available at ``http://localhost:8080/index.php/apps/yourappid/`` @@ -172,7 +172,7 @@ Since the route which returns the initial HTML has been taken care of, the contr } -.. note:: The parameters are extracted from the request body and the url using the controller method's variable names. Since PHP does not support type hints for primitive types such as ints and booleans, we need to add them as annotations in the comments. In order to type cast a parameter to an int, add **@param int $parameterName** +.. note:: The parameters are extracted from the request body and the URL using the controller method's variable names. Since PHP does not support type hints for primitive types such as ints and booleans, we need to add them as annotations in the comments. In order to type cast a parameter to an int, add **@param int $parameterName** Now the controller methods need to be connected to the corresponding URLs in the **ownnotes/appinfo/routes.php** file: @@ -1045,7 +1045,7 @@ The template file **ownnotes/templates/part.navigation.php** contains the naviga