Theming Nextcloud

Themes can be used to customize the look and feel of Nextcloud.

Note

This is an advanced way of theming Nextcloud; the Nextcloud team recommends instead the use of the Theming app which, when enabled, can be accessed from the Admin settings.

Getting started

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 to make a backup of your current theme(s), e.g.:

  • cd …/nextcloud/themes
  • cp -r example mytheme

Creating and activating a new theme

There are two basic ways of creating new themings:

  • doing all new from scratch
  • starting from an existing theme or the example theme and doing everything step by step and more experimentally

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
  • make sure that the theming app is disabled

Structure

The folder structure of a theme is exactly the same as the main Nextcloud structure. You can override js files, images, translations and templates with own versions. CSS files are loaded additionally to the default files so you can override CSS properties. CSS files and the standard pictures that are used reside for example in /nextcloud/core/ and /nextcloud/settings/ in these sub folders:

  • css = style sheets
  • js = JavaScripts
  • img = images
  • l10n = translation files
  • templates = PHP and HTML template files

Notes for updates

Note

With Nextcloud 12, CSS files have been merged into one server.css so in order to keep your theme working you should consolidate your existing css styles into a server.css file. As for the example theme the styles.css file has been renamed to server.css.

It is not recommended to the user to perform adaptations inside the folder /themes/example because files inside this folder might get replaced during the next Nextcloud update process.

During an update, files might get changed within the core and settings folders. This could result in problems because your template files will not ‘know’ about these changes and therefore must be manually merged with the updated core file or simply be deleted (or renamed for a test).

For example if /settings/templates/apps.php gets updated by a new Nextcloud version, and you have a /themes/MyTheme/settings/templates/apps.php in your template, you must merge the changes that where made within the update with the ones you did in your template.

But this is unlikely and will be mentioned in the Nextcloud release notes if it occurs.

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 all other terms the shipped translation will be used.

If you want to override the translation of the term “Download” within the files app for the language de you need to create the file themes/THEME_NAME/apps/files/l10n/de.js and put the following code in:

OC.L10N.register(
  "files",
  {
    "Download" : "Herunterladen"
  },
  "nplurals=2; plural=(n != 1);"
);

Additionally you need to create another file themes/THEME_NAME/apps/files/l10n/de.json with the same translations that look like this:

{
  "translations": {
    "Download" : "Herunterladen"
  },
  "pluralForm" :"nplurals=2; plural=(n != 1);"
}

Both files (.js and .json) are needed with the same translations, because the first is needed to enable translations in the JavaScript code and the second one is read by the PHP code and provides the data for translated terms in there.

How to update custom mimetype icons

The following command is required to run after adding custom mimetype icons to your theme:

sudo -u www-data php occ maintenance:mimetype:update-js

How to change names, slogans and URLs

The Nextcloud theming allows a lot of the names that are shown on the web interface to be changed. It’s also possible to change the URLs to the documentation or the Android/iOS apps.

This can be done with a file named defaults.php within the root of the theme. You can find it in the example theme (/themes/example/defaults.php). In there you need to specify a class named OC_Theme and need to implement the methods you want to overwrite:

class OC_Theme {
  public function getAndroidClientUrl() {
    return 'https://play.google.com/store/apps/details?id=com.nextcloud.client';
  }

  public function getName() {
    return 'Nextcloud';
  }
}

Each method should return a string. Following methods are available:

  • getAndroidClientUrl
  • getBaseUrl
  • getDocBaseUrl
  • getEntity
  • getName
  • getHTMLName
  • getiOSClientUrl
  • getiTunesAppId
  • getLogoClaim
  • getLongFooter
  • getMailHeaderColor
  • getSyncClientUrl
  • getTitle
  • getShortFooter
  • getSlogan

Note

Only these methods are available in the templates, because we internally wrap around hardcoded method names.

One exception is the method buildDocLinkToKey which gets passed in a key as first parameter. For core we do something like this to build the documentation link:

public function buildDocLinkToKey($key) {
  return $this->getDocBaseUrl() . '/server/9.0/go.php?to=' . $key;
}

Testing the new theme out

There are different options for doing so:

  • If you’re using a tool like the Inspector tools inside Mozilla, you can test out the CSS-Styles immediately inside the css-attributes, while looking at them.
  • If you have a developing/testing server as described in 1. you can test out the effects in a real environment permanently.