Skip to content

Commit e71e005

Browse files
jarrodekjarrodek
committed
Docs: Updating documentation for theming.
1 parent 495876d commit e71e005

File tree

8 files changed

+128
-62
lines changed

8 files changed

+128
-62
lines changed

‎docs/images/styling-devtools-selection.png‎

21.1 KB
Loading

‎docs/images/styling-doc.png‎

57.2 KB
Loading

‎docs/images/styling-docs-catalog.png‎

95.5 KB
Loading

‎docs/images/styling-source-component.png‎

43.8 KB
Loading

‎docs/images/styling-title-highlighted.png‎

14.1 KB
Loading

‎docs/method-title-source.png‎

-55.3 KB
Binary file not shown.

‎docs/method-title.png‎

-40.6 KB
Binary file not shown.

‎docs/theming.md‎

Lines changed: 128 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,102 +1,168 @@
11
# Styling the API Console
22

3-
Theming is based on [CSS variables] and CSS mixins. Basic concepts of using the variables and mixins are described in [Polymer 2.0 styling] documentation.
3+
## Before you begin
44

5-
The CSS mixins are not standardized and therefore require additional libraries for support. Polymer has its own implementation of CSS mixins.
5+
You should know concept of [shadow DOM][]. Also be familiar with [CSS variables][] and CSS mixins. Basic concepts of using the variables and mixins are described in [Polymer 2.0 styling][] documentation.
66

7-
## Basics
7+
This document won't explain how styling web components work. It describes what has to be done to customize styling of API console.
88

9-
Basic theme is defined in the [api-console-styles.html](../api-console-styles.html) file. This file contains many CSS variables and mixins definitions.
9+
## Theme file
1010

11-
Each of these definitions is used to style one of the elements for building the API console. The many elements that contain a UI accept, or have their own, variables / mixins that are applied to element's internal content.
11+
API console has it's styles defined in shadow DOM of element and in API console own theme file.
12+
The [default theme][] is a seperate component which can be used alongside the `api-console` element
13+
to style the console.
1214

13-
For example `--raml-path-selector-background-color` variable is accepted by the `raml-path-selector` element (main navigation element) and applied to the element's background color.
15+
Our [build tools][] automatically include default theme element to the compiled bundle. However you can instruct the build tools to use other than default file (by adding `--theme-file` option).
1416

15-
Consequently, theming is possible for encapsulated web components. Also, most of the variables have an element name prefix for better understanding of where a given variable / mixin is applied.
17+
Note that default theme includes `paper-styles/default-theme.html` which is material design default theme for Google's Paper Elements.
1618

17-
To start creating your own theme you should be familiar with [ARC elements catalog](https://elements.advancedrestclient.com/). It contains all web components used to build API console plus documentation and a styling guide for all components.
19+
## Including theme file
1820

19-
## Identifying styles
21+
By default API console do not include any theme file. It makes it easier to work with theming.
2022

21-
Assume you'd like to change a style for the title of the HTTP method in the documentation:
23+
When developing theme for API console create a demo page that includes API console (source and AMF model) and add reference to your theme file.
2224

23-
![Documentation > HTTP method > title](method-title.png "Title of the HTTP method")
25+
Assume the following structure of your theme project:
2426

25-
Identify the custom element that contains this title. Use the Chrome DevTools inspector, or an equivalent tool, to inspect the title element.
27+
```
28+
-api-console-acme-theme
29+
|-bower_components
30+
|-README.md
31+
|-index.html
32+
|-api-console-acme-theme.html
33+
|-bower.json
34+
```
35+
36+
Then your index.html file would look like:
37+
38+
```html
39+
<!doctype html>
40+
<html>
41+
<head>
42+
<meta charset="utf-8">
43+
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
44+
<meta name="viewport" content="width=device-width, minimum-scale=1.0, initial-scale=1, user-scalable=yes">
45+
<title>API Console Acme Theme Demo</title>
46+
<script src="bower_components/webcomponentsjs/webcomponents-loader.js"></script>
47+
<link rel="import" href="bower_components/api-console/api-console.html">
48+
<link rel="import" href="api-console-acme-theme.html">
49+
</head>
50+
<body>
51+
<api-console></api-console>
52+
</body>
53+
</html>
54+
```
55+
56+
And finally your `api-console-acme-theme.html` file:
57+
58+
```html
59+
<custom-style>
60+
<style>
61+
:root {
62+
/* Style definition goes here */
63+
}
64+
</style>
65+
</custom-style>
66+
```
67+
68+
This setup allows you to start developing your own theme for API console.
2669

27-
![Source of: Documentation > HTTP method > title](method-title-source.png "Source code of the title of the HTTP method")
70+
For an example of such setup take a look into our [demo page][]. It contains complete example of adding API console, theme file and other components required for the console to work as a standalone application.
71+
It also contains an example of how to use AMF models.
2872

29-
You see the title is hosted by the `<raml-docs-method-viewer>` element that can be found in the catalog at https://elements.advancedrestclient.com/elements/raml-docs-method-viewer. In the documentation for this element, you see that there are three methods for styling this element:
73+
## Developing theme
3074

31-
- `--raml-docs-h1` mixin
32-
- `--raml-docs-method-viewer-title-method-font-weight` variable
33-
- `--arc-font-headline` mixin
75+
### Typography
3476

35-
Setting any of these properties in your own style definition alters the element styles. You can use the more general `--arc-font-headline` mixin that is applied to any headline (h1) elements in the console. Or, you can use the more specific `--raml-docs-h1` that is applied to all `<h1>`'s in the documentation pages.
77+
The ARC components typography is based on couple of CSS mixins. They are used in every component.
78+
The whole typography is defined in the following mixins:
3679

3780
```css
38-
:root {
39-
--raml-docs-h1: {
40-
color: red;
41-
};
42-
}
81+
/* Common properties */
82+
--arc-font-common-base: {
83+
/* Base font definition */
84+
};
85+
--arc-font-common-code: {
86+
/* Base font definition for code block */
87+
};
88+
--arc-font-common-nowrap: {
89+
/* No wrapping text definition */
90+
};
91+
/* Styles for common objects */
92+
--arc-font-display1: {
93+
@apply --arc-font-common-base;
94+
};
95+
--arc-font-headline: {
96+
};
97+
--arc-font-title: {
98+
};
99+
--arc-font-subhead: {
100+
};
101+
--arc-font-body2: {
102+
};
103+
--arc-font-body1: {
104+
};
105+
--arc-font-caption: {
106+
};
107+
--select-text: {
108+
};
43109
```
44110

45-
Repeat this style for any part of API Console you like.
111+
See [default theme][] for an example with values.
46112

47-
## Including custom styles into the console
113+
### Styles
48114

49-
Currently the only way to apply a custom stylesheet in the console is to replace
50-
the original theme file. There are various ways to perform this replacement, depending on how you use the API Console.
115+
First thing you need to do is to identify the style (variable or mixin) you'd like to change.
51116

52-
If you work on a clone or fork of the repository, you can alter the `api-console-styles.html` file directly.
53117

54-
If you request the `api-console` as a bower component, you have to replace the style file manually each time you update bower components, or you can automate this task.
118+
Let's say you are about to style HTTP method documentation page which normally look like this:
55119

56-
To automate this task, first create the `.bowerrc` file in your project directory where you keep the `bower.json` file. Add the following code to the file:
120+
![Page: Documentation > HTTP method](images/styling-doc.png "HTTP method documentation with default theme")
57121

58-
```json
59-
{
60-
"scripts": {
61-
"postinstall": "node update-styles.js"
62-
}
63-
}
64-
```
122+
To change URL section styles you would have to open Developer Tools (usually it's F12) and select the element.
65123

66-
This code runs the `update-styles.js` script in the node each time components are installed or updated.
124+
![Page: Documentation > HTTP method, highlighted URL section](images/styling-title-highlighted.png "HTTP method documentation with selected URL section in dev tools")
67125

68-
Next, create the `update-styles.js` file with the following content:
126+
Identify the custom element that contains this section. Walk up in the DOM tree until you see a custom element (an element that is not standard DOM element).
127+
You can recognize those as an element that has `shadow-root` node.
69128

70-
```javascript
71-
const fs = require('fs');
129+
![Source of: Documentation > HTTP method > title](images/styling-devtools-selection.png "Source code of the title of the HTTP method")
72130

73-
const sourceStyles = 'api-console-styles.html';
74-
const destinationStyles = 'bower_components/api-console/api-console-styles.html';
131+
In this case it is `api-method-documentation`.
75132

76-
fs.readFile(sourceStyles, 'utf8', (err, data) => {
77-
if (err) {
78-
console.error(err);
79-
process.exit(1);
80-
return;
81-
}
82-
fs.writeFile(destinationStyles, data, 'utf8', (err) => {
83-
console.error(err);
84-
process.exit(1);
85-
return;
86-
});
87-
console.log('API Console styles updated.');
88-
});
133+
#### Webcomponents.org
134+
135+
First option is to check documentaiton page of the component at [webcomponents.org](https://webcomponents.org) website. Go directly to component's page which is [https://www.webcomponents.org/element/advanced-rest-client/api-method-documentation](https://www.webcomponents.org/element/advanced-rest-client/api-method-documentation).
136+
For any other element just append its name to `https://www.webcomponents.org/element/advanced-rest-client/`.
137+
(note that `paper-*`, `iron-*`, and `app-*` elements have different URLs as they are not part of API components ecosystem but you can use search option to find them).
138+
139+
Most of the components contains styling section in the documentaiton page. Find the mixin you are looking for and use it for styling.
140+
141+
![Webcomponent.org documentation page](images/styling-docs-catalog.png "Webcomponent.org documentation page with styling documentation")
142+
143+
Using this documentation you can find the following definitions to style the element:
144+
145+
```css
146+
:root {
147+
--api-method-documentation-url-font-size: 14px;
148+
--api-method-documentation-url-background-color: red;
149+
--api-method-documentation-url-font-color: yellow;
150+
}
89151
```
90152

91-
This code just copies contents from `sourceStyles` file to `destinationStyles` file.
153+
#### GitHub
154+
155+
If you cannot find styles documentation for the element it means either you cannot style this particular element (there's no API for this in component's definition) or part of documentation is missing.
156+
To be sure you can check component's source which is located at [https://github.com/advanced-rest-client/api-method-documentation](https://github.com/advanced-rest-client/api-method-documentation).
157+
In the source code you can read which variables or mixins are applied to particular element:
92158

93-
## Sizing the embeddable element
159+
![Component source code](images/styling-source-component.png "Component's source view of styling")
94160

95-
The `api-console` must either be explicitly sized, or contained by an explicitly
96-
sized parent. The parent container also has to be positioned relatively
97-
(`position: relative` CSS property). "Explicitly sized" means the container either has an explicit CSS height property set via a class or inline style, or the size is
98-
set by the layout in some other way, such as the flex layout or absolute positioning.
161+
If you can't style an element in a way you like you can always fork the component, change it's styling by adding new variable/mixin and send a PR to us. If the change make sense then it will be included into the component library.
99162

100163
[CSS variables]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables
101164
[Polymer 2.0 styling]: https://www.polymer-project.org/1.0/docs/devguide/styling
102165
[build tools]: build-tools.md
166+
[shadow DOM]: https://developers.google.com/web/fundamentals/web-components/shadowdom
167+
[default theme]: https://github.com/advanced-rest-client/api-console-default-theme
168+
[demo page]: ../demo/standalone/

0 commit comments

Comments
 (0)