mirror of
https://github.com/netbox-community/netbox.git
synced 2025-07-14 09:51:22 -06:00
Add UI development docs & update front-end scripts
This commit is contained in:
Matt
parent
a0ba8380c9
commit
c221b9b4d4
99
docs/development/web-ui.md
Normal file
99
docs/development/web-ui.md
Normal file
@ -0,0 +1,99 @@
|
|||||||
|
# Web UI Development
|
||||||
|
|
||||||
|
## Front End Technologies
|
||||||
|
|
||||||
|
The NetBox UI is built on languages and frameworks:
|
||||||
|
|
||||||
|
### Styling & HTML Elements
|
||||||
|
|
||||||
|
#### [Bootstrap](https://getbootstrap.com/) 5
|
||||||
|
|
||||||
|
The majority of the NetBox UI is made up of stock Bootstrap components, with some styling modifications and custom components added on an as-needed basis. Bootstrap uses [Sass](https://sass-lang.com/), and NetBox extends Bootstrap's core Sass files for theming and customization.
|
||||||
|
|
||||||
|
### Client-side Scripting
|
||||||
|
|
||||||
|
#### [TypeScript](https://www.typescriptlang.org/)
|
||||||
|
|
||||||
|
All client-side scripting is transpiled from TypeScript to JavaScript and served by Django. In development, TypeScript is an _extremely_ effective tool for accurately describing and checking the code, which leads to significantly fewer bugs, a better development experience, and more predictable/readable code.
|
||||||
|
|
||||||
|
As part of the [bundling](#bundling) process, Bootstrap's JavaScript plugins are imported and bundled alongside NetBox's front-end code.
|
||||||
|
|
||||||
|
!!! danger "NetBox is jQuery-free"
|
||||||
|
Following the Bootstrap team's deprecation of jQuery in Bootstrap 5, NetBox also no longer uses jQuery in front-end code.
|
||||||
|
|
||||||
|
## Guidance
|
||||||
|
|
||||||
|
NetBox generally follows the following guidelines for front-end code:
|
||||||
|
|
||||||
|
- Bootstrap utility classes may be used to solve one-off issues or to implement singular components, as long as the class list does not exceed 4-5 classes. If an element needs more than 5 utility classes, a custom SCSS class should be added that contains the required style properties.
|
||||||
|
- Custom classes must be commented, explaining the general purpose of the class and where it is used.
|
||||||
|
- Reuse SCSS variables whenever possible. CSS values should (almost) never be hard-coded.
|
||||||
|
- All TypeScript functions must have, at a minimum, a basic [JSDoc](https://jsdoc.app/) description of what the function is for and where it is used. If possible, document all function arguments via [`@param` JSDoc block tags](https://jsdoc.app/tags-param.html).
|
||||||
|
- Expanding on NetBox's [dependency policy](style-guide.md#introducing-new-dependencies), new front-end dependencies should be avoided unless absolutely necessary. Every new front-end dependency adds to the CSS/JavaScript file size that must be loaded by the client and this should be minimized as much as possible. If adding a new dependency is unavoidable, use a tool like [Bundlephobia](https://bundlephobia.com/) to ensure the smallest possible library is used.
|
||||||
|
- All UI elements must be usable on all common screen sizes, including mobile devices. Be sure to test newly implemented solutions (JavaScript included) on as many screen sizes and device types as possible.
|
||||||
|
- NetBox aligns with Bootstrap's [supported Browsers and Devices](https://getbootstrap.com/docs/5.1/getting-started/browsers-devices/) list.
|
||||||
|
|
||||||
|
## UI Development
|
||||||
|
|
||||||
|
To contribute to the NetBox UI, you'll need to review the main [Getting Started guide](getting-started.md) in order to set up your base environment.
|
||||||
|
|
||||||
|
### Tools
|
||||||
|
|
||||||
|
Once you have a working NetBox development environment, you'll need to install a few more tools to work with the NetBox UI:
|
||||||
|
|
||||||
|
- [NodeJS](https://nodejs.org/en/download/) (the LTS release should suffice)
|
||||||
|
- [Yarn](https://yarnpkg.com/getting-started/install) (version 1)
|
||||||
|
|
||||||
|
After Node and Yarn are installed on your system, you'll need to install all the NetBox UI dependencies:
|
||||||
|
|
||||||
|
```console
|
||||||
|
$ cd netbox/project-static
|
||||||
|
$ yarn
|
||||||
|
```
|
||||||
|
|
||||||
|
!!! warning "Check Your Working Directory"
|
||||||
|
You need to be in the `netbox/project-static` directory to run the below `yarn` commands.
|
||||||
|
|
||||||
|
### Bundling
|
||||||
|
|
||||||
|
In order for the TypeScript and Sass (SCSS) source files to be usable by a browser, they must first be transpiled (TypeScript → JavaScript, Sass → CSS), bundled, and minified. After making changes to TypeScript or Sass source files, run `yarn bundle`.
|
||||||
|
|
||||||
|
`yarn bundle` is a wrapper around the following subcommands, any of which can be run individually:
|
||||||
|
|
||||||
|
| Command | Action |
|
||||||
|
| :-------------------- | :---------------------------------------------- |
|
||||||
|
| `yarn bundle` | Bundle TypeScript and Sass (SCSS) source files. |
|
||||||
|
| `yarn bundle:styles` | Bundle Sass (SCSS) source files only. |
|
||||||
|
| `yarn bundle:scripts` | Bundle TypeScript source files only. |
|
||||||
|
|
||||||
|
All output files will be written to `netbox/project-static/dist`, where Django will pick them up when `manage.py collectstatic` is run.
|
||||||
|
|
||||||
|
!!! info "Remember to re-run `manage.py collectstatic`"
|
||||||
|
If you're running the development web server — `manage.py runserver` — you'll need to run `manage.py collectstatic` to see your changes.
|
||||||
|
|
||||||
|
### Linting, Formatting & Type Checking
|
||||||
|
|
||||||
|
Before committing any changes to TypeScript files, and periodically throughout the development process, you should run `yarn validate` to catch formatting, code quality, or type errors.
|
||||||
|
|
||||||
|
!!! tip "IDE Integrations"
|
||||||
|
If you're using an IDE, it is strongly recommended to install [ESLint](https://eslint.org/docs/user-guide/integrations), [TypeScript](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Editor-Support), and [Prettier](https://prettier.io/docs/en/editors.html) integrations, if available. Most of them will automatically check and/or correct issues in the code as you develop, which can significantly increase your productivity as a contributor.
|
||||||
|
|
||||||
|
`yarn validate` is a wrapper around the following subcommands, any of which can be run individually:
|
||||||
|
|
||||||
|
| Command | Action |
|
||||||
|
| :--------------------------------- | :--------------------------------------------------------------- |
|
||||||
|
| `yarn validate` | Run all validation. |
|
||||||
|
| `yarn validate:lint` | Validate TypeScript code via [ESLint](https://eslint.org/) only. |
|
||||||
|
| `yarn validate:types` | Validate TypeScript code compilation only. |
|
||||||
|
| `yarn validate:formatting` | Validate code formatting of JavaScript & Sass/SCSS files. |
|
||||||
|
| `yarn validate:formatting:styles` | Validate code formatting Sass/SCSS only. |
|
||||||
|
| `yarn validate:formatting:scripts` | Validate code formatting TypeScript only. |
|
||||||
|
|
||||||
|
You can also run the following commands to automatically fix formatting issues:
|
||||||
|
|
||||||
|
| Command | Action |
|
||||||
|
| :-------------------- | :---------------------------------------------- |
|
||||||
|
| `yarn format` | Format TypeScript and Sass (SCSS) source files. |
|
||||||
|
| `yarn format:styles` | Format Sass (SCSS) source files only. |
|
||||||
|
| `yarn format:scripts` | Format TypeScript source files only. |
|
||||||
|
|
||||||
@ -103,6 +103,7 @@ nav:
|
|||||||
- Signals: 'development/signals.md'
|
- Signals: 'development/signals.md'
|
||||||
- Application Registry: 'development/application-registry.md'
|
- Application Registry: 'development/application-registry.md'
|
||||||
- User Preferences: 'development/user-preferences.md'
|
- User Preferences: 'development/user-preferences.md'
|
||||||
|
- Web UI: 'development/web-ui.md'
|
||||||
- Release Checklist: 'development/release-checklist.md'
|
- Release Checklist: 'development/release-checklist.md'
|
||||||
- Release Notes:
|
- Release Notes:
|
||||||
- Version 3.0: 'release-notes/version-3.0.md'
|
- Version 3.0: 'release-notes/version-3.0.md'
|
||||||
|
|||||||
@ -1,85 +0,0 @@
|
|||||||
<div style="align:center;">
|
|
||||||
<h1>NetBox UI Development</h1>
|
|
||||||
</div>
|
|
||||||
|
|
||||||
## Introduction
|
|
||||||
|
|
||||||
The following tools and languages are used during the **build** process:
|
|
||||||
|
|
||||||
### Languages
|
|
||||||
#### [Sass](https://sass-lang.com/)
|
|
||||||
|
|
||||||
Sass is similar to CSS, but has variables, functions, utilities, mixins, and other nice syntax additions. With Sass, we can import Bootstrap's Sass files, override or extend variables, and add classes of our own using Bootstrap's variables (as well as other CSS libraries used).
|
|
||||||
|
|
||||||
#### [TypeScript](https://www.typescriptlang.org/)
|
|
||||||
|
|
||||||
TypeScript is a strict static-typed superset of JavaScript. In development, it's an _extremely_ effective tool for accurately describing and checking the code, which leads to significantly fewer bugs, a better development experience, and more predictable/readable code.
|
|
||||||
|
|
||||||
### Tools
|
|
||||||
|
|
||||||
#### [esbuild](https://esbuild.github.io/)
|
|
||||||
|
|
||||||
esbuild is a bundling tool that takes given input files of most front-end languages (Sass and TypeScript, in our case), follows each of their dependencies (via import statements), and bundles them into a single minified file.
|
|
||||||
|
|
||||||
For JavaScript, every `.ts` file in `netbox/project-static/src` is:
|
|
||||||
|
|
||||||
1. Transpiled from TypeScript to JavaScript
|
|
||||||
2. Minified
|
|
||||||
3. Combined into a single output file at `netbox/project-static/dist/netbox.js` (this includes any dependant libraries imported in a file)
|
|
||||||
|
|
||||||
Likewise, with Sass, every `.scss` file in `netbox/project-static/styles` is:
|
|
||||||
|
|
||||||
1. Transpiled from Sass to CSS
|
|
||||||
2. Minified
|
|
||||||
3. Combined into a single output file at `netbox/project-static/dist/netbox.css` (this includes any dependant libraries imported in file)
|
|
||||||
|
|
||||||
For pre v4 releases, this process will be run in development, and the files in `netbox/project-static/dist` checked into change control. This is because running Parcel (and installing dependencies via NPM/Yarn, as described below) requires other system dependencies like NodeJS and Yarn, which aren't part of the current v2 dependency list.
|
|
||||||
|
|
||||||
#### [Yarn](https://yarnpkg.com/)
|
|
||||||
|
|
||||||
Yarn is a package manager (think `pip` in the Python world) for JavaScript packages on the [NPM](https://www.npmjs.com/) registry (think PyPI in the Python world). Technically, one could simply use NPM's own `npm` tool as well, however, `yarn` is widely used because it tends to be significantly faster than `npm` (and has other cool features, which we aren't using in NetBox).
|
|
||||||
|
|
||||||
### Installation
|
|
||||||
|
|
||||||
#### NodeJS
|
|
||||||
|
|
||||||
If you don't already have it, install [NodeJS](https://nodejs.org/en/download/) (the LTS release should be fine).
|
|
||||||
|
|
||||||
#### Yarn
|
|
||||||
|
|
||||||
Next, install [Yarn](https://yarnpkg.com/getting-started/install):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
npm install -g yarn
|
|
||||||
```
|
|
||||||
|
|
||||||
#### NetBox Dependencies
|
|
||||||
|
|
||||||
From `netbox/project-static`, run the command `yarn` — this will install all production and development dependencies to `netbox/project-static/node_modules`.
|
|
||||||
|
|
||||||
### Creating dist files
|
|
||||||
|
|
||||||
After any changes to TypeScript or Sass files, you'll need to recompile/bundle the dist files.
|
|
||||||
|
|
||||||
To bundle only CSS files, run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# netbox/project-static
|
|
||||||
yarn bundle:styles
|
|
||||||
```
|
|
||||||
|
|
||||||
To bundle only JS files, run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# netbox/project-static
|
|
||||||
yarn bundle:scripts
|
|
||||||
```
|
|
||||||
|
|
||||||
Or, to bundle both, run:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# netbox/project-static
|
|
||||||
yarn bundle
|
|
||||||
```
|
|
||||||
|
|
||||||
_**Note:** if you're running the development web server_ — `manage.py runserver` — _you'll need to run_ `manage.py collectstatic` _to see your changes._
|
|
||||||
@ -11,7 +11,15 @@
|
|||||||
"bundle": "node bundle.js",
|
"bundle": "node bundle.js",
|
||||||
"bundle:styles": "node bundle.js --styles",
|
"bundle:styles": "node bundle.js --styles",
|
||||||
"bundle:scripts": "node bundle.js --scripts",
|
"bundle:scripts": "node bundle.js --scripts",
|
||||||
"typecheck": "tsc --noEmit"
|
"format": "yarn format:scripts && yarn format:styles",
|
||||||
|
"format:scripts": "prettier -w src/**/*.ts",
|
||||||
|
"format:styles": "prettier -w styles/**/*.scss",
|
||||||
|
"validate": "yarn validate:types && yarn validate:lint",
|
||||||
|
"validate:lint": "eslint -c .eslintrc ./src/**/*.ts",
|
||||||
|
"validate:types": "tsc --noEmit",
|
||||||
|
"validate:formatting": "yarn validate:formatting:scripts && yarn validate:formatting:styles",
|
||||||
|
"validate:formatting:styles": "prettier -c styles/**/*.scss",
|
||||||
|
"validate:formatting:scripts": "prettier -c src/**/*.ts"
|
||||||
},
|
},
|
||||||
"dependencies": {
|
"dependencies": {
|
||||||
"@mdi/font": "^5.9.55",
|
"@mdi/font": "^5.9.55",
|
||||||
@ -45,36 +53,6 @@
|
|||||||
"eslint-plugin-prettier": "^3.3.1",
|
"eslint-plugin-prettier": "^3.3.1",
|
||||||
"prettier": "^2.2.1",
|
"prettier": "^2.2.1",
|
||||||
"prettier-eslint": "^12.0.0",
|
"prettier-eslint": "^12.0.0",
|
||||||
"stylelint": "^13.13.1",
|
|
||||||
"stylelint-config-twbs-bootstrap": "^2.2.3",
|
|
||||||
"typescript": "^4.2.3"
|
"typescript": "^4.2.3"
|
||||||
},
|
|
||||||
"stylelint": {
|
|
||||||
"extends": "stylelint-config-twbs-bootstrap/scss",
|
|
||||||
"rules": {
|
|
||||||
"selector-max-class": 16,
|
|
||||||
"selector-max-id": 4,
|
|
||||||
"selector-max-type": 16,
|
|
||||||
"selector-max-compound-selectors": 16,
|
|
||||||
"declaration-no-important": null,
|
|
||||||
"selector-max-universal": 4,
|
|
||||||
"selector-no-qualifying-type": [
|
|
||||||
true,
|
|
||||||
{
|
|
||||||
"ignore": [
|
|
||||||
"attribute",
|
|
||||||
"class"
|
|
||||||
]
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"number-leading-zero": "always",
|
|
||||||
"string-quotes": "single",
|
|
||||||
"selector-pseudo-element-colon-notation": "single",
|
|
||||||
"declaration-property-value-disallowed-list": {
|
|
||||||
"border": "none",
|
|
||||||
"outline": "none"
|
|
||||||
},
|
|
||||||
"scss/selector-no-union-class-name": true
|
|
||||||
}
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user