Refactor activity log doc

docs/activity-log.html

@@ -205,47 +205,47 @@
 <div id='docMainBox' class='px-16 pb-12 pt-4 overflow-auto'>
 <h1 class='mb-8'>Activity Log</h1>
 
-<div class='border-t'><p>As an admin user of CMS, You may need to record some important operations and these records should be easily queried and audited,
-so QOR5 provides a built-in activity module to record the operation of the model and support the following features:</p>
+<div class='border-t'><p>QOR5 provides a built-in activity module for recording model operations that may be important for admin users of CMS. These records are designed to be easily queried and audited, and the activity module supports the following features:</p>
 
 <ul>
-<li>Support recording very detailed changes when a model data is changed.</li>
-<li>Support adding ignore fields when diffing a modified data, such as the update time.</li>
-<li>Support customizing how to diff a complex field type, such as the time.Time type.</li>
-<li>Support customizing the keys to indentify the current model data.</li>
-<li>Support both automatic recording and manual recording the CRUD operation.</li>
-<li>Support customizing the action about what the current operation is.</li>
-<li>Support querying the activity log from admin page.</li>
+<li>Detailed change logging functionality for model data modifications.</li>
+<li>Allow certain fields to be ignored when comparing modified data, such as the update time.</li>
+<li>Customization of the diffing process for complex field types, like time.Time.</li>
+<li>Customization of the keys used to identify model data.</li>
+<li>Support both automatic and manual CRUD operation recording.</li>
+<li>Provide flexibility to customize the actions other than default CRUD.</li>
+<li>An page for querying the activity log via QOR5 admin</li>
 </ul>
-<h2><a name="initialize-the-activity" class="anchor" href="#initialize-the-activity" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
-Initialize the activity</h2>
+<h2><a name="initialize-the-activity-package" class="anchor" href="#initialize-the-activity-package" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
+Initialize the activity package</h2>
 
-<highlightjs :language='"go"' :code='"presetsBuilder := presets.New()\ndb, err := gorm.Open(sqlite.Open(\"/tmp/activity.db\"), \u0026gorm.Config{})\nif err != nil {\n\tpanic(err)\n}\nactivity.New(presetsBuilder, db)"'></highlightjs>
-<ul>
-<li>The above code will create a new activity instance with the default configuration.</li>
-<li>If you already have a key to fetch the current user from the context, you can use <code>SetCreatorContextKey</code> method to set it.</li>
-<li>If you want to fetch the DB from the context, you can use <code>SetDBContextKey</code> method to set it.</li>
-<li>If you want to customize the text that displayed on the model edit page, you can use <code>SetTabHeading</code> method to customized it.</li>
-</ul>
-<h2><a name="register-the-preset-models" class="anchor" href="#register-the-preset-models" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
-Register the preset models</h2>
+<p>To initialize activity package with the default configuration, you need to pass a <code>presets.Builder</code> instance and a database instance.</p>
 
-<highlightjs :language='"go"' :code='"presetsBuilder := presets.New()\ndb, err := gorm.Open(sqlite.Open(\"/tmp/activity.db\"), \u0026gorm.Config{})\nif err != nil {\n\tpanic(err)\n}\n\ntype Product struct {\n\tTitle string\n\tCode  string\n\tPrice float64\n}\n\nproductModel := presetsBuilder.Model(\u0026Product{})\nactivityBuilder := activity.New(presetsBuilder, db)\nactivityBuilder.RegisterModel(productModel).UseDefaultTab().AddKeys(\"Title\").AddIgnoredFields(\"Code\").SkipDelete()"'></highlightjs>
-<ul>
-<li>The above code will register the product model into activity and the product model will be recorded when it is created, updated or deleted automatically.</li>
-<li>By default, the activity will use the <code>primary</code> field as the key to indentify the current model data. You also can use <code>SetKeys</code> and <code>AddKeys</code> methods to customize the keys.</li>
-<li>By default, the activity will ignore the <code>ID</code>, <code>CreatedAt</code>, <code>UpdatedAt</code>, <code>DeletedAt</code> fields when diffing a modified data. You also can use <code>AddIgnoredFields</code> and <code>SetIgnoredFields</code> methods to customize the ignore fields.</li>
-<li>The activity already handle some special field types, such as the time.Time and media_library.MediaBox, you also can use <code>AddTypeHanders</code> methods to add more type handles.</li>
-<li>If you want to skip the automatic recording, you can use <code>SkipCreate</code>, <code>SkipUpdate</code> and <code>SkipDelete</code> methods to skip the automatic recording.</li>
-<li>If you want to display the related activity log on the model edit page, you can use <code>UseDefaultTab</code> method to enable it.</li>
-<li>If you want to display the link of which the model page is changed, you can use <code>SetLink</code> method to set it.</li>
-</ul>
+<highlightjs :language='"go"' :code='"presetsBuilder := presets.New()\ndb, err := gorm.Open(sqlite.Open(\"/tmp/activity.db\"), \u0026gorm.Config{})\nif err != nil {\n\tpanic(err)\n}\nactivityBuilder := activity.New(presetsBuilder, db)"'></highlightjs>
+<p>By default, the activity package uses QOR5 login package&#39;s <code>login.UserKey</code> as the default key to fetch the current user from the context. If you want to use your own key, you can use the <code>SetCreatorContextKey</code> function.</p>
+
+<p>Same with above, the activity package uses the db instance that passed in during initialization to perform db operations. If you need another db to do the work, you can use <code>SetDBContextKey</code> method.</p>
+<h2><a name="register-the-models-that-require-activity-tracking" class="anchor" href="#register-the-models-that-require-activity-tracking" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
+Register the models that require activity tracking</h2>
+
+<p>This example demonstrates how to register <code>Product</code> into the activity. The activities on the product model will be automatically recorded when it is created, updated, or deleted.</p>
+
+<highlightjs :language='"go"' :code='"type Product struct {\n\tTitle string\n\tCode  string\n\tPrice float64\n}\nproductModel := presetsBuilder.Model(\u0026Product{})\n\nactivityBuilder.RegisterModel(productModel).UseDefaultTab().AddKeys(\"Title\").AddIgnoredFields(\"Code\").SkipDelete()"'></highlightjs>
+<p>By default, the activity package will use the primary key as the key to indentify the current model data. You can use <code>SetKeys</code> and <code>AddKeys</code> methods to customize it.</p>
+
+<p>When diffing the modified data, the activity package will ignore the <code>ID</code>, <code>CreatedAt</code>, <code>UpdatedAt</code>, <code>DeletedAt</code> fields. You can either use <code>AddIgnoredFields</code> to append your own fields to the default ignored fields. Or <code>SetIgnoredFields</code> method to replace the default ignored fields.</p>
+
+<p>For special fields like <code>time.Time</code> or media files handled by QOR5 media_library, activity package already handled them. You can use <code>AddTypeHanders</code> method to handle your own field types.</p>
+
+<p>If you want to skip the automatic recording, you can use <code>SkipCreate</code>, <code>SkipUpdate</code> and <code>SkipDelete</code> methods.</p>
+
+<p>The Activity package allows for displaying the activities of a record on its editing page. Simply use the <code>EnableActivityInfoTab</code> method to enable this feature. Once enabled, you can customize the format of each activity&#39;s display text using the <code>SetTabHeading</code> method. Additionally, you can make each activity a link to the corresponding record using the <code>SetLink</code> method.</p>
 <h2><a name="record-the-activity-log-manually" class="anchor" href="#record-the-activity-log-manually" rel="nofollow" aria-hidden="true"><span class="octicon octicon-link"></span></a>
 Record the activity log manually</h2>
 
-<p>If you register a preset model into the activity, the activity will record the activity log automatically for the CRUD operation of the model. But if you want to record the activity log manually for some other operations or you want to register a model that is not a preset model, you can use the following sample to record the activity log manually.</p>
+<p>If you register a preset model into the activity, the activity package will automatically record the activity log for CRUD operations. However, if you need to manually record the activity log for other operations or if you want to register a non-preset model, you can use the following sample code.</p>
 
-<highlightjs :language='"go"' :code='"presetsBuilder := presets.New()\ndb, err := gorm.Open(sqlite.Open(\"/tmp/activity.db\"), \u0026gorm.Config{})\nif err != nil {\n\tpanic(err)\n}\n\ntype Product struct {\n\tTitle string\n\tCode  string\n\tPrice float64\n}\n\nactivityBuilder := activity.New(presetsBuilder, db)\nactivityBuilder.RegisterModel(\u0026Product{})\ncurrentCtx := context.WithValue(context.Background(), activity.CreatorContextKey, \"user1\")\nactivityBuilder.AddRecords(\"Publish\", currentCtx, \u0026Product{Title: \"Product 1\", Code: \"P1\", Price: 100}) // custmize the action name\nactivityBuilder.AddRecords(\"Update Price\", currentCtx, \u0026Product{Title: \"Product 1\", Code: \"P1\", Price: 200})\n"'></highlightjs>
+<highlightjs :language='"go"' :code='"currentCtx := context.WithValue(context.Background(), activity.CreatorContextKey, \"user1\")\n\nactivityBuilder.AddRecords(\"Publish\", currentCtx, \u0026Product{Title: \"Product 1\", Code: \"P1\", Price: 100})\n\nactivityBuilder.AddRecords(\"Update Price\", currentCtx, \u0026Product{Title: \"Product 1\", Code: \"P1\", Price: 200})"'></highlightjs>
 </div>
 </div>
 </div>

docsrc/content/basics/activity.go

@@ -8,40 +8,41 @@ import (
 
 var Activity = Doc(
 	Markdown(`
-As an admin user of CMS, You may need to record some important operations and these records should be easily queried and audited,
-so QOR5 provides a built-in activity module to record the operation of the model and support the following features:
-
-* Support recording very detailed changes when a model data is changed.
-* Support adding ignore fields when diffing a modified data, such as the update time.
-* Support customizing how to diff a complex field type, such as the time.Time type.
-* Support customizing the keys to indentify the current model data.
-* Support both automatic recording and manual recording the CRUD operation.
-* Support customizing the action about what the current operation is.
-* Support querying the activity log from admin page.
-
-## Initialize the activity
-	`),
+QOR5 provides a built-in activity module for recording model operations that may be important for admin users of CMS. These records are designed to be easily queried and audited, and the activity module supports the following features:
+
+* Detailed change logging functionality for model data modifications.
+* Allow certain fields to be ignored when comparing modified data, such as the update time.
+* Customization of the diffing process for complex field types, like time.Time.
+* Customization of the keys used to identify model data.
+* Support both automatic and manual CRUD operation recording.
+* Provide flexibility to customize the actions other than default CRUD.
+* An page for querying the activity log via QOR5 admin
+
+## Initialize the activity package
+To initialize activity package with the default configuration, you need to pass a ~presets.Builder~ instance and a database instance.
+`),
 	ch.Code(generated.NewActivitySample).Language("go"),
 	Markdown(`
-- The above code will create a new activity instance with the default configuration.
-- If you already have a key to fetch the current user from the context, you can use ~~~SetCreatorContextKey~~~ method to set it.
-- If you want to fetch the DB from the context, you can use ~~~SetDBContextKey~~~ method to set it.
-- If you want to customize the text that displayed on the model edit page, you can use ~~~SetTabHeading~~~ method to customized it.
+By default, the activity package uses QOR5 login package's ~~login.UserKey~~ as the default key to fetch the current user from the context. If you want to use your own key, you can use the ~~SetCreatorContextKey~~ function.
+
+Same with above, the activity package uses the db instance that passed in during initialization to perform db operations. If you need another db to do the work, you can use ~~SetDBContextKey~~ method.
 
-## Register the preset models
+## Register the models that require activity tracking
+This example demonstrates how to register ~~Product~~ into the activity. The activities on the product model will be automatically recorded when it is created, updated, or deleted.
 `),
 	ch.Code(generated.ActivityRegisterPresetsModelsSample).Language("go"),
 	Markdown(`
-- The above code will register the product model into activity and the product model will be recorded when it is created, updated or deleted automatically.
-- By default, the activity will use the ~~~primary~~~ field as the key to indentify the current model data. You also can use ~~~SetKeys~~~ and ~~~AddKeys~~~ methods to customize the keys.
-- By default, the activity will ignore the ~~~ID~~~, ~~~CreatedAt~~~, ~~~UpdatedAt~~~, ~~~DeletedAt~~~ fields when diffing a modified data. You also can use ~~~AddIgnoredFields~~~ and ~~~SetIgnoredFields~~~ methods to customize the ignore fields.
-- The activity already handle some special field types, such as the time.Time and media_library.MediaBox, you also can use ~~~AddTypeHanders~~~ methods to add more type handles.
-- If you want to skip the automatic recording, you can use ~~~SkipCreate~~~, ~~~SkipUpdate~~~ and ~~~SkipDelete~~~ methods to skip the automatic recording.
-- If you want to display the related activity log on the model edit page, you can use ~~~UseDefaultTab~~~ method to enable it.
-- If you want to display the link of which the model page is changed, you can use ~~~SetLink~~~ method to set it.
+By default, the activity package will use the primary key as the key to indentify the current model data. You can use ~~SetKeys~~ and ~~AddKeys~~ methods to customize it.
+
+When diffing the modified data, the activity package will ignore the ~~ID~~, ~~CreatedAt~~, ~~UpdatedAt~~, ~~DeletedAt~~ fields. You can either use ~~AddIgnoredFields~~ to append your own fields to the default ignored fields. Or ~~SetIgnoredFields~~ method to replace the default ignored fields.
+
+For special fields like ~~time.Time~~ or media files handled by QOR5 media_library, activity package already handled them. You can use ~~AddTypeHanders~~ method to handle your own field types.
+
+If you want to skip the automatic recording, you can use ~~SkipCreate~~, ~~SkipUpdate~~ and ~~SkipDelete~~ methods.
+
+The Activity package allows for displaying the activities of a record on its editing page. Simply use the ~~EnableActivityInfoTab~~ method to enable this feature. Once enabled, you can customize the format of each activity's display text using the ~~SetTabHeading~~ method. Additionally, you can make each activity a link to the corresponding record using the ~~SetLink~~ method.
 
 ## Record the activity log manually
-If you register a preset model into the activity, the activity will record the activity log automatically for the CRUD operation of the model. But if you want to record the activity log manually for some other operations or you want to register a model that is not a preset model, you can use the following sample to record the activity log manually.
-	`),
+If you register a preset model into the activity, the activity package will automatically record the activity log for CRUD operations. However, if you need to manually record the activity log for other operations or if you want to register a non-preset model, you can use the following sample code.`),
 	ch.Code(generated.ActivityRecordLogSample).Language("go"),
 ).Title("Activity Log")

docsrc/examples/e00_basics/activity.go

@@ -16,49 +16,25 @@ func NewActivitySample() {
 	if err != nil {
 		panic(err)
 	}
-	activity.New(presetsBuilder, db)
+	activityBuilder := activity.New(presetsBuilder, db)
 	// @snippet_end
-}
 
-func ActivityRegisterModelsSample() {
 	// @snippet_begin(ActivityRegisterPresetsModelsSample)
-	presetsBuilder := presets.New()
-	db, err := gorm.Open(sqlite.Open("/tmp/activity.db"), &gorm.Config{})
-	if err != nil {
-		panic(err)
-	}
-
 	type Product struct {
 		Title string
 		Code  string
 		Price float64
 	}
-
 	productModel := presetsBuilder.Model(&Product{})
-	activityBuilder := activity.New(presetsBuilder, db)
+
 	activityBuilder.RegisterModel(productModel).UseDefaultTab().AddKeys("Title").AddIgnoredFields("Code").SkipDelete()
 	// @snippet_end
-}
 
-func ActivityRecordLogSample() {
 	// @snippet_begin(ActivityRecordLogSample)
-	presetsBuilder := presets.New()
-	db, err := gorm.Open(sqlite.Open("/tmp/activity.db"), &gorm.Config{})
-	if err != nil {
-		panic(err)
-	}
+	currentCtx := context.WithValue(context.Background(), activity.CreatorContextKey, "user1")
 
-	type Product struct {
-		Title string
-		Code  string
-		Price float64
-	}
+	activityBuilder.AddRecords("Publish", currentCtx, &Product{Title: "Product 1", Code: "P1", Price: 100})
 
-	activityBuilder := activity.New(presetsBuilder, db)
-	activityBuilder.RegisterModel(&Product{})
-	currentCtx := context.WithValue(context.Background(), activity.CreatorContextKey, "user1")
-	activityBuilder.AddRecords("Publish", currentCtx, &Product{Title: "Product 1", Code: "P1", Price: 100}) // custmize the action name
 	activityBuilder.AddRecords("Update Price", currentCtx, &Product{Title: "Product 1", Code: "P1", Price: 200})
-
 	// @snippet_end
 }