diff --git a/developer_manual/android_library/examples.rst b/developer_manual/android_library/examples.rst index c1f4a477b..ca90647bd 100644 --- a/developer_manual/android_library/examples.rst +++ b/developer_manual/android_library/examples.rst @@ -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 diff --git a/developer_manual/android_library/index.rst b/developer_manual/android_library/index.rst index dc96e4250..3a02ece7f 100644 --- a/developer_manual/android_library/index.rst +++ b/developer_manual/android_library/index.rst @@ -18,7 +18,7 @@ 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 `_ +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/app/code_signing.rst b/developer_manual/app/code_signing.rst index 993b337e4..267936b14 100644 --- a/developer_manual/app/code_signing.rst +++ b/developer_manual/app/code_signing.rst @@ -58,7 +58,7 @@ private key. This Root Authority is only used for signing certificate signing requests (CSRs) for additional certificates. Certificates issued by the Root Authority must -always to be limited to a specific scope, usually the application identifier. +always be limited to a specific scope, usually the application identifier. This enforcement is done using the ``CN`` attribute of the certificate. Code signing is then done by creating a ``signature.json`` file with the @@ -121,10 +121,10 @@ examples will assume that you are trying to sign an application named your GitHub account to show your mail address in your profile. Nextcloud might ask you for further information to verify that you're the legitimate owner of the application. Make sure to keep the private key file (``contacts.key``) - secret and not disclose it to any third-parties. + secret and not disclose it to any third parties. 3. Nextcloud will provide you with the signed certificate. 4. Run ``./occ integrity:sign-app`` to sign your application, and specify - your private and the public key as well as the path to the application. + your private and public keys as well as the path to the application. A valid example looks like: ``./occ integrity:sign-app --privateKey=/Users/lukasreschke/contacts.key --certificate=/Users/lukasreschke/CA/contacts.crt --path=/Users/lukasreschke/Programming/contacts`` diff --git a/developer_manual/app/container.rst b/developer_manual/app/container.rst index 1a75061c3..8774489a1 100644 --- a/developer_manual/app/container.rst +++ b/developer_manual/app/container.rst @@ -125,7 +125,7 @@ The container works in the following way: $c->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..e736a637e 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: @@ -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..ed74c5279 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 @@ -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/l10n.rst b/developer_manual/app/l10n.rst index 23e9be550..45d903a00 100644 --- a/developer_manual/app/l10n.rst +++ b/developer_manual/app/l10n.rst @@ -4,7 +4,7 @@ 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 === @@ -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..4e8f2b13e 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 @@ -65,8 +65,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: @@ -131,7 +131,7 @@ Legal and security * 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 ^^^^^^^^^^^^^^^^^^^^ 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..852ebe579 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 @@ -55,7 +55,7 @@ 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 +* **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 @@ -85,7 +85,7 @@ The identifier used inside the route is being passed into controller method by r 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 @@ -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..3a8e0351e 100644 --- a/developer_manual/app/settings.rst +++ b/developer_manual/app/settings.rst @@ -12,7 +12,7 @@ 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 ============= @@ -21,7 +21,7 @@ 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/tutorial.rst b/developer_manual/app/tutorial.rst index 9f180711a..d59f4cad0 100644 --- a/developer_manual/app/tutorial.rst +++ b/developer_manual/app/tutorial.rst @@ -33,7 +33,7 @@ Now open another terminal window and start the development server:: Afterwards a skeleton app can be created 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/`` diff --git a/developer_manual/app/users.rst b/developer_manual/app/users.rst index 74819b01d..6b3fac635 100644 --- a/developer_manual/app/users.rst +++ b/developer_manual/app/users.rst @@ -1,5 +1,5 @@ ============== -Usermanagement +User Management ============== .. sectionauthor:: Bernhard Posselt diff --git a/developer_manual/bugtracker/codereviews.rst b/developer_manual/bugtracker/codereviews.rst index 5df3d68d6..521e796fa 100644 --- a/developer_manual/bugtracker/codereviews.rst +++ b/developer_manual/bugtracker/codereviews.rst @@ -10,7 +10,7 @@ Introduction In order to increase the code quality within Nextcloud, developers are requested to perform code reviews. As we are now heavily using the GitHub platform these -code review shall take place on GitHub as well. +code reviews shall take place on GitHub as well. Precondition ------------ @@ -32,7 +32,7 @@ How will it work? #. Other developers (either named or at free will) have a look at the changes and are welcome to write comments within the comment field. #. In case the reviewer is okay with the changes and thinks all his comments and - suggestions have been take into account a :+1 on the comment will signal a positive + suggestions have been taken into account a :+1 on the comment will signal a positive review. #. Before a pull request will be merged into master or the corresponding branch at least 2 reviewers need to give :+1 score. diff --git a/developer_manual/bugtracker/index.rst b/developer_manual/bugtracker/index.rst index 7ea173a42..1c09c1155 100644 --- a/developer_manual/bugtracker/index.rst +++ b/developer_manual/bugtracker/index.rst @@ -15,7 +15,7 @@ Thank you for helping Nextcloud by reporting bugs. Before submitting an issue, p * If the issue is with the Nextcloud server, report it to the `Server repository`_ * If the issue is with the Nextcloud client, report it to the `Client repository`_ -* If the issue with with an Nextcloud app, report it to where that app is developed +* If the issue with with a Nextcloud app, report it to where that app is developed * If the app is listed in our `main GitHub organization`_ report it to the correct sub repository diff --git a/developer_manual/bugtracker/kanban.rst b/developer_manual/bugtracker/kanban.rst index b9041a5b0..998c97eaf 100644 --- a/developer_manual/bugtracker/kanban.rst +++ b/developer_manual/bugtracker/kanban.rst @@ -154,7 +154,7 @@ What does a developer think? manually.* When can I pull? - As long as you are reviewing the issue the you should leave the "6 – + As long as you are reviewing the issue you should leave the "6 – Reviewing" label assigned. Before moving the issue to the "To review" step the issue should have been resolved, meaning that not only the issue has been implemented but also no other functionality has been broken. @@ -182,7 +182,7 @@ Who is Assigned? No one. -While we stated before that said that we push issues to the next column, we can +While we stated before that we push issues to the next column, we can of course move the item back and forth arbitrarily. Basically you can drag the issue around in the huboard or just change the label when viewing the issue in the GitHub. @@ -241,7 +241,7 @@ Misc Labels * Needs info – Either from a developer or the bug reporter. This is nearly as severe as Panic, because no further action can be taken -* L18n – A translation issue go see our `transifex`_ +* L18n – A translation issue; go see our `transifex`_ * Junior Job – The issue is considered a good starting point to get involved in Nextcloud development Milestones equal Releases diff --git a/developer_manual/bugtracker/triaging.rst b/developer_manual/bugtracker/triaging.rst index 87a3d67f1..390b60455 100644 --- a/developer_manual/bugtracker/triaging.rst +++ b/developer_manual/bugtracker/triaging.rst @@ -6,7 +6,7 @@ Nextcloud Bug Triaging :maxdepth: 2 :hidden: -Bug Triaging is the process of checking bug reports to see if they are still valid (the problem might be solved since the bug was reported), reproducing them when possible (to make sure it really is an Nextcloud issue and not a configuration problem) and in general making sure the bug is useful for a developer who wants to fix it. If the bug is not useful and can't be augmented by the original reporter or the triaging contributor, it has to be closed. +Bug Triaging is the process of checking bug reports to see if they are still valid (the problem might be solved since the bug was reported), reproducing them when possible (to make sure it really is a Nextcloud issue and not a configuration problem) and in general making sure the bug is useful for a developer who wants to fix it. If the bug is not useful and can't be augmented by the original reporter or the triaging contributor, it has to be closed. Why do you want to join ======================= diff --git a/developer_manual/core/externalapi.rst b/developer_manual/core/externalapi.rst index b8fb73d10..0dc72095c 100644 --- a/developer_manual/core/externalapi.rst +++ b/developer_manual/core/externalapi.rst @@ -31,13 +31,13 @@ Returning Data Once the API backend has matched your URL, your callable function as defined in **BarController::getFoo** will be executed. The AppFramework will make sure that send parameters are provided to the method based on its declaration. To return -data back the the client, you should return an instance of (a subclass of) +data back to the client, you should return an instance of (a subclass of) :php:class:`OCP\AppFramework\Http\Response`, typically :php:class:`OCSResponse`. The API backend will then use this to construct the XML or JSON response. Authentication & Basics ~~~~~~~~~~~~~~~~~~~~~~~ -Because REST is stateless you have to send user and password each time you access the API. Therefore running Nextcloud **with SSL is highly recommended** otherwise **everyone in your network can log your credentials**:: +Because REST is stateless you have to send user and password each time you access the API. Therefore running Nextcloud **with SSL is highly recommended**; otherwise **everyone in your network can log your credentials**:: https://user:password@example.com/ocs/v1.php/apps/yourapp diff --git a/developer_manual/core/theming.rst b/developer_manual/core/theming.rst index 8b54b7925..d89bba692 100644 --- a/developer_manual/core/theming.rst +++ b/developer_manual/core/theming.rst @@ -11,16 +11,15 @@ This documentation contains only the Web-frontend adaptations so far. Getting started =============== -A good idea getting starting with a dynamically created website is to inspect it with **web developer tools**, that are found in almost any browser. They show the generated HTML and the CSS Code, that the client/browser is receiving: -With this facts you can easily determine, where the following object-related attributes for the phenomenons are settled: +A good idea to get started with a dynamically created website is to inspect it with **web developer tools**, that are found in almost any browser. They show the generated HTML and the CSS Code that the client/browser is receiving: +With this facts you can easily determine where the following object-related attributes for the phenomenons are settled: * place * colour * links * graphics -The next thing you should do, before starting any changes is: -Make a backup of your current theme(s) e.g.: +The next thing you should do, before starting any changes, is to make a backup of your current theme(s), e.g.: * cd …/nextcloud/themes * cp -r example mytheme @@ -35,8 +34,8 @@ There are two basic ways of creating new themings: Depending on how you created your new theme it will be necessary to -* put a new theme into the /themes -folder. The theme can be activated by putting ``'theme' => 'MyTheme'``, into the ``/config/config.php`` file. -* make your changes in the ``/themes/MyTheme`` -folder +* put a new theme into the /themes folder. The theme can be activated by putting ``'theme' => 'MyTheme'`` into the ``/config/config.php`` file. +* make your changes in the ``/themes/MyTheme`` folder * make sure that the theming app is disabled @@ -92,15 +91,15 @@ If you want to do a quick exchange like (1) it's important to know the size of t * You can look up sizing in most cases via the file properties inside your file-manager * Create an own picture/logo with the same size then -The (main) pictures, that can be found inside Nextcloud standard theming are the following: +The (main) pictures that can be found inside Nextcloud standard theming are the following: * The logo at the login-page above the credentials-box: …/nextcloud/themes/default/core/img/logo.svg -* The logo, that's always in the left upper corner after login: …/nextcloud/themes/default/core/img/logo-wide.svg +* The logo that's always in the left upper corner after login: …/nextcloud/themes/default/core/img/logo-wide.svg Inserting your new logo ----------------------- Inserting a new logo into an existing theme is as simple as replacing the old logo with the new (generated) one. -You can use: scalable vector graphics (.svg) or common graphics formats for the internet such as portable network graphics (.png) or .jepg +You can use: scalable vector graphics (.svg) or common graphics formats for the internet such as portable network graphics (.png) or .jpeg Just insert the new created picture by using the unchanged name of the old picture. The app icons can also be overwritten in a theme. To change for example the app icon of the activity app you need to overwrite it by saving the new image to …/nextcloud/themes/default/apps/activity/img/activity.svg @@ -134,10 +133,10 @@ On the top of the login page you can see a case- distinguished setting for diffe background: linear-gradient(top, #33537a 0%,#1d2d42 100%); /* W3C */ } -The different background-assignments indicate the headers for a lot of different browser types. What you most likely want to do is change the #35537a (lighter blue) and #ld2d42 (dark blue) color to the colours of our choice. In some older and other browsers, there is just one color, but in the rest showing gradients is possible. -The login page background is a horizontal gradient. The first hex number, #35537a, is the top color of the gradient at the login screen. The second hex number, #ld2d42 is the bottom color of the gradient at the login screen. +The different background-assignments indicate the headers for a lot of different browser types. What you most likely want to do is change the #35537a (lighter blue) and #ld2d42 (dark blue) color to the colours of our choice. In some older and other browsers there is just one color, but in the rest showing gradients is possible. +The login page background is a horizontal gradient. The first hex number, #35537a, is the top color of the gradient at the login screen. The second hex number, #ld2d42, is the bottom color of the gradient at the login screen. The gradient in top of the normal view after login is also defined by these CSS-settings, so that they take effect in logged in situation as well. -Change these colors to the hex color of your choice: +Change these colors to the hex color of your choice. As usual: * the first two figures give the intensity of the red channel, @@ -156,7 +155,7 @@ How to change translations You can override the translation of single strings within your theme. Simply create the same folder structure within your theme folder for the language file -you want to override. Only the changed strings need to be added to that file for +you want to override. Only the changed strings need to be added to that file; for all other terms the shipped translation will be used. If you want to override the translation of the term "Download" within the diff --git a/developer_manual/core/translation.rst b/developer_manual/core/translation.rst index 29e196d87..a4daae33e 100644 --- a/developer_manual/core/translation.rst +++ b/developer_manual/core/translation.rst @@ -4,8 +4,8 @@ Translation Make text translatable ---------------------- -In HTML or PHP wrap it like this ``t('This is some text'));?>`` or this ``t('This is some text'));?>`` -For the right date format use ``l('date', time()));?>``. Change the way dates are shown by editing /core/l10n/l10n-[lang].php +In HTML or PHP wrap it like this ``t('This is some text'));?>`` or this ``t('This is some text'));?>``. +For the right date format use ``l('date', time()));?>``. Change the way dates are shown by editing /core/l10n/l10n-[lang].php. To translate text in javascript use: ``t('appname','text to translate');`` @@ -65,8 +65,8 @@ Please follow the steps below to add translation support to your app: Create a folder ``l10n``. Create the file ``ignorelist`` which can contain files which shall not be scanned during step 4. -Edit ``l10n/.tx/config`` and copy/past a config section and adopt it by changing the app/folder name. -Run ``perl l10n.pl read`` with l10n +Edit ``l10n/.tx/config`` and copy/paste a config section and adapt it by changing the app/folder name. +Run ``perl l10n.pl read`` with l10n. Add the newly created translation template (l10n/Templates/.pot) to git and commit the changes above. After the next nightly sync job a new resource will appear on Transifex and from now on every night the latest translations will arrive. diff --git a/developer_manual/core/unit-testing.rst b/developer_manual/core/unit-testing.rst index b20334b99..819c06d0f 100644 --- a/developer_manual/core/unit-testing.rst +++ b/developer_manual/core/unit-testing.rst @@ -9,7 +9,7 @@ Getting PHPUnit Nextcloud uses PHPUnit >= 4.8 for unit testing. -To install it, either get it via your packagemanager:: +To install it, either get it via your package manager:: sudo apt-get install phpunit @@ -38,9 +38,9 @@ To get started, do the following: Then you can simply run the created test with phpunit. -.. note:: If you use Nextcloud functions in your class under test (i.e: OC::getUser()) you'll need to bootstrap Nextcloud or use dependency injection. +.. note:: If you use Nextcloud functions in your class under test (i.e., OC::getUser()) you'll need to bootstrap Nextcloud or use dependency injection. -.. note:: You'll most likely run your tests under a different user than the Web server. This might cause problems with your PHP settings (i.e: open_basedir) and requires you to adjust your configuration. +.. note:: You'll most likely run your tests under a different user than the Web server. This might cause problems with your PHP settings (i.e., open_basedir) and requires you to adjust your configuration. An example for a simple test would be: @@ -84,7 +84,7 @@ In :file:`/srv/http/nextcloud/apps/myapp/` you run the test with:: phpunit tests/testaddtwo.php -Make sure to extend the ``\Test\TestCase`` class with your test and always call the parent methods, +Make sure to extend the ``\Test\TestCase`` class with your test and always call the parent methods when overwriting ``setUp()``, ``setUpBeforeClass()``, ``tearDown()`` or ``tearDownAfterClass()`` method from the TestCase. These methods set up important stuff and clean up the system after the test, so the next test can run without side effects, like remaining files and entries in the file cache, etc.