From 097570834662a892ba79c440d6452888b8b86bfc Mon Sep 17 00:00:00 2001 From: Christian Ludwig Date: Wed, 14 Oct 2015 16:52:12 +0200 Subject: [PATCH 1/3] removed mentioning of 'default theme' in theming Since v8 there is no 'default' theme, but an exaple theme. --- developer_manual/core/theming.rst | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/developer_manual/core/theming.rst b/developer_manual/core/theming.rst index 5755365be..0080a4604 100644 --- a/developer_manual/core/theming.rst +++ b/developer_manual/core/theming.rst @@ -19,14 +19,11 @@ With this facts you can easily determine, where the following object-related att * links * graphics -In owncloud standard theme everything is held very simple. This allows you quick adapting. In an unchanged ownCloud version CSS files and the standard pictures reside in /owncloud/themes/default folder. The next thing you should do, before starting any changes is: Make a backup of your current theme(s) e.g.: -* Goto …/owncloud/themes -* cp -r default default.old - -.. note:: In this example the theme name ``default`` is used because this is automatically loaded. This should be changed in the config file to avoid having this overwritten by the ownCloud package (see :ref:`notes-for-updates`). +* cd …/owncloud/themes +* cp -r example mytheme Creating and activating a new theme =================================== @@ -34,12 +31,12 @@ 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 and doing everything step by step and more experimentally +* 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" => ‘themename’, into the config.php file. -* make all changes in the /themes/default -file +* make all changes in the /themes/example or /themes/‘themename’ -folder Structure ========= @@ -47,8 +44,14 @@ Structure The folder structure of a theme is exactly the same as the main ownCloud 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. +override CSS properties. CSS files and the standard pictures that are used reside +for example in /owncloud/core/ and /owncloud/settings/ in these sub folders: +* css = style sheets +* js = JavaScripts +* img = images +* l10n = translation files +* templates = php and html template files How to change images and the logo ================================= @@ -164,7 +167,7 @@ How to change names, slogans and URLs The ownCloud 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. In there you need to specify a class named ``OC_Theme`` and need to implement the methods you want to overwrite: +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: .. code-block:: php From 5724c59933a038e879efe7561d69765c6410a63a Mon Sep 17 00:00:00 2001 From: Christian Ludwig Date: Thu, 15 Oct 2015 12:49:06 +0200 Subject: [PATCH 2/3] Changed notes for updates in theming.rst --- developer_manual/core/theming.rst | 78 ++++++++++++------------------- 1 file changed, 30 insertions(+), 48 deletions(-) diff --git a/developer_manual/core/theming.rst b/developer_manual/core/theming.rst index 0080a4604..c5c23b382 100644 --- a/developer_manual/core/theming.rst +++ b/developer_manual/core/theming.rst @@ -1,6 +1,5 @@ Theming ownCloud ================ - Themes can be used to customize the look and feel of ownCloud. Themes can relate to the following topics of owncloud: @@ -9,8 +8,9 @@ Themes can relate to the following topics of owncloud: 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: @@ -25,9 +25,9 @@ Make a backup of your current theme(s) e.g.: * cd …/owncloud/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 @@ -38,9 +38,9 @@ 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" => ‘themename’, into the config.php file. * make all changes in the /themes/example or /themes/‘themename’ -folder + Structure ========= - The folder structure of a theme is exactly the same as the main ownCloud 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 @@ -53,19 +53,38 @@ for example in /owncloud/core/ and /owncloud/settings/ in these sub folders: * l10n = translation files * templates = php and html template files +.. _notes-for-updates: + + +Notes for Updates +================= +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 ownCloud update process. + +During an update, files might get changed within the core an 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 +ownCloud 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 at least ownCloud aims to give further information in this case. + + How to change images and the logo ================================= - A new logo which you may want to insert can be added as follows: Figure out the path of the old logo ----------------------------------- - Replace the old picture, which position you found out as described under 1.3. by adding an extension in case you want to re-use it later. Creating an own logo -------------------- - If you want to do a quick exchange like (1) it's important to know the size of the picture before you start creating an own logo: * Go to the place in the filesystem, that has been shown by the web developer tool/s @@ -85,9 +104,8 @@ Just insert the new created picture by using the unchanged name of the old pictu 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 …/owncloud/themes/default/apps/activity/img/activity.svg -changing the default colours +Changing the default colours ---------------------------- - With a web-developer tool like Mozilla-Inspector, you also get easily displayed the color of the background you clicked on. On the top of the login page you can see a case- distinguished setting for different browsers: @@ -120,9 +138,9 @@ The other major color scheme is the blue header bar on the main navigation page This color we will change with the above as well. Save the file and refresh the browser for the changes to take effect. + How to change translations ========================== - .. versionadded 8.0 You can override the translation of single strings within your theme. Simply @@ -162,9 +180,9 @@ 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 change names, slogans and URLs ===================================== - The ownCloud 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: @@ -209,46 +227,10 @@ One exception is the method ``buildDocLinkToKey`` which gets passed in a key as return $this->getDocBaseUrl() . '/server/8.2/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. - - -.. _GitHub themes repository: https://github.com/owncloud/themes -.. _here: https://github.com/owncloud/themes/tree/master/example - -.. _notes-for-updates: - -Notes for Updates -================= - -In case of theming it is recommended to the user, -not to perform these adaptations inside the folder /themes/default. - -Please perform the following steps, to avoid conflicts with other upcoming updates: - -* create a new folder inside /themes: for example: /themes/MyTheme -* Copy the folders /themes/default/core and /themes/default/settings to /themes/MyTheme -* edit the file /config/config.php -* Insert: 'theme' => 'MyTheme', into this file - -Within the folder /themes/MyTheme all files, which are needed for theming -are save from coming updates. -All company theming must be done exclusively here from now on. - -In case, that one of the following files is affected due to an upgrade, - -* /themes/default/settings/templates/apps.php -* /themes/default/defaults.php - -the files listed below, have to be replaced by those listed above: - -* /themes/MyTheme/settings/templates/apps.php -* /themes/MyTheme/defaults.php - -But this is unlikely at least in the upcoming updates (5.0.x). -ownCloud aims to give further information in this case. From f7ab5ec4900c1f879ac0f6fe8792c651ae8796fb Mon Sep 17 00:00:00 2001 From: Christian Ludwig Date: Thu, 15 Oct 2015 13:41:09 +0200 Subject: [PATCH 3/3] Update theming.rst Highlight the changes that need to be done in config.php --- developer_manual/core/theming.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/developer_manual/core/theming.rst b/developer_manual/core/theming.rst index c5c23b382..4eb04ca2b 100644 --- a/developer_manual/core/theming.rst +++ b/developer_manual/core/theming.rst @@ -35,8 +35,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" => ‘themename’, into the config.php file. -* make all changes in the /themes/example or /themes/‘themename’ -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 Structure