Skip to content
This repository was archived by the owner on Oct 1, 2024. It is now read-only.

Commit 554c81e

Browse files
author
george
committed
documentation updates
1 parent 67d0699 commit 554c81e

File tree

6 files changed

+307
-135
lines changed

6 files changed

+307
-135
lines changed

‎app/docs/download.md‎

Lines changed: 22 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
There's three ways to grab Undernet for your project: CDN, NPM, or the raw source code.
22

3-
See related documentation to learn the coding patterns and API in the framework's [CSS](/docs/overview/cs) and [JavaScript](/docs/overview/javascript).
3+
See related documentation to learn the patterns and API in the framework's [CSS](/docs/overview/cs) and [JavaScript](/docs/overview/javascript).
44

55
## CDN (easiest)
66

7-
The quickest way to use Undernet is to link the bundled js and minified css using a CDN, such as [jsdelivr](https://jsdelivr.com). Note that this route doesn't allow you to customize the CSS like the other options.
7+
The quickest way to use Undernet is to link the bundled js and minified css using a CDN, such as [jsdelivr](https://jsdelivr.com). Note that this route doesn't allow you to customize the style. For that, refer to the
88

99
Include the link tag before your custom CSS, and the script tag at the end of your `<body>` content.
1010

@@ -34,6 +34,15 @@ Include the link tag before your custom CSS, and the script tag at the end of yo
3434
</html>
3535
```
3636

37+
Note that if you plan to link to and start Undernet via `<script>` tag, it's recommended to add an event listener for `DOMContentLoaded` to ensure the page is ready. Head over to the [JavaScript](/docs/overview/javascript) page to see more examples, including UI frameworks like React.
38+
39+
```html
40+
<script>
41+
// Undernet is now attached to the `window`
42+
if (document) document.addEventListener("DOMContentLoaded", Undernet.start)
43+
</script>
44+
```
45+
3746
## NPM or Yarn
3847

3948
You can also install and setup with npm or yarn.
@@ -48,13 +57,15 @@ $ npm install -D undernet
4857
$ yarn add -D undernet
4958
```
5059

51-
Note that Undernet uses global DOM variables such as `window`, `document`, and `navigator`, which can break server-side rendering. To avoid conflicts, component scripts internally check for these variables before execution. This should not affect SEO in any meaningful way as content isn't generated dynamically.
60+
Unlike if you use the CDN, the module _does not_ attach Undernet to the `window`.
61+
62+
Also, note that Undernet uses global DOM variables like `window` and `document`, which can break server-side rendering. To avoid conflicts, component scripts internally check before execution. This should not affect SEO in any meaningful way as content isn't generated dynamically with Undernet's component scripts.
5263

5364
### Sass
5465

55-
With NPM, you need to set up two files which import Undernet's Sass partials. In these examples, the Webpack shorthand `~` is used to access `node_modules`, but any tool will do.
66+
With NPM, you need to set up two files which import Undernet's Sass partials. In these examples, the Webpack shorthand `~` is used to access `node_modules` (it doesn't matter how you get the files, as long as they come from that folder).
5667

57-
The first file is your config, which will have Sass utilities including variables, functions, and mixins. This can be imported wherever you want, as many times as you need, to get access to those utilities.
68+
The first file is your config, which will have Sass helpers like variables, functions, and mixins. This can be imported wherever you want, as many times as you need, to get access to those utilities.
5869

5970
In your app, create a file called `_custom-config.scss` like so:
6071

@@ -65,9 +76,9 @@ In your app, create a file called `_custom-config.scss` like so:
6576
@import "~undernet/src/scss/utilities/mixins";
6677
```
6778

68-
Note the comment; you can insert or import your variable overrides before the original `config`.
79+
Note the comment; you can insert or import your variable overrides before the original `config` as all variables use the [Sass `!default` rule](https://sass-lang.com/documentation/variables#default-values).
6980

70-
The next file includes the base framework, including all elements, components, and class utilities you might need. **Only import this file once per page/global stylesheet**, otherwise you'll duplicate the selectors for each redundant import. Your app's Sass entry file is a good place to import it.
81+
The next file should import the core framework, including all elements, components, and class utilities (you can forego any components/elements that aren't relevant to you). **Only import this file once at the global level**, otherwise you'll duplicate the selectors for each redundant import. Your application's Sass entry file is a good place to import it.
7182

7283
Create a file called `_custom-undernet.scss` like so:
7384

@@ -95,12 +106,15 @@ Finally, import `custom-undernet.scss` to your app's Sass entry file, wherever t
95106
// all your other styles after
96107
```
97108

98-
... or link to the compiled CSS in your layout.
109+
... or link to the compiled CSS in your layout, before custom stylesheet links or style tags..
99110

100111
```html
101112
<link rel="stylesheet" ref="path/to/custom-undernet.css" />
113+
<!-- all your other stylesheets/style tags after -->
102114
```
103115

116+
If you used scopes, disregard the suggestion above about importing before all other styles.
117+
104118
## Source Files
105119

106120
Lastly, if you want to host the source files or minified versions diretly, you can do that too:
@@ -119,64 +133,5 @@ Going this route allows for far more customization. Use this option if you inten
119133
- SCSS: [Download](https://github.com/geotrev/undernet/raw/master/dist/undernet.scss.zip)
120134
- JS: [Download](https://github.com/geotrev/undernet/raw/master/dist/undernet.modules.js.zip)
121135

122-
Note that if you plan to start Undernet's JS inline via `<script>` tag, it's recommended to add an event listener for `DOMContentLoaded` to ensure the page is ready.
123-
124-
```html
125-
<script>
126-
if (document) document.addEventListener("DOMContentLoaded", Undernet.start)
127-
</script>
128-
```
129-
130-
Similarly, if you are in a UI framework such as React, the appropriate lifecycle method would be `componentDidMount`. If you take this route, be sure to tear down the events in the corresponding `componentWillUnmount`.
131-
132-
```js
133-
componentDidMount() {
134-
Undernet.start()
135-
}
136-
componentWillUnmount() {
137-
Undernet.stop()
138-
}
139-
```
140-
141-
In the case of React hooks, you can use `useState`:
142-
143-
```js
144-
const observedState = []
145-
const componentUnmountFn = Undernet.stop
146-
const componentMountFn = () => {
147-
Undernet.start()
148-
return componentUnmountFn
149-
}
150-
useEffect(componentMountFn, observedState)
151-
```
152-
153-
If you're using a framework to affect DOM state (including removing nodes from the DOM), you might want to be careful. Undernet isn't smart enough to know that your DOM changed, so you should "stop" right before changing state, and "start" once the DOM is rendered and ready again.
154-
155-
Let's look at a real world example, again using React hooks:
156-
157-
```js
158-
const [showSidebar, setShowSidebar] = useState(true)
159-
handleClick(e) {
160-
e.preventDefault()
161-
// stop accordions if sidebar is visible, right before we close it!
162-
if (showSidebar) {
163-
Accordion.stop(".sidebar-wrapper")
164-
}
165-
setShowSidebar(false)
166-
}
167-
useEffect(() => {
168-
// if sidebar has become visible, start accordions again
169-
if (showSidebar) {
170-
Accordion.start(".sidebar-wrapper")
171-
}
172-
}, [showSidebar])
173-
```
174-
175-
In this example, we have a `handleClick` function that is connected to a button to hide a sidebar containing an accordion.
176-
177-
We want to "stop" accordions from the DOM by checking if `showsidebar` is currently `true`, before `setShowSidebar` is called.
178-
179-
Then, to "start" accordions again, an effect is implemented re-checking `showSidebar`; if it's `true`, we know the sidebar has been re-expanded, so we can start them again.
180-
181136
---
182137
<p class="has-text-end">Is this article inaccurate? <a href="https://github.com/geotrev/undernet/tree/master/app/docs/download.md">Edit this page on Github!</a></p>

‎app/docs/introduction.md‎

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
Welcome! Undernet is a fully modular, highly configurable set of base CSS styles and interactive UI components. It's also responsive and internationalization-friendly for right-to-left languages.
1+
Welcome! Undernet is a fully modular, highly configurable set of base CSS styles and interactive UI components. It is responsive and automatically handles right-to-left languages with its styles and components.
22

33
The framework is extremely light, carrying no external dependencies. It's available via CDN, [NPM](https://www.npmjs.org/package/undernet), and as a raw download.
44

@@ -10,14 +10,14 @@ Undernet was created with the goal of simplifying the development experience, al
1010

1111
Over time, lots of new features have been added. These include lots of helper CSS classes and Sass utilities to empower developers in building their interfaces.
1212

13-
Undernet can both be a prototyping tool or the basis for your web app. You can easily pick and choose which elements and components to include, reducing the size of the overall bundle.
13+
Undernet can both be a prototyping tool _or_ the basis for your web app. You can easily pick and choose which elements and components to include, reducing the size of the overall bundle.
1414

1515
### Core Principles
1616

17-
- 🧩 **Configuration:** The framework comes with a configuration file enabling full brand control, from global to element-specific styling.
18-
- ♿ **Accessibility:** Accessibility is baked in to interactive components like dropdowns and modals, to ensure everyone can use your interface.
19-
- 📦 **Modularity:** Undernet can act independently from your core stylesheet and can be added to to existing projects using [scopes](/docs/overview/css).
20-
- 🚲 **Agility:** Installation options range from CDN to hosting the source files yourself.
17+
- 🧩 **Configurable:** The framework comes with a configuration file enabling full brand control, from global, to element, to component styling.
18+
- ♿ **Accessible:** Accessibility is baked into all facets of Underneet; theree's no excuse why everyone can't use your interface.
19+
- 📦 **Modular:** Undernet can act independently from your core stylesheet and be added to to existing projects using a style [scope](/docs/overview/css).
20+
- 🚲 **Flexible:** Installation options range from CDN to hosting the source files yourself.
2121

2222
### Support
2323

@@ -28,13 +28,12 @@ Undernet's CSS and JavaScript will work in _recent versions_ these browsers:
2828
- Safari ✓
2929
- Opera ✓
3030

31-
The framework is also tested in and supports **Internet Explorer 11** and **Edge** (non-chromium) on Windows. Support for IE11 and non-chromium Edge may drop in the near future as the new Edge is rolled out in 2020.
31+
The framework is also tested in and supports **Internet Explorer 11** and **Edge** on Windows. Support for IE11 and Edge may drop in the near future as chromium Edge is rolled out.
3232

3333
## Contribute
3434

35-
Undernet is completely [free and open source](https://en.wikipedia.org/wiki/Free_and_open-source_software)!
36-
37-
Contribute on [Github](https://www.github.com/geotrev/undernet/) if you have questions or a want to file a bug report. Be sure to [read about contributing](https://github.com/geotrev/undernet/blob/master/CONTRIBUTING.md) before filing a bug or pull request.
35+
Undernet supports a FOSS methodology ([free and open source](https://en.wikipedia.org/wiki/Free_and_open-source_software)). You can contribute on [Github](https://www.github.com/geotrev/undernet/) if you have questions or a want to file a bug report. Be sure to [read about contributing](https://github.com/geotrev/undernet/blob/master/CONTRIBUTING.md) before filing a bug or pull request.
3836

3937
---
38+
4039
<p class="has-text-end">Is this article inaccurate? <a href="https://github.com/geotrev/undernet/tree/master/app/docs/introduction.md">Edit this page on Github!</a></p>

0 commit comments

Comments
 (0)