From 3d9c02a1bb7b870d4a7b45c3cb2d283641535aec Mon Sep 17 00:00:00 2001 From: wxiaoguang Date: Mon, 6 Jun 2022 22:44:20 +0800 Subject: [PATCH] Update frontend guideline (#19901) * update frontend guideline * "Native" => "Vanilla JS", fix typo comma. Co-authored-by: Lunny Xiao --- .../doc/developers/guidelines-frontend.md | 32 ++++++++++++------- 1 file changed, 21 insertions(+), 11 deletions(-) diff --git a/docs/content/doc/developers/guidelines-frontend.md b/docs/content/doc/developers/guidelines-frontend.md index 01d44596b..0fced64b1 100644 --- a/docs/content/doc/developers/guidelines-frontend.md +++ b/docs/content/doc/developers/guidelines-frontend.md @@ -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: * **Less styles:** `web_src/less/` -* **Javascript files:** `web_src/js/` -* **Vue layouts:** `web_src/js/components/` -* **HTML templates:** `templates/` +* **JavaScript files:** `web_src/js/` +* **Vue components:** `web_src/js/components/` +* **Go HTML templates:** `templates/` ## 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. 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. -4. jQuery events across different features should use their own namespaces. -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. +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 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[]{}` 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 -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: -* Vue + Native +* Vue + Vanilla JS * Fomantic-UI (jQuery) -* Native only +* Vanilla JS Discouraged implementations: -* Vue + jQuery -* jQuery + Native +* Vue + Fomantic-UI (jQuery) +* 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 @@ -75,7 +80,8 @@ Some lint rules and IDEs also have warnings if the returned Promise is not handl ### 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: * `$.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. +### 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 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.