JavaScript

The JavaScript files reside in the js/ folder and should be included in the template:

<?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:

<?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:

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:

var baseUrl = OC.generateUrl('');

Full URLs can be generated by using:

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

New in version 9.0.

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\AppFramework\Services\IInitialState. This service has two methods you can use to provide the initial state.

• provideInitialState(string $appName, string $key, $data): 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): 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

• Vue way with @nextcloud/initial-state:

import { loadState } from '@nextcloud/initial-state'

const val = loadState('myapp', 'user_preference')

// Provide a fallback value to return when the state is not found
const valWithFallback = loadState('myapp', 'user_preference', 'no_preference')

• Legacy way:

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.