gitea/docs/content/doc/developers/guidelines-frontend.en-us.md
wxiaoguang 21a1d76911
Improve the frontend guideline (#23298)
### The CustomEvent prefix

There was already `ce-quick-submit`, the `ce-` prefix seems better than
`us-`. Rename the only `us-` prefixed `us-load-context-popup` to `ce-`
prefixed.

### Styles and Attributes in Go HTML Template

https://github.com/go-gitea/gitea/pull/21855#issuecomment-1429643073

Suggest to stick to `class="c1 {{if $var}}c2{{end}}"`

The readability and maintainability should be applied to the code which
is read by developers, but not for the generated outputs.

The template code is the code for developers, while the generated HTML
are only for browsers.

The `class="c1 {{if $var}}c2{{end}}"` style is clearer for developers
and more intuitive, and the generated HTML also makes browsers happy (a
few spaces do not affect anything)

Think about a more complex case:

* `class="{{if $active}}active{{end}} menu item {{if $show}}show{{end}}
{{if $warn}}warn{{end}}"`
* --vs--
* `class="{{if $active}}active {{end}}menu item{{if $show}}
show{{end}}{{if $warn}} warn{{end}}"`

The first style make it clearer to see each CSS class name with its
`{{if}}` block.

Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
2023-03-05 22:23:42 +08:00

5.8 KiB

date title slug weight toc draft menu
2021-10-13T16:00:00+02:00 Guidelines for Frontend Development guidelines-frontend 20 false false
sidebar
parent name weight identifier
developers Guidelines for Frontend 20 guidelines-frontend

Guidelines for Frontend Development

Table of Contents

{{< toc >}}

Background

Gitea uses Less CSS, Fomantic-UI (based on jQuery) and Vue3 for its frontend.

The HTML pages are rendered by Go HTML Template.

The source files can be found in the following directories:

  • Less styles: web_src/less/
  • JavaScript files: web_src/js/
  • Vue components: web_src/js/components/
  • Go HTML templates: templates/

General Guidelines

We recommend Google HTML/CSS Style Guide and Google JavaScript Style Guide

Gitea specific guidelines:

  1. Every feature (Fomantic-UI/jQuery module) should be put in separate files/directories.
  2. HTML ids and classes should use kebab-case, it's preferred to contain 2-3 feature related keywords.
  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. 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. Gitea's helper CSS classes in helpers.less could be helpful.
  5. The backend can pass complex data to the frontend by using ctx.PageData["myModuleData"] = map[]{}, but do not expose whole models to the frontend to avoid leaking sensitive data.
  6. Simple pages and SEO-related pages use Go HTML Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue3.
  7. Clarify variable types, prefer elem.disabled = true instead of elem.setAttribute('disabled', 'anything'), prefer $el.prop('checked', var === 'yes') instead of $el.prop('checked', var).
  8. Use semantic elements, prefer <button class="ui button"> instead of <div class="ui button">.
  9. Avoid unnecessary !important in CSS, add comments to explain why it's necessary if it can't be avoided.
  10. Avoid mixing different events in one event listener, prefer to use individual event listeners for every event.
  11. Custom event names are recommended to use ce- prefix.

Accessibility / ARIA

In history, Gitea heavily uses Fomantic UI which is not an accessibility-friendly framework. Gitea uses some patches to make Fomantic UI more accessible (see the aria.js and aria.md), but there are still many problems which need a lot of work and time to fix.

Framework Usage

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 + Vanilla JS
  • Fomantic-UI (jQuery)
  • Vanilla JS

Discouraged implementations:

  • 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

Only mark a function as async if and only if there are await calls or Promise returns inside the function.

It's not recommended to use async event listeners, which may lead to problems. The reason is that the code after await is executed outside the event dispatch. Reference: https://github.com/github/eslint-plugin-github/blob/main/docs/rules/async-preventdefault.md

If an event listener must be async, the e.preventDefault() should be before any await, it's recommended to put it at the beginning of the function.

If we want to call an async function in a non-async context, it's recommended to use const _promise = asyncFoo() to tell readers that this is done by purpose, we want to call the async function and ignore the Promise. Some lint rules and IDEs also have warnings if the returned Promise is not handled.

HTML Attributes and dataset

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().
    • $.data() can be used to bind some non-string data to elements in rare cases, but it is highly discouraged.
  • For new code:

    • node.dataset should not be used, use node.getAttribute instead.
    • never bind any user data to a DOM node, use a suitable design pattern to describe the relation between node and data.

Show/Hide Elements

  • Vue components are recommended to use v-if and v-show to show/hide elements.
  • Go template code should use Gitea's .gt-hidden and showElem()/hideElem()/toggleElem(), see more details in .gt-hidden's comment.

Styles and Attributes in Go HTML Template

It's recommended to use:

<div class="gt-name1 gt-name2 {{if .IsFoo}}gt-foo{{end}}" {{if .IsFoo}}data-foo{{end}}></div>

instead of:

<div class="gt-name1 gt-name2{{if .IsFoo}} gt-foo{{end}}"{{if .IsFoo}} data-foo{{end}}></div>

to make the code more readable.

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.

Vue3 and JSX

Gitea is using Vue3 now. We decided not to introduce JSX to keep the HTML and the JavaScript code separated.