You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
:description: Introducing skin creation, less and icon modification.
5
-
:keywords: create, creator, skin, icon
1
+
= Create a Skin for {productname}
2
+
:navtitle: Create a Skin
3
+
:description_short: Introduction to skin creation.
4
+
:description: Learn how to create a custom skin, modify Less variables, and update icons for {productname}.
5
+
:keywords: create, skin, customization, icon, Less
6
6
7
-
This section provides information on how to manually create a new skin to customize the appearance of {productname}{productmajorversion}.
8
-
9
-
The {productname} Skin Tool provides an interactive method for designing and creating a skin for {productname}, visit: http://skin.tiny.cloud/[http://skin.tiny.cloud/].
7
+
This guide explains how to manually create a new skin to customize the appearance of {productname}{productmajorversion}.
10
8
11
9
== Prerequisites
12
10
13
-
This guide assumes:
11
+
Before beginning, ensure that:
14
12
15
-
* Familiarity with the command line and running simple commands.
16
-
* https://nodejs.org/en/[Node.js], https://yarnpkg.com/en/[Yarn] and https://gulpjs.com[Gulp] are already installed.
17
-
* Basic understanding of http://lesscss.org[Less], the CSS preprocessor we use to build the skins. More specifically, http://lesscss.org/features/#variables-feature[read the section about variables].
13
+
* Familiarity with the command line and basic commands is established.
14
+
* link:https://nodejs.org/en/[Node.js], link:https://yarnpkg.com/en/[Yarn], and link:https://gulpjs.com[Gulp] are already installed.
15
+
* A basic understanding of link:http://lesscss.org[Less], the CSS preprocessor used to build skins, is acquired. Specifically, review the link:http://lesscss.org/features/#variables-feature[section on variables].
18
16
19
17
== Preparation
20
18
21
-
The CSS that goes with a theme is called a skin. The default skin for {productname} {productmajorversion} is named Oxide and is written in http://lesscss.org[Less], a popular CSS preprocessor. With Oxide we introduced a concept we call the *Style API*. This API consists of around 300 variables which you use to modify the appearance of {productname}. You never touch the underlying CSS. The benefit of this approach is that improvements we make to the CSS and HTML won't break your custom skin. This also means that if things don't work as expected, we can provide support and bug fixes, something that was virtually impossible before.
19
+
The CSS associated with a theme is called a skin. The default skin for {productname} {productmajorversion} is **Oxide**, written in link:http://lesscss.org[Less]. Oxide introduces the *Style API*, which consists of approximately 300 variables that allow customization of {productname} without modifying the underlying CSS. This approach ensures compatibility with future updates and provides continued support for bug fixes.
22
20
23
-
IMPORTANT: We do not recommend modifying or overriding CSS rules directly.
21
+
[IMPORTANT]
22
+
Do not modify or overriding CSS rules directly.
24
23
25
-
To set up the skin development environment, begin with the following steps:
24
+
Follow these steps to set up the skin development environment:
26
25
27
-
. Download (or `+git clone+`) the https://github.com/tinymce/tinymce[{productname} source code].
28
-
. Open the terminal and navigate to the folder you just downloaded.
29
-
. Install dependencies with the command:
26
+
. Download (or `+git clone+`) the link:https://github.com/tinymce/tinymce[{productname} source code].
27
+
. Open a terminal and navigate to the folder you just downloaded.
28
+
. Install dependencies and build the project using the following commands:
30
29
+
31
30
[source,sh]
32
31
----
33
-
yarn install
32
+
yarn && yarn dev && yarn build
34
33
----
35
-
. Launch the web server to preview the skins using the command:
34
+
. Start the development server to preview skins:
36
35
+
37
36
[source,sh]
38
37
----
39
38
yarn oxide-start
40
39
----
40
+
. Once the server starts, open a browser and navigate to the displayed URL, typically `+http://localhost:3000+`.
41
41
42
-
You should now be able to open a web browser and point it to the url displayed in the terminal, usually `+http://localhost:3000+`.
43
-
44
-
The development environment is set up and ready to work.
42
+
The development environment is now setup and should look similar to the following:
45
43
46
44
image::SDK-for-silver.png[{productname} skin SDK for Silver theme]
47
45
48
-
If you just need to build the skins without launching a web server, run:
46
+
[NOTE]
47
+
If required to modify the skin without launching a web server, run `+yarn oxide-build+` instead of `+yarn oxide-start+`.
49
48
50
-
[source,sh]
51
-
----
52
-
yarn oxide-build
53
-
----
49
+
== Creating or Editing a Skin
54
50
55
-
== Making or editing a skin
51
+
Ensure completion of the preparation steps before proceeding.
56
52
57
-
Make sure you have performed the preparation steps above.
53
+
=== Directory Structure
58
54
59
-
=== Overview
55
+
Navigate to `+modules/oxide/src/less/skins/+`. This folder contains:
60
56
61
-
Navigate to `+modules/oxide/src/less/skins/+`. There are two folders in this location:
57
+
. `+/ui+`: Contains editor UI skins. The main file here is `+skin.less+`.
58
+
. `+/content+`: Contains skins for the content inside the editor.
62
59
63
-
* `+/ui+` - which is the skins for the editor. The important file here is `+skin.less+`.
64
-
* `+/content+` - which is the skins for the content within the editor.
60
+
The `+modules/oxide/src/less/theme/+` folder contains Less files defining global styles. Most files list available variables at the top, such as colors, margins, and fonts. Variables are prefixed with `@` (e.g., `@background-color`).
65
61
66
-
The folder `+modules/oxide/src/less/theme/+` contains the Less files. At the top of most files you'll find the available variables that defines the default colors, margins, fonts etc (variables are the strings that starts with an at-character, for example `+@background-color+`). _Do not edit these files_, instead use them as a reference when creating your skin. We recommend starting with the two files containing global variables: `+modules/oxide/src/less/theme/globals/global-variables.less+` and the toolbar buttons: `+modules/oxide/src/less/theme/components/toolbar-button/toolbar-button.less+`.
62
+
[IMPORTANT]
63
+
====
64
+
_Do not edit these files directly_. Instead, use them as references when creating a custom skin. Start by reviewing:
67
65
68
-
The general workflow is that you look inside the less files within the theme folder and copy the variables you like to change into your skin's `+skin.less+` file.
NOTE: The skin *only* changes the visual presentation of the UI and *not* the placement of elements. Placement of elements is done by the {productname} UI framework. This framework makes it possible to do complex UI layouts on all browsers without touching any CSS when plugins are created.
69
+
The typical workflow involves copying variables from the theme folder into the skins `skin.less` file and modifying them as needed.
70
+
====
71
71
72
-
[[creating-a-skin]]
73
-
=== Creating a skin
72
+
[NOTE]
73
+
Skins **only** affect the visual appearance of the UI. Element positioning is managed by {productname}'s UI framework.
74
74
75
-
. Begin by duplicating the `+default+` folder located in `+modules/oxide/src/less/skins/ui/+` and rename it to the name of your skin.
76
-
. Start the development server using the terminal command `+yarn oxide-start+`. If you already have the server running, you need to restart it to make it recognize your new skin using `+ctrl-c+` and then start it again.
77
-
. Open the file `+modules/oxide/src/less/skin/ui/<your-skin-name>/skin.less+`.
78
-
. Open any less file located in the theme folder, for example `+modules/oxide/src/less/theme/globals/global-variables.less+` and copy a variable you like to change, it's easiest to copy the whole line. Let's copy the `+@background-color+` variable to start with.
79
-
. Paste the variable into the `+skin.less+` file you opened in step 2. For a striking look, change the variable value to be red, like this: `+@background-color: red;+`. Then save the file.
75
+
[[creating-a-skin]]
76
+
=== Creating a Skin
80
77
81
-
Your skin.less file should now look like this:
78
+
. Duplicate the `+default+` folder in `+modules/oxide/src/less/skins/ui/+` and rename it.
79
+
. Rebuild the project to recognize the newly created skins by running:
80
+
+
81
+
[source,sh]
82
+
----
83
+
yarn build
84
+
----
85
+
. Start the development server by running:
86
+
+
87
+
[source,sh]
88
+
----
89
+
yarn oxide-start
90
+
----
91
+
+
92
+
[TIP]
93
+
If the server is already running, restart it (`+Ctrl+C+`) and run the command again.
82
94
95
+
. Open `+modules/oxide/src/less/skin/ui/<your-skin-name>/skin.less+`.
96
+
. Open a Less file from the theme folder (e.g., `+modules/oxide/src/less/theme/globals/global-variables.less+`) and copy a variable to modify. For example:
97
+
+
98
+
[source,less]
99
+
----
100
+
@background-color: red;
101
+
----
102
+
. Paste the variable into the `skin.less` file.
103
+
+
104
+
The updated `skin.less` should look like this:
105
+
+
83
106
[source,less]
84
107
----
85
108
@import 'src/less/theme/theme';
@@ -90,30 +113,60 @@ Your skin.less file should now look like this:
90
113
91
114
@background-color: red;
92
115
----
116
+
+
117
+
. Save the file and check the changes in a browser. Select the skin from the _Skin menu_.
118
+
. The editor should now display with a red background.
119
+
120
+
image::SDK-for-silver-custom-example.png[{productname} Skin SDK for the Silver theme]
93
121
94
-
Switch to the web browser. Select your skin from the _Skin menu_. It should show a fiery red editor
122
+
This method allows customization of {productname} by modifying predefined variables, such as toolbar spacing or letter spacing.
95
123
96
-
image::SDK-for-silver-custom-example.png[{productname} skin SDK for Silver theme]
124
+
[TIP]
125
+
Adjust {productname} configurations in `+modules/oxide/src/demo/index.html+` to match specific use cases.
97
126
98
-
This is how you skin {productname}: copy variables from the files in the theme folder and paste them into your skin file. There are variables for most things, like spacing between toolbar buttons to letter spacing. Simple yet powerful.
127
+
== Creating a Content CSS File
99
128
100
-
TIP: You can change the {productname} config in `+modules/oxide/src/demo/index.html+` to suit your particular use case.
129
+
To modify the appearance of content inside the editor (e.g., headings, lists, quotes), create a content CSS file:
101
130
102
-
== Creating a content CSS file
131
+
. Create a folder in `+modules/oxide/src/less/skins/content/+` and add a `content.less` file. Alternatively, duplicate an existing content CSS file.
132
+
. Rebuild the project to recognize the newly created content skin.
133
+
+
134
+
[source,sh]
135
+
----
136
+
yarn build
137
+
----
138
+
. Start the development server:
139
+
+
140
+
[source,sh]
141
+
----
142
+
yarn oxide-start
143
+
----
144
+
+
145
+
[TIP]
146
+
If the server is already running, restart it (`+Ctrl+C+`) and run the command again.
103
147
104
-
To update the appearance of the content within the editor, such as headings, quotes, lists, etc... you create a content css. These are located in `+modules/oxide/src/less/skin/content/+`
148
+
. Add styles for relevant elements (`h1` to `h6`, `a`, `blockquote`, `code`, `table`, etc.). For example:
149
+
+
150
+
[source,less]
151
+
----
152
+
h1 {
153
+
color: red;
154
+
}
155
+
----
156
+
+
157
+
. Save the file and check the changes in a browser.
158
+
. The editor should now display with red headings.
105
159
106
-
. Create a folder in `+modules/oxide/src/less/skins/content/+` and create a `+content.less+` file in it. Alternatively, you can duplicate any of the existing content css.
107
-
. Start the development server using the terminal command yarn oxide-start. If you already have the server running, you need to restart it to make it recognize your new skin using ctrl-c and then start it again.
108
-
. Add the relevant element selectors for the desired use case such as `+h1+` to `+h6+`, `+a+`, `+blockquote+`, `+code+`, `+table+`, etc...
160
+
== Moving the Skin into {productname}
109
161
110
-
== Moving the skin into TinyMCE
162
+
. Copy the skin and/or content CSS from `+modules/oxide/build/skins/+` to the appropriate folders in the production {productname} setup.
163
+
. Update {productname}'s initialization options:
111
164
112
-
. Copy the skin and/or content CSS from `+modules/oxide/build/skins/+` to the corresponding folders in your production {productname} folder.
113
-
. Update the {productname} init function with the xref:editor-skin.adoc#skin[skin] option and/or the xref:add-css-options.adoc#content_css[content_css] option.
165
+
* Use the xref:editor-skin.adoc#skin[skin] option for UI skins.
166
+
* Use the xref:add-css-options.adoc#content_css[content_css] option for content styles.
114
167
115
-
For more information on how to specify the location of the skin file, see xref:editor-skin.adoc#skin_url[this] section.
168
+
For details on specifying the skin file location, see xref:editor-skin.adoc#skin_url[this section].
116
169
117
-
== Modifying the icons
170
+
== Modifying Icons
118
171
119
-
For information on adding custom icons, see: xref:creating-an-icon-pack.adoc[Create an icon pack for {productname}].
172
+
For details on adding custom icons, see: xref:creating-an-icon-pack.adoc[Create an Icon Pack for {productname}].
Copy file name to clipboardExpand all lines: modules/ROOT/pages/customize-ui.adoc
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -35,7 +35,7 @@ tinymce.init({
35
35
});
36
36
----
37
37
38
-
To create a skin interactively, visit http://skin.tiny.cloud/t5/[the {productname} 6 Skin Tool]. For information on manually creating skins for {productname}, see xref:creating-a-skin.adoc[Creating a skin].
38
+
For information on manually creating skins for {productname}, see xref:creating-a-skin.adoc[Creating a skin].
39
39
40
40
NOTE: Developers often confuse the difference between {productname} "themes" and "skins". A *Skin* in {productname} is used to make changes to the appearance of the editor, for example, colors, margins, padding, fonts, icons, etc. A *Theme* creates the editor construction (left, top, bottom, or right of the editing area - vertical or horizontal, inline or outside, etc.). A skin usually changes the color scheme of a button, dialog, etc. while the theme applies to the whole editor including its functionality and has child skins to change the appearance.
0 commit comments