mirror of
https://github.com/nextcloud/documentation.git
synced 2026-01-04 02:36:49 +07:00
141 lines
4.6 KiB
ReStructuredText
141 lines
4.6 KiB
ReStructuredText
==========
|
|
JavaScript
|
|
==========
|
|
|
|
.. sectionauthor:: Bernhard Posselt <dev@bernhard-posselt.com>
|
|
|
|
The JavaScript files reside in the **js/** folder and should be included in the template:
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
// add one file
|
|
script('myapp', 'script'); // adds js/script.js
|
|
|
|
// add multiple files in the same app
|
|
script('myapp', array('script', 'navigation')); // adds js/script.js js/navigation.js
|
|
|
|
// add vendor files (also allows the array syntax)
|
|
vendor_script('myapp', 'script'); // adds vendor/script.js
|
|
|
|
If the script file is only needed when the file list is displayed, you should
|
|
listen to the ``OCA\Files::loadAdditionalScripts`` event:
|
|
|
|
.. code-block:: php
|
|
|
|
<?php
|
|
$eventDispatcher = \OC::$server->getEventDispatcher();
|
|
$eventDispatcher->addListener('OCA\Files::loadAdditionalScripts', function() {
|
|
script('myapp', 'script'); // adds js/script.js
|
|
vendor_script('myapp', 'script'); // adds vendor/script.js
|
|
});
|
|
|
|
|
|
Sending the CSRF token
|
|
----------------------
|
|
|
|
If any other JavaScript request library than jQuery is being used, the requests need to send the CSRF token as an HTTP header named **requesttoken**. The token is available in the global variable **oc_requesttoken**.
|
|
|
|
For AngularJS the following lines would need to be added:
|
|
|
|
.. code-block:: js
|
|
|
|
var app = angular.module('MyApp', []).config(['$httpProvider', function($httpProvider) {
|
|
$httpProvider.defaults.headers.common.requesttoken = oc_requesttoken;
|
|
}]);
|
|
|
|
|
|
Generating URLs
|
|
---------------
|
|
|
|
To send requests to Nextcloud the base URL where Nextcloud is currently running is needed. To get the base URL use:
|
|
|
|
.. code-block:: js
|
|
|
|
var baseUrl = OC.generateUrl('');
|
|
|
|
Full URLs can be generated by using:
|
|
|
|
.. code-block:: js
|
|
|
|
var authorUrl = OC.generateUrl('/apps/myapp/authors/1');
|
|
|
|
|
|
Extending core parts
|
|
--------------------
|
|
|
|
It is possible to extend components of the core web UI. The following examples
|
|
should show how this is possible.
|
|
|
|
Extending the "new" menu in the files app
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
.. versionadded:: 9.0
|
|
|
|
.. code-block:: js
|
|
|
|
var myFileMenuPlugin = {
|
|
attach: function (menu) {
|
|
menu.addMenuEntry({
|
|
id: 'abc',
|
|
displayName: 'Menu display name',
|
|
templateName: 'templateName.ext',
|
|
iconClass: 'icon-filetype-text',
|
|
fileType: 'file',
|
|
actionHandler: function () {
|
|
console.log('do something here');
|
|
}
|
|
});
|
|
}
|
|
};
|
|
OC.Plugins.register('OCA.Files.NewFileMenu', myFileMenuPlugin);
|
|
|
|
This will register a new menu entry in the "New" menu of the files app. The
|
|
method ``attach()`` is called once the menu is built. This usually happens right
|
|
after the click on the button.
|
|
|
|
|
|
Loading initial state
|
|
---------------------
|
|
|
|
Often apps have some kind of initial state. Often the first thing a script does
|
|
is querying an endpoint to obtain this initial state. This makes the user
|
|
experience sub optimal as they have to wait for yet another request to finish
|
|
loading.
|
|
|
|
To provide the initial state in a standardized way quickly to the javascript
|
|
Nextcloud provides an API. The API consists of a PHP part (that supplies the state)
|
|
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
|
|
has two methods you can use to provide the initial state.
|
|
|
|
* ``provideInitialState(string $appName, string $key, $data)``: Use this method
|
|
if you know for sure your state will be used. For example on the settings page
|
|
of your app.
|
|
* ``provideLazyInitialState(string $appName, string $key, Closure $closure)``:
|
|
Use this method if you want to inject your state on a general page. For example
|
|
the initial state of the notifications app. The callback will be invoked if and only if a template is rendered.
|
|
|
|
You call both methods with the name of your app and a key. This is to scope
|
|
the states properly. You will need both when retrieving the initial state in
|
|
javascript.
|
|
|
|
The data for the initial state is converted to JSON. So be sure that the
|
|
data you provide (either in $data or as a return from the $closure) can be converted
|
|
to JSON.
|
|
|
|
Obtaining the initial state in JavaScript
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
To obtain the initial state in your JavaScript you have to only call one
|
|
function
|
|
|
|
.. code-block:: js
|
|
|
|
const state = OCP.InitialState.loadState('MyApp', 'MyState');
|
|
|
|
Now state will contain the provided state which you can use as any variable. It
|
|
is as simple as that.
|