views

type AttachRequestLayer ¶

type AttachRequestLayer struct{}

AttachRequestLayer injects the *http.Request context as "$request", the raw query parameter map as "$get", and the current Unix microseconds timestamp as "$timestamp". It is registered globally inside lamu.StartServer.

func (AttachRequestLayer) Next(next http.Handler) http.Handler

type ContextNilPointerValueError ¶ added in v0.6.18

type ContextNilPointerValueError[K any] struct {
	Key K
}

func (e ContextNilPointerValueError[K]) Error() string

type ContextTypeMismatchError ¶ added in v0.6.18

type ContextTypeMismatchError[V any] struct {
	Value any
}

func (e ContextTypeMismatchError[V]) Error() string

type FormPatcher ¶

type FormPatcher interface {
	// Patch performs modifications on form data values and validation errors, returning the altered maps.
	Patch(view View, r *http.Request, formData map[string]any, formErrors map[string]error) (map[string]any, map[string]error)
}

FormPatcher defines an interface for components capable of modifying form values and validation errors. It is applied during form submission flows to run hooks, inject defaults, or inject custom validations.

Use Cases:

• Injecting session data (e.g. current user ID) into submitted form maps.
• Performing cross-field validations and appending custom validation errors.
• Hashing sensitive inputs (e.g. passwords) before storage persistence.

Example:

type AuthorPatcher struct{}

func (p AuthorPatcher) Patch(view views.View, r *http.Request, formData map[string]any, formErrors map[string]error) (map[string]any, map[string]error) {
	formData["author_id"] = GetUserIDFromSession(r)
	return formData, formErrors
}

type FormPatchers ¶

type FormPatchers []registry.Pair[string, FormPatcher]

FormPatchers represents an ordered sequence of FormPatcher registry pairs.

func (f FormPatchers) Apply(view View, r *http.Request, values map[string]any, errors map[string]error) (map[string]any, map[string]error)

type GlobalLayer ¶

type GlobalLayer interface {
	// Next wraps the global HTTP handler.
	Next(http.Handler) http.Handler
}

GlobalLayer defines a global HTTP middleware layer that wraps the base server route multiplexer.

type Layer ¶

type Layer interface {
	// Next wraps the next handler in the view request execution chain.
	Next(View, http.Handler) http.Handler
}

Layer defines a view-specific middleware execution layer. It wraps an HTTP handler chain to inspect, modify, or intercept HTTP requests.

Use Cases:

• Parsing view-specific parameters (e.g. path values) or checking custom access policies.
• Injecting telemetry hooks or headers targeting individual views.

Example:

type HeaderInjectorLayer struct{}

func (l HeaderInjectorLayer) Next(view views.View, next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		w.Header().Set("X-Custom-View-Header", "Lamu")
		next.ServeHTTP(w, r)
	})
}

type LayerCreate ¶

type LayerCreate[T any] struct {
	// SuccessURL represents the dynamic Getter resolving to the redirection target URL upon successful record creation.
	SuccessURL getters.Getter[string]
	// FormPatchers represents the collection of patch middleware rules to apply to form maps before database insertion.
	FormPatchers FormPatchers
}

LayerCreate handles database record insertion transactions for type T on incoming POST requests. On non-POST requests, it passes execution to the next handler downstream.

On a POST request, it parses the view's form parameters, executes registered FormPatchers, populates a new record instance of type T with the non-association values, inserts it inside a transaction, and syncs many-to-many associations. Upon successful creation, the new primary key is stored as "$id" on the request context. If SuccessURL is set, a successful operation redirects the browser to the resolved path. Otherwise, it passes execution downstream with the enriched context.

Use Cases:

• Handling model creation form submissions (e.g. creating users, items, or configurations).
• Triggering background jobs or side-effects upon record creation using transaction commit hooks.

Example:

views.View{
    Layers: []views.Layer{
        &views.PathLayer{Names: []string{"id"}},
        views.LayerCreate[User]{
            SuccessURL: lamu.RoutePath("users.List", nil),
            FormPatchers: views.FormPatchers{
                registry.NewPair("author", AuthorPatcher{}),
            },
        },
    },
}

func (m LayerCreate[T]) Next(view View, next http.Handler) http.Handler

type LayerDelete ¶

type LayerDelete[T any] struct {
	// Key is the Getter function returning the context key pointing to the target record to delete.
	Key getters.Getter[string]
	// SuccessURL represents the dynamic Getter resolving to the redirection target URL upon successful deletion.
	SuccessURL getters.Getter[string]
	// QueryPatchers represents the slice of query modifications to restrict deletion scopes.
	QueryPatchers QueryPatchers[T]
}

LayerDelete handles database row removal operations for type T on DELETE/POST request actions. It expects the target record to already reside inside the context under Key (typically placed by a preceding LayerDetail layer).

Upon intercepting a delete trigger, it extracts the record's primary ID, runs GORM deletions through any configured QueryPatchers, and handles redirections or downstream handler execution depending on SuccessURL mappings.

Use Cases:

• Supporting resource deletion handlers (e.g. deleting users, clearing obsolete transactions).
• Applying scope-based delete queries (e.g., confirming record ownership before issuing DB delete commands).

Example:

views.View{
    Layers: []views.Layer{
        views.LayerDetail[User]{Key: getters.Static("$record")},
        views.LayerDelete[User]{
            Key:        getters.Static("$record"),
            SuccessURL: lamu.RoutePath("users.List", nil),
        },
    },
}

func (m LayerDelete[T]) Next(view View, next http.Handler) http.Handler

type LayerDetail ¶

type LayerDetail[T any] struct {
	// Key represents the context key string under which the loaded record instance is stored.
	// PathParamKey represents the URL path parameter name carrying the primary key (e.g., "id").
	Key, PathParamKey getters.Getter[string]

	// QueryPatchers represents the slice of query modifiers applied to GORM before retrieving the row.
	QueryPatchers QueryPatchers[T]
}

LayerDetail loads a single database record of type T by querying its primary key from a URL route path parameter. It acts as the primary data loader, storing the fetched record in the request context under Key for downstream layers or handlers (e.g. LayerUpdate or LayerDelete).

QueryPatchers are applied to the query before execution, permitting preloading of associations, access control filtering, or tenant scopes.

Use Cases:

• Fetching detail records for display views (e.g. profile edit pages, product specifications).
• Injecting model contexts for subsequent operations like record updates or deletions.

Example:

views.View{
    Layers: []views.Layer{
        &views.PathLayer{Names: []string{"userId"}},
        views.LayerDetail[User]{
            PathParamKey: getters.Static("userId"),
            Key:          getters.Static("$user"),
            QueryPatchers: views.QueryPatchers{
                views.QueryPatcherPreload[User]("Profile"),
            },
        },
    },
}

func (m LayerDetail[T]) Next(view View, next http.Handler) http.Handler

type LayerJsonImport ¶

type LayerJsonImport[T any] struct {
	// FileField represents the form parameter key name representing the uploaded JSON file.
	FileField string
	// SuccessURL represents the dynamic Getter resolving to the redirection target URL upon successful bulk imports.
	SuccessURL getters.Getter[string]
}

LayerJsonImport handles bulk creation of database records of type T from a JSON file upload on incoming POST requests. On non-POST requests, it passes through downstream.

On a POST trigger, it extracts the uploaded file from FileField, decodes it as a JSON array of type T, and runs batch creations of 100 records inside a transaction. Upon successful completion, the imported count is saved as "$count" on the request context.

Use Cases:

• Importing bulk data sets from structured JSON files (e.g. uploading user spreadsheets or importing inventories).

Example:

views.View{
    Layers: []views.Layer{
        views.LayerJsonImport[Product]{
            FileField:  "import_file",
            SuccessURL: lamu.RoutePath("products.List", nil),
        },
    },
}

func (m LayerJsonImport[T]) Next(view View, next http.Handler) http.Handler

type LayerList ¶

type LayerList[T any] struct {
	// Key represents the context key string under which the loaded components.ObjectList is stored.
	Key getters.Getter[string]
	// PageSize represents the dynamic Getter returning the number of records per page (defaults to 12).
	PageSize getters.Getter[uint]
	// QueryPatchers represents the slice of query modifiers applied to GORM before retrieving the list.
	QueryPatchers QueryPatchers[T]
}

LayerList manages paginated database queries and column sorting/filtering operations for collections of type T. It parses whitelisted URL query parameters matching model fields, builds dynamic GORM queries, loads paged results inside components.ObjectList, and stores them in the request context under Key.

Automatically applies ILIKE containing checks for string fields, equality matches for other types, and resolves ordering clauses depending on the "sort" parameters.

Use Cases:

• Displaying search/filter list views (e.g. users directories, transaction histories).
• Supporting table widgets with numeric page toggles or filter panels.

Example:

views.View{
    Layers: []views.Layer{
        views.LayerList[User]{
            Key:      getters.Static("$usersList"),
            PageSize: getters.Static(uint(15)),
            QueryPatchers: views.QueryPatchers{
                views.QueryPatcherPreload[User]("Profile"),
            },
        },
    },
}

func (m LayerList[T]) Next(view View, next http.Handler) http.Handler

type LayerSingleton ¶

type LayerSingleton[T any] struct {
	// SuccessURL represents the dynamic Getter resolving to the redirection target URL upon successful singleton updates.
	SuccessURL getters.Getter[string]
}

LayerSingleton manages single-row settings database tables of type T (e.g. system configurations, site-wide parameters). It combines the functions of detail loading and updating because there is no primary key parameter passed via URLs. Instead, it operates on the single record returned from FirstOrCreate.

On non-POST triggers (e.g. GET), it loads or creates the singleton row, storing its fields map in the request context under getters.ContextKeyIn to pre-fill template form input values. On POST triggers, it parses form parameters, runs GORM Updates inside a transaction, syncs association values, and handles redirects.

Use Cases:

• Managing global system settings, administrator configs, or general app configuration forms.

Example:

views.View{
    Layers: []views.Layer{
        views.LayerSingleton[SystemConfig]{
            SuccessURL: lamu.RoutePath("admin.Dashboard", nil),
        },
    },
}

func (m LayerSingleton[T]) Next(view View, next http.Handler) http.Handler

type LayerTableToggleColumns ¶

type LayerTableToggleColumns struct {
	// QueryParam represents the Getter resolving to the URL query parameter key (e.g. "cols").
	QueryParam getters.Getter[string]
	// ContextKey represents the Getter resolving to the request context key under which the visibility map is saved.
	ContextKey getters.Getter[string]
}

LayerTableToggleColumns parses a URL query parameter carrying a list of active columns, builds a boolean map of visible columns, and stores it in the request context under ContextKey. Downstream data tables fetch this map (e.g., using components.GetterEnabledColumnsFromContext) to dynamically show or hide fields.

Use Cases:

• Supporting customizable table layouts where users can check/uncheck columns via toolbar toggles.

Example:

views.View{
    Layers: []views.Layer{
        views.LayerTableToggleColumns{
            QueryParam: getters.Static("cols"),
            ContextKey: getters.Static("visibleColumnsMap"),
        },
        views.LayerList[User]{
            Key: getters.Static("$users"),
        },
    },
}

func (m LayerTableToggleColumns) Next(_ View, next http.Handler) http.Handler

type LayerUpdate ¶

type LayerUpdate[T any] struct {
	// Key represents the context key pointing to the target loaded record to update.
	Key getters.Getter[string]
	// SuccessURL represents the dynamic Getter resolving to the redirection target URL upon successful updates.
	SuccessURL getters.Getter[string]
	// FormPatchers represents the collection of patch middleware rules to apply to form maps before updates.
	FormPatchers FormPatchers
	// QueryPatchers represents the slice of query modifications to restrict update scopes.
	QueryPatchers QueryPatchers[T]
}

LayerUpdate handles database row updates for type T on incoming POST requests. It expects the target record to already reside inside the context under Key (typically loaded by a preceding LayerDetail layer).

On intercepting a POST action, it parses form values, runs registered FormPatchers, updates columns recursively inside a GORM transaction, syncs association properties, and handles redirection links.

Use Cases:

• Driving resource edit/update views (e.g., editing user profiles, updating product information).
• Triggering background jobs or side-effects upon record update using transaction commit hooks.

Example:

views.View{
    Layers: []views.Layer{
        views.LayerDetail[User]{Key: getters.Static("$record")},
        views.LayerUpdate[User]{
            Key:        getters.Static("$record"),
            SuccessURL: lamu.RoutePath("users.List", nil),
        },
    },
}

func (m LayerUpdate[T]) Next(view View, next http.Handler) http.Handler

type MethodLayer ¶

type MethodLayer struct {
	// Method represents the target HTTP verb (e.g., "GET", "POST").
	Method string
	// Handler represents the routing sub-handler builder function.
	Handler func(*View) http.Handler
}

MethodLayer routes incoming requests matching a specific HTTP Method string directly to a custom sub-handler function, bypassing subsequent middleware chains.

func (m MethodLayer) Next(view View, next http.Handler) http.Handler

type MultiStepFormLayer ¶

type MultiStepFormLayer struct{}

MultiStepFormLayer coordinates stage transitions, input validations, error caching, and HTMX swaps for multi-stage wizards. It intercepts HTTP POST operations targeting components.MultiStepForm page wrappers, increments or decrements the request context "$stage" index, merges carried validation errors, and enforces HTTP StatusUnprocessableEntity (422) redirects to swap out form stages.

Use Cases:

• Driving multi-stage checkout forms, step-by-step registration processes, or linear onboarding flows.

Example:

views.View{
    Layers: []views.Layer{
        views.MultiStepFormLayer{},
    },
}

func (m MultiStepFormLayer) Next(view View, next http.Handler) http.Handler

type PathLayer ¶

type PathLayer struct {
	// Names represents the slice of URL path parameter keys to extract.
	Names []string
}

PathLayer extracts URL path parameter variables (PathValue) and stores them in a map[string]any under the "$path" context key.

func (m PathLayer) Next(_ View, next http.Handler) http.Handler

type QueryPatcher ¶

type QueryPatcher[T any] interface {
	// Patch injects queries, preloads, scopes, or joins, returning the decorated GORM chain.
	Patch(View, *http.Request, gorm.ChainInterface[T]) gorm.ChainInterface[T]
}

QueryPatcher defines an interface for component utilities capable of modifying a database query chain. It is applied during database retrieval flows (like detail queries, list queries, updates, or deletions) to append SQL filters.

Use Cases:

• Injecting preloads to eager-load relations (e.g. preloading profiles or tags).
• Appending multi-tenant scoping filters (e.g., scoping data queries by current account ID).
• Enforcing state constraints (e.g. filtering out soft-deleted items or restricting lists to active states).

Example:

type TenantScopePatcher struct{}

func (p TenantScopePatcher) Patch(view views.View, r *http.Request, query gorm.ChainInterface[Product]) gorm.ChainInterface[Product] {
	tenantID := GetTenantIDFromContext(r.Context())
	return query.Where("tenant_id = ?", tenantID)
}

type QueryPatcherJoinFilter ¶

type QueryPatcherJoinFilter[T any, TJoin any] struct {
	// Param represents the key in the request parameter map ($get) containing the selected IDs.
	Param string
	// OwnerField represents the struct field name of the foreign key to model T inside the join model TJoin (e.g., "CourseID").
	OwnerField string
	// RelatedField represents the struct field name of the foreign key to the associated entity inside the join model TJoin (e.g., "TeacherID").
	RelatedField string
}

QueryPatcherJoinFilter filters rows of model type T based on association IDs of another entity, resolved via a many-to-many join model TJoin. It extracts selected IDs from the query parameter map, resolves the struct field names to database columns using schema reflection, and appends a subquery filter.

Use Cases:

• Filtering a list of records by many-to-many associations (e.g., filtering courses matching a set of teacher IDs via a CourseTeacher join table).

Example:

views.View{
    Layers: []views.Layer{
        views.LayerList[Course]{
            QueryPatchers: views.QueryPatchers{
                views.NewPair("filter_teachers", views.QueryPatcherJoinFilter[Course, CourseTeacher]{
                    Param:        "teacher_ids",
                    OwnerField:   "CourseID",
                    RelatedField: "TeacherID",
                }),
            },
        },
    },
}

func (p QueryPatcherJoinFilter[T, TJoin]) Patch(_ View, r *http.Request, db gorm.ChainInterface[T]) gorm.ChainInterface[T]

type QueryPatcherOrderBy ¶

type QueryPatcherOrderBy[T any] struct {
	// Order represents the SQL order clause string (e.g., "name ASC", "id DESC").
	Order string
}

QueryPatcherOrderBy applies a default SQL ORDER BY sort clause to a GORM query chain.

Use Cases:

• Enforcing default sorting orders on index tables (e.g. listing elements by creation dates descending, or alphabetically).

Example:

views.View{
    Layers: []views.Layer{
        views.LayerList[Product]{
            QueryPatchers: views.QueryPatchers{
                views.NewPair("default_sort", views.QueryPatcherOrderBy[Product]{
                    Order: "created_at DESC",
                }),
            },
        },
    },
}

func (p QueryPatcherOrderBy[T]) Patch(_ View, _ *http.Request, db gorm.ChainInterface[T]) gorm.ChainInterface[T]

type QueryPatcherPreload ¶

type QueryPatcherPreload[T any] struct {
	// Fields represents the slice of GORM association names or nested dotted paths to eager load (e.g. "Profile", "Profile.Address").
	Fields []string
	// PreloadBuilder represents an optional callback allowing custom SQL builders on relation queries.
	PreloadBuilder func(View, *http.Request, gorm.PreloadBuilder) error
}

QueryPatcherPreload applies GORM eager preloads to the database query chain, fetching related association entities. Eager preloads prevent N+1 database queries when rendering rows and grids referencing nested relational data fields.

Use Cases:

• Eager-loading relational dependencies (e.g. preloading user profiles, loading item tags).
• Customizing relation preloads (e.g. ordering preloaded history logs chronologically).

Example:

views.View{
    Layers: []views.Layer{
        views.LayerList[Product]{
            QueryPatchers: views.QueryPatchers{
                views.NewPair("preload_tags", views.QueryPatcherPreload[Product]{
                    Fields: []string{"Tags"},
                }),
            },
        },
    },
}

func (p QueryPatcherPreload[T]) Patch(v View, r *http.Request, db gorm.ChainInterface[T]) gorm.ChainInterface[T]

type QueryPatcherSearch ¶

type QueryPatcherSearch[T any] struct {
	// Columns represents the list of database column names to match using OR ILIKE clauses.
	Columns []string
}

QueryPatcherSearch applies a case-insensitive OR contains filter (using ILIKE) across multiple database columns. It executes when the "search" URL query parameter is non-empty (e.g. ?search=term).

Use Cases:

• Implementing global search input controls on data index tables to search records by text fields (e.g., matching users by first name, last name, or email).

Example:

views.View{
    Layers: []views.Layer{
        views.LayerList[User]{
            QueryPatchers: views.QueryPatchers{
                views.NewPair("global_search", views.QueryPatcherSearch[User]{
                    Columns: []string{"first_name", "last_name", "email"},
                }),
            },
        },
    },
}

func (p QueryPatcherSearch[T]) Patch(_ View, r *http.Request, db gorm.ChainInterface[T]) gorm.ChainInterface[T]

type QueryPatchers ¶

type QueryPatchers[T any] []registry.Pair[string, QueryPatcher[T]]

QueryPatchers represents a sequence of QueryPatcher registry pairs applied in order.

func (q QueryPatchers[T]) Apply(view View, r *http.Request, query gorm.ChainInterface[T]) gorm.ChainInterface[T]

type TxCommitHook ¶

type TxCommitHook interface {
	// AfterTxCommit runs logic immediately after a successful transaction commit.
	AfterTxCommit(db *gorm.DB)
}

TxCommitHook defines an interface for GORM model types that execute hooks after a creation or update transaction successfully commits. Unlike GORM's built-in transaction hooks (which run within the active transaction blocks), the hook parameter represents the request-scoped pooled db connection (running outside the transaction context).

Use Cases:

• Sending confirmation/welcome emails immediately after a user record has committed to the database.
• Triggering async operations (like publishing event payloads, starting workers, or invalidating caches) post-commit.

Example:

type Member struct {
	gorm.Model
	Email string
}

func (m *Member) AfterTxCommit(db *gorm.DB) {
	// Safely queue welcome notification after transaction commits.
	go queueWelcomeEmail(m.Email)
}

type View ¶

type View struct {
	// PageName represents the unique identifier string referencing the page component.
	PageName string
	// PageLookup represents the resolver function mapping page keys to [components.PageInterface] objects.
	PageLookup func(name string) (components.PageInterface, bool)
	// Layers represents the collection of middleware layers wrapping page views.
	Layers []registry.Pair[string, Layer]
	// contains filtered or unexported fields
}

View represents the core page controller coordinating middleware layers and page template rendering pipelines. It matches incoming HTTP requests, executes an ordered sequence of middleware Layer steps (e.g. data fetching, authentication, or updates), parses input parameters, and renders target HTML pages compiled from components.PageInterface trees.

Use Cases:

• Defining request endpoints mapping back-office dashboards, user profiles, or transactional forms.
• Structuring reusable middleware layers to execute prior to HTML rendering phases.

Example:

var UserDetailView = &views.View{
	PageName:   "users.detail",
	PageLookup: myRegistryLookup,
	Layers: []registry.Pair[string, views.Layer]{
		registry.NewPair("detail", views.LayerDetail[User]{Key: getters.Static("$record")}),
	},
}

func (v *View) GetHandler() http.Handler

func (v *View) GetPage() (components.PageInterface, bool)

func (v *View) InsertLayerAfter(afterName, name string, layer Layer) *View

func (v *View) InsertLayerBefore(beforeName, name string, layer Layer) *View

func (v *View) ParseForm(w http.ResponseWriter, r *http.Request) (map[string]any, map[string]error, error)

func (v *View) PatchLayer(name string, patcher func(Layer) Layer) *View

func (v *View) PatchLayers(layers ...registry.Pair[string, func(Layer) Layer]) *View

func (v *View) RenderPage(w http.ResponseWriter, r *http.Request)

func (v *View) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (v *View) WithLayer(name string, layer Layer) *View

func (v *View) WithLayers(layers ...registry.Pair[string, Layer]) *View