TudbuT/forgejo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 4

Update frontend guideline (#19901)

Browse source 
* update frontend guideline

* "Native" => "Vanilla JS", fix typo comma.

Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
This commit is contained in:
wxiaoguang 2022-06-06 22:44:20 +08:00 committed by GitHub
parent c48706ecde
commit 3d9c02a1bb
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 21 additions and 11 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

32
docs/content/doc/developers/guidelines-frontend.md
View file

@ -27,9 +27,9 @@ The HTML pages are rendered by [Go HTML Template](https://pkg.go.dev/html/templa
The source files can be found in the following directories: The source files can be found in the following directories:
* **Less styles:** `web_src/less/` * **Less styles:** `web_src/less/`
* **Javascript files:** `web_src/js/` * **JavaScript files:** `web_src/js/`
* **Vue layouts:** `web_src/js/components/` * **Vue components:** `web_src/js/components/`
* **HTML templates:** `templates/` * **Go HTML templates:** `templates/`
## General Guidelines ## General Guidelines
@ -40,24 +40,29 @@ We recommend [Google HTML/CSS Style Guide](https://google.github.io/styleguide/h
1. Every feature (Fomantic-UI/jQuery module) should be put in separate files/directories. 1. Every feature (Fomantic-UI/jQuery module) should be put in separate files/directories.
2. HTML ids and classes should use kebab-case. 2. HTML ids and classes should use kebab-case.
3. HTML ids and classes used in JavaScript should be unique for the whole project, and should contain 2-3 feature related keywords. We recommend to use the `js-` prefix for classes that are only used in JavaScript. 3. HTML ids and classes used in JavaScript should be unique for the whole project, and should contain 2-3 feature related keywords. We recommend to use the `js-` prefix for classes that are only used in JavaScript.
4. jQuery events across different features should use their own namespaces. 4. jQuery events across different features could use their own namespaces if there are potential conflicts.
5. CSS styling for classes provided by frameworks should not be overwritten. Always use new class-names to overwrite framework styles. We recommend to use the `us-` prefix for user defined styles. 5. CSS styling for classes provided by frameworks should not be overwritten. Always use new class-names with 2-3 feature related keywords to overwrite framework styles.
6. The backend can pass complex data to the frontend by using `ctx.PageData["myModuleData"] = map[]{}` 6. The backend can pass complex data to the frontend by using `ctx.PageData["myModuleData"] = map[]{}`
7. Simple pages and SEO-related pages use Go HTML Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue2 (or Vue3 in future). 7. Simple pages and SEO-related pages use Go HTML Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue2 (or Vue3 in future).
### Framework Usage ### Framework Usage
Mixing different frameworks together is highly discouraged. A JavaScript module should follow one major framework and follow the framework's best practice. Mixing different frameworks together is discouraged, it makes the code difficult to be maintained.
A JavaScript module should follow one major framework and follow the framework's best practice.
Recommended implementations: Recommended implementations:
* Vue + Native * Vue + Vanilla JS
* Fomantic-UI (jQuery) * Fomantic-UI (jQuery)
* Native only * Vanilla JS
Discouraged implementations: Discouraged implementations:
* Vue + jQuery * Vue + Fomantic-UI (jQuery)
* jQuery + Native * jQuery + Vanilla JS
To make UI consistent, Vue components can use Fomantic-UI CSS classes.
Although mixing different frameworks is discouraged,
it should also work if the mixing is necessary and the code is well-designed and maintainable.
### `async` Functions ### `async` Functions
@ -75,7 +80,8 @@ Some lint rules and IDEs also have warnings if the returned Promise is not handl
### HTML Attributes and `dataset` ### HTML Attributes and `dataset`
We forbid `dataset` usage, its camel-casing behaviour makes it hard to grep for attributes. However there are still some special cases, so the current guideline is: The usage of `dataset` is forbidden, its camel-casing behaviour makes it hard to grep for attributes.
However, there are still some special cases, so the current guideline is:
* For legacy code: * For legacy code:
* `$.data()` should be refactored to `$.attr()`. * `$.data()` should be refactored to `$.attr()`.
@ -86,6 +92,10 @@ We forbid `dataset` usage, its camel-casing behaviour makes it hard to grep for
* never bind any user data to a DOM node, use a suitable design pattern to describe the relation between node and data. * never bind any user data to a DOM node, use a suitable design pattern to describe the relation between node and data.
### Legacy Code
A lot of legacy code already existed before this document's written. It's recommended to refactor legacy code to follow the guidelines.
### Vue2/Vue3 and JSX ### Vue2/Vue3 and JSX
Gitea is using Vue2 now, we plan to upgrade to Vue3. We decided not to introduce JSX to keep the HTML and the JavaScript code separated. Gitea is using Vue2 now, we plan to upgrade to Vue3. We decided not to introduce JSX to keep the HTML and the JavaScript code separated.