forgejo-domi/docs/content/doc/developers/guidelines-frontend.md

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 Vue2 for its frontend.

The HTML pages are rendered by Go Text Template

General Guidelines

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

Guidelines specialized for Gitea:

1. Every feature (Fomantic-UI/jQuery module) should be put in separated files/directories.
2. HTML id/css-class-name should use kebab-case.
3. HTML id/css-class-name used by JavaScript top-level selector should be unique in whole project, and should contain 2-3 feature related keywords. Recommend to use js- prefix for CSS names for JavaScript usage only.
4. jQuery events across different features should use their own namespaces.
5. CSS styles provided by frameworks should not be overwritten by framework's selectors globally. Always use new defined CSS names to overwrite framework styles. Recommend to use us- prefix for user defined styles.
6. Backend can pass data to frontend (JavaScript) by ctx.PageData["myModuleData"] = map{}
7. Simple pages and SEO-related pages use Go Text Template render to generate static Fomantic-UI HTML output. Complex pages can use Vue2 (or Vue3 in future).

Legacy Problems and Solutions

Too many codes in web_src/index.js

In history, many JavaScript codes are written into web_src/index.js directly, which becomes too big to maintain. We should split this file into small modules, the separated files can be put in web_src/js/features for the first step.

Vue2/Vue3 and JSX

Gitea is using Vue2 now, we have plan to upgrade to Vue3. We decide not to introduce JSX now to make sure the HTML and JavaScript codes are not mixed together.