From 4f633caecad25cc13b18726d890f696bd4d12b20 Mon Sep 17 00:00:00 2001
From: Yarden Shoham <git@yardenshoham.com>
Date: Wed, 20 Nov 2024 17:28:40 +0000
Subject: [PATCH] Add comments and reduce abstraction levels

---
 models/repo/star.go          |  4 ++--
 models/repo/star_test.go     |  6 +++---
 routers/api/v1/repo/star.go  |  2 +-
 routers/web/repo/repo.go     |  5 ++++-
 routers/web/repo/view.go     | 32 ++++++++------------------------
 templates/repo/watchers.tmpl |  3 +++
 6 files changed, 21 insertions(+), 31 deletions(-)

diff --git a/models/repo/star.go b/models/repo/star.go
index 4c66855525..f734584f9a 100644
--- a/models/repo/star.go
+++ b/models/repo/star.go
@@ -76,8 +76,8 @@ func IsStaring(ctx context.Context, userID, repoID int64) bool {
 }
 
 // GetStargazers returns the users that starred the repo.
-func GetStargazers(ctx context.Context, repo *Repository, opts db.ListOptions) ([]*user_model.User, error) {
-	sess := db.GetEngine(ctx).Where("star.repo_id = ?", repo.ID).
+func GetStargazers(ctx context.Context, repoID int64, opts db.ListOptions) ([]*user_model.User, error) {
+	sess := db.GetEngine(ctx).Where("star.repo_id = ?", repoID).
 		Join("LEFT", "star", "`user`.id = star.uid")
 	if opts.Page > 0 {
 		sess = db.SetSessionPagination(sess, &opts)
diff --git a/models/repo/star_test.go b/models/repo/star_test.go
index aaac89d975..20fe82302a 100644
--- a/models/repo/star_test.go
+++ b/models/repo/star_test.go
@@ -39,7 +39,7 @@ func TestRepository_GetStargazers(t *testing.T) {
 	// repo with stargazers
 	assert.NoError(t, unittest.PrepareTestDatabase())
 	repo := unittest.AssertExistsAndLoadBean(t, &repo_model.Repository{ID: 4})
-	gazers, err := repo_model.GetStargazers(db.DefaultContext, repo, db.ListOptions{Page: 0})
+	gazers, err := repo_model.GetStargazers(db.DefaultContext, repo.ID, db.ListOptions{Page: 0})
 	assert.NoError(t, err)
 	if assert.Len(t, gazers, 1) {
 		assert.Equal(t, int64(2), gazers[0].ID)
@@ -50,7 +50,7 @@ func TestRepository_GetStargazers2(t *testing.T) {
 	// repo with stargazers
 	assert.NoError(t, unittest.PrepareTestDatabase())
 	repo := unittest.AssertExistsAndLoadBean(t, &repo_model.Repository{ID: 3})
-	gazers, err := repo_model.GetStargazers(db.DefaultContext, repo, db.ListOptions{Page: 0})
+	gazers, err := repo_model.GetStargazers(db.DefaultContext, repo.ID, db.ListOptions{Page: 0})
 	assert.NoError(t, err)
 	assert.Len(t, gazers, 0)
 }
@@ -69,7 +69,7 @@ func TestClearRepoStars(t *testing.T) {
 	assert.NoError(t, repo_model.ClearRepoStars(db.DefaultContext, repo.ID))
 	unittest.AssertNotExistsBean(t, &repo_model.Star{UID: user.ID, RepoID: repo.ID})
 
-	gazers, err := repo_model.GetStargazers(db.DefaultContext, repo, db.ListOptions{Page: 0})
+	gazers, err := repo_model.GetStargazers(db.DefaultContext, repo.ID, db.ListOptions{Page: 0})
 	assert.NoError(t, err)
 	assert.Len(t, gazers, 0)
 }
diff --git a/routers/api/v1/repo/star.go b/routers/api/v1/repo/star.go
index 99676de119..3e414322d3 100644
--- a/routers/api/v1/repo/star.go
+++ b/routers/api/v1/repo/star.go
@@ -45,7 +45,7 @@ func ListStargazers(ctx *context.APIContext) {
 	//   "404":
 	//     "$ref": "#/responses/notFound"
 
-	stargazers, err := repo_model.GetStargazers(ctx, ctx.Repo.Repository, utils.GetListOptions(ctx))
+	stargazers, err := repo_model.GetStargazers(ctx, ctx.Repo.Repository.ID, utils.GetListOptions(ctx))
 	if err != nil {
 		ctx.Error(http.StatusInternalServerError, "GetStargazers", err)
 		return
diff --git a/routers/web/repo/repo.go b/routers/web/repo/repo.go
index 9206f936f4..93a6261b38 100644
--- a/routers/web/repo/repo.go
+++ b/routers/web/repo/repo.go
@@ -352,7 +352,10 @@ func Action(ctx *context.Context) {
 		ctx.Data["IsStaringRepo"] = repo_model.IsStaring(ctx, ctx.Doer.ID, ctx.Repo.Repository.ID)
 	}
 
-	// if we have user cards on the page we should refresh them
+	// we send the HX-Trigger header to trigger the refreshCards event, when the frontend receives a request with this header
+	// htmx triggers all elements that have the attribute hx-trigger="refreshCards from:body". This attribute is usually placed
+	// on containers that show a list of either stargazers or watchers. For a demonstration of the effects see the pull
+	// request description of https://github.com/go-gitea/gitea/pull/32570.
 	ctx.RespHeader().Add("HX-Trigger", "refreshCards")
 
 	switch ctx.PathParam(":action") {
diff --git a/routers/web/repo/view.go b/routers/web/repo/view.go
index 6dad016bde..7cfaebb680 100644
--- a/routers/web/repo/view.go
+++ b/routers/web/repo/view.go
@@ -1102,7 +1102,9 @@ func checkOutdatedBranch(ctx *context.Context) {
 }
 
 // RenderUserCards render a page show users according the input template
-func RenderUserCards(ctx *context.Context, total int, getter func(opts db.ListOptions) ([]*user_model.User, error), tpl base.TplName) {
+func RenderUserCards(ctx *context.Context, pageType string, total int, getter func(goctx gocontext.Context, repoID int64, opts db.ListOptions) ([]*user_model.User, error), tpl base.TplName) {
+	ctx.Data["Title"] = ctx.Tr(pageType)
+	ctx.Data["CardsTitle"] = ctx.Tr(pageType)
 	page := ctx.FormInt("page")
 	if page <= 0 {
 		page = 1
@@ -1110,7 +1112,7 @@ func RenderUserCards(ctx *context.Context, total int, getter func(opts db.ListOp
 	pager := context.NewPagination(total, setting.ItemsPerPage, page, 5)
 	ctx.Data["Page"] = pager
 
-	items, err := getter(db.ListOptions{
+	items, err := getter(ctx, ctx.Repo.Repository.ID, db.ListOptions{
 		Page:     pager.Paginater.Current(),
 		PageSize: setting.ItemsPerPage,
 	})
@@ -1123,42 +1125,24 @@ func RenderUserCards(ctx *context.Context, total int, getter func(opts db.ListOp
 	ctx.HTML(http.StatusOK, tpl)
 }
 
-func renderUserList(ctx *context.Context, pageType string, total int, getter func(opts db.ListOptions) ([]*user_model.User, error), tpl base.TplName) {
-	ctx.Data["Title"] = ctx.Tr(pageType)
-	ctx.Data["CardsTitle"] = ctx.Tr(pageType)
-	RenderUserCards(ctx, total, getter, tpl)
-}
-
 // Watchers render repository's watch users
 func Watchers(ctx *context.Context) {
-	renderUserList(ctx, "repo.watchers", ctx.Repo.Repository.NumWatches,
-		func(opts db.ListOptions) ([]*user_model.User, error) {
-			return repo_model.GetRepoWatchers(ctx, ctx.Repo.Repository.ID, opts)
-		}, tplWatchers)
+	RenderUserCards(ctx, "repo.watchers", ctx.Repo.Repository.NumWatches, repo_model.GetRepoWatchers, tplWatchers)
 }
 
 // WatchersCards renders a repository's watchers user cards
 func WatchersCards(ctx *context.Context) {
-	renderUserList(ctx, "repo.watchers", ctx.Repo.Repository.NumWatches,
-		func(opts db.ListOptions) ([]*user_model.User, error) {
-			return repo_model.GetRepoWatchers(ctx, ctx.Repo.Repository.ID, opts)
-		}, tplCards)
+	RenderUserCards(ctx, "repo.watchers", ctx.Repo.Repository.NumWatches, repo_model.GetRepoWatchers, tplCards)
 }
 
 // Stars render repository's starred users
 func Stars(ctx *context.Context) {
-	renderUserList(ctx, "repo.stargazers", ctx.Repo.Repository.NumStars,
-		func(opts db.ListOptions) ([]*user_model.User, error) {
-			return repo_model.GetStargazers(ctx, ctx.Repo.Repository, opts)
-		}, tplWatchers)
+	RenderUserCards(ctx, "repo.stargazers", ctx.Repo.Repository.NumStars, repo_model.GetStargazers, tplWatchers)
 }
 
 // StarsCards renders a repository's stargazers user cards
 func StarsCards(ctx *context.Context) {
-	renderUserList(ctx, "repo.stargazers", ctx.Repo.Repository.NumStars,
-		func(opts db.ListOptions) ([]*user_model.User, error) {
-			return repo_model.GetStargazers(ctx, ctx.Repo.Repository, opts)
-		}, tplCards)
+	RenderUserCards(ctx, "repo.stargazers", ctx.Repo.Repository.NumStars, repo_model.GetStargazers, tplCards)
 }
 
 // Forks render repository's forked users
diff --git a/templates/repo/watchers.tmpl b/templates/repo/watchers.tmpl
index e7493deca4..829d75fc29 100644
--- a/templates/repo/watchers.tmpl
+++ b/templates/repo/watchers.tmpl
@@ -2,6 +2,9 @@
 <div role="main" aria-label="{{.Title}}" class="page-content repository watchers">
 	{{template "repo/header" .}}
 	<div class="no-loading-indicator tw-hidden"></div>
+	<!-- this element reloads its content with htmx as soon as a response from the backend
+	 includes the header "HX-Trigger: refreshCards". This usually happens when a user
+	 watched/unwatched/starred/unstarred and we want their user card to appear/disappear -->
 	<div
 		hx-trigger="refreshCards from:body"
 		hx-indicator=".no-loading-indicator"