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
Copy file name to clipboardExpand all lines: README.md
+2-26Lines changed: 2 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -31,32 +31,8 @@ _Note: You will need to use [Node](https://nodejs.org/en/) v.7 or higher._
31
31
32
32
## Support
33
33
34
-
Though we have tested and verified general usability within these frameworks, PFE makes no guarantees about compatibility within specific sites & applications. Please test accordingly.
Though we have tested and verified general usability within these frameworks, PFE makes no guarantees about compatibility within specific sites & applications. Please test accordingly. For more details, check out the [official status card per component](https://github.com/patternfly/patternfly-elements/issues?q=is%3Aopen+is%3Aissue+label%3A%22status+tracking+only%22) or visit the [status page on the documentation site](https://patternfly.github.io/patternfly-elements/getting-started/component-status/).
Check out the demo files within each component for examples of the attributes and possible variable overrides. The readme.md files within each component should have descriptions about the supported attributes & variables.
15
+
16
+
The list below is the recommended approach to using web components and overriding style properties, in order.
17
+
12
18
13
19
## 1. Install PatternFly Elements
14
20
15
21
16
-
Use [NPM](https://www.npmjs.com/) (Node Package Manager) to install the whole PatternFly Elements library or a handful of individual PatternFly Elements.
22
+
Use [NPM](https://www.npmjs.com/) (Node Package Manager) to install individual PatternFly Elements.
17
23
18
24
```bash
19
25
npm install --save @patternfly/pfe-card
26
+
npm install --save @patternfly/pfe-cta
20
27
```
21
28
22
-
Or, utilize the Red Hat asset library! When it exists!
23
29
30
+
## 2. Include PatternFly Elements JavaScript
24
31
25
-
26
-
## 2. Include PatternFly Elements on a page
27
-
28
-
You have some options:
32
+
There are a few options:
29
33
30
34
1. Load JavaScript modules via script tag: `script type="module"`
31
-
1. Downloads all of the dependencies on its own
32
-
2. [Only supported in modern browsers](https://caniuse.com/#search=module)
35
+
1. Downloads all of the dependencies on its own.
36
+
2. [Only supported in modern browsers](https://caniuse.com/#search=module).
33
37
2. Include the PatternFly Element and its dependencies on the page(s) or within the app.
34
38
35
39
```html
36
40
import '@patternfly/pfe-card/pfe-card.js';
37
41
import '@patternfly/pfe-cta/pfe-cta.js';
38
42
```
39
43
40
-
3. Use [require.js](https://requirejs.org/) JavaScript file and module loader
44
+
3. Use [require.js](https://requirejs.org/) JavaScript file and module loader.
41
45
- Learn more about [Polyfills](/getting-started/polyfills)
42
-
3. Load individual PatternFly Element scripts, but bundle the polyfills with the base `pfelement.js` file
43
-
1. All elements are based off of pfelement.js so including the polyfills with this one file would mean you only need to include the pfelement.js file before you include anything else
44
-
4. Bundle all of the scripts together into one
45
-
5. TBD Idea: polyfill.io > webservice (build something similar internal to Red Hat - component service)
46
-
1. pipe needed polyfills for website, checks headers, runtime
47
-
2. delivers dynamic JS
48
-
3. If I want pfe-card - it gets the pfe-card.js + required other files (serves up js bundle)
46
+
3. Load individual PatternFly Element scripts, but bundle the polyfills with the base `pfelement.js` file.
47
+
1. All elements are based off of pfelement.js so including the polyfills with this one file would mean you only need to include the pfelement.js file before you include anything else.
48
+
4. Bundle all of the scripts together into one rollup, and include that.
49
+
49
50
50
51
51
52
52
53
## 3. Use PatternFly Elements markup
53
54
54
-
You can use PatternFly Elements with other standard HTML markup in your app or page:
55
+
Different components have different intended uses. We tend to think of them in 3 distinct groups:
56
+
57
+
- Content, such as a call-to-action: `pfe-cta`
58
+
- Containers, such as a card: `pfe-card`
59
+
- Combos, such as the pattern which captures sets of content and renders it as an accordion or tab set: `pfe-content-set`
60
+
61
+
62
+
### Content Components
63
+
64
+
The beauty of web components is that they have much of the styling built-into the tag itself. Start with the tags first.
65
+
66
+
```
67
+
<body>
68
+
<pfe-cta>
69
+
<a href="#">Learn more</a>
70
+
</pfe-cta>
71
+
</body>
72
+
```
73
+
74
+
75
+
76
+
### Container components (see also container notes below)
77
+
78
+
```
79
+
<body>
80
+
<pfe-card pfe-color="darkest">
81
+
<p>Hello world.</p>
82
+
</pfe-card>
83
+
</body>
84
+
```
85
+
86
+
87
+
You can use PatternFly Elements alongside other standard HTML markup in your app or page. Here's a React app example:
55
88
56
89
```html
57
90
import React, { Component } from 'react';
@@ -73,12 +106,12 @@ class App extends Component {
73
106
</p>
74
107
<divclassName="body">
75
108
<pfe-card>
76
-
<h2slot="header">Default card</h2>
109
+
<h2slot="pfe-card--header">Default card</h2>
77
110
<p>This is the default pfe-card and <ahref="#">a link</a>.</p>
78
111
<p>Leverage agile frameworks to provide a robust synopsis for high level overviews. Iterative approaches to corporate strategy foster collaborative thinking to further the overall value proposition.</p>
79
112
<p>Organically grow the holistic world view of disruptive innovation via workplace diversity and empowerment.</p>
@@ -92,17 +125,142 @@ class App extends Component {
92
125
93
126
## 4. Add attributes
94
127
95
-
You may choose to add attributes such as `priority` or `color` as needed to adjust usage of palette color, context, or priority.
128
+
You may choose to add attributes such as `pfe-variant`, `pfe-priority` or `pfe-color` as needed to adjust usage of general theme, palette color, or priority. Check the readme file of a component to see what attributes are supported. Or check out the [Storybook](https://patternfly.github.io/patternfly-elements/demo) to preview how the attributes work.
Theme variables will impact all components on the page where this CSS is loaded.
170
+
171
+
172
+
```
173
+
// your-page.css
174
+
:root {
175
+
--pfe-theme--color--ui-accent: green;
176
+
--pfe-theme--color--surface--darker: navy;
177
+
}
105
178
```
106
179
107
180
181
+
_Note_: overriding local variables (i.e., --pfe-cta--foo) will not work at this level. Those overrides can only be done on the component via tag name, class, or ID.
108
182
183
+
184
+
#### Page-level CSS, component variables
185
+
186
+
187
+
```
188
+
/* your-page.css */
189
+
pfe-cta {
190
+
--pfe-cta--BackgroundColor: green;
191
+
}
192
+
pfe-band {
193
+
--pfe-band--Padding--vertical: 34px;
194
+
}
195
+
```
196
+
197
+
198
+
199
+
### Component-level inline CSS
200
+
201
+
As a last resort, you may choose to override variables with inline styles. This could be desirable if you only need one component to deviate from the design system. Note that this incurs some level of risk, especially related to colors, as you are opting out of the color combinations in the system.
202
+
203
+
204
+
```
205
+
<pfe-cta style="--pfe-cta--BackgroundColor:pink">
206
+
```
207
+
208
+
209
+
## 6. Victory!
210
+
211
+
Be sure to browser test within your own site or application. If you run into any trouble, please file an issue in the [issue queue](https://github.com/patternfly/patternfly-elements/issues).
212
+
213
+
<hr/>
214
+
215
+
216
+
## FAQ
217
+
218
+
### Should I use on=dark or color=darkest on my container? What's the difference?
219
+
220
+
*`on=dark` is being deprecated. Instead, custom classes already on the page should set broadcast values.
221
+
* The original goal for `on=dark` was all about context, but instead of having to provide another attribute somewhere, the card or a band or another container will inform any nested components that the text color needs to change through the set of broadcast variables. Existing broadcast vars (defined in `$BROADCAST-VARS`) include: `text`, `ui-link`, `ui-link--hover`, `ui-link--visited`, `ui-link--focus`.
222
+
* If your page has a custom background color for a band or card, you should set the background and also set the broadcast colors.
In themes (like the advanced-theme.css file from the Red Hat Theme ) we apply broadcast variables to plain links, because they are light DOM and also have default colors applied by the browser. This CSS file not only includes variables but also styles for headlines and links on the page. It sets the colors for these elements using a CSS variable, which web components can change the value of.
237
+
238
+
For example, advanced-theme.css includes:
239
+
240
+
```
241
+
.PFElement a {
242
+
color: var(--pfe-broadcasted--color--ui-link);
243
+
}
244
+
```
245
+
246
+
We choose not to apply broadcast colors to text elements like paragraphs because it still would not be high enough specificity to override anything coming from pre-existing stylesheets, and paragraphs will inherit color from parents.
247
+
248
+
249
+
```
250
+
// this would not really be helpful to add to cp-theme or redhat-theme
251
+
h1, h2, h3, h4, h5, h6, p {
252
+
color: var(--pfe-broadcasted--color--text);
253
+
}
254
+
// if there was some class like this in the theme, It would override it anyway.
description = "Status of each PatternFly Elements component"
4
+
weight = 1
5
+
draft = false
6
+
bref = ""
7
+
toc = true
8
+
menu = "start"
9
+
tags = [ "start" ]
10
+
+++
11
+
12
+
13
+
Though we have tested and verified general usability within these frameworks, PFE makes no guarantees about compatibility within specific sites & applications. Please test accordingly. For more details, check out the [official status card per component](https://github.com/patternfly/patternfly-elements/issues?q=is%3Aopen+is%3Aissue+label%3A%22status+tracking+only%22).
0 commit comments