Documentation

Overview

    Package portal implements HTTP routes for portal pages.

    These pages can be registered at init()-time, and will be routed to /admin/portal.

    Typically they read/write `settings` as defined by `go.chromium.org/luci/server/settings`, but they can also be used to provide information to administrators or to provide admin-only actions (such as clearing queues or providing admin tokens).

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var AssumeTrustedPort auth.Method = trustedPortAuth{}

      AssumeTrustedPort can be passed as auth.Method to InstallHandlers to indicate that portal endpoints are being exposed on an internal port accessible only to cluster administrators and no additional auth checks are required (or they are not possible).

      Functions

      func GetPages

      func GetPages() map[string]Page

        GetPages returns a map with all registered pages.

        func InstallHandlers

        func InstallHandlers(r *router.Router, base router.MiddlewareChain, adminAuth auth.Method)

          InstallHandlers installs HTTP handlers that implement admin UI.

          `adminAuth` is the method that will be used to authenticate the access (regardless of what's installed in the base context). It must be able to distinguish admins (aka superusers) from non-admins. It is needed because settings UI must be usable even before auth system is configured.

          `adminAuth` can be a special value portal.AssumeTrustedPort which completely disables all authentication and authorization checks (by delegating them to the network layer).

          func RegisterPage

          func RegisterPage(pageKey string, p Page)

            RegisterPage makes exposes UI for a portal page (identified by given unique key).

            Should be called once when application starts (e.g. from init() of a package that defines the page). Panics if such key is already registered.

            Types

            type Action

            type Action struct {
            	ID            string        // page-unique ID
            	Title         string        // what's displayed on the button
            	Help          template.HTML // optional help text
            	Confirmation  string        // optional text for "Are you sure?" confirmation prompt
            	NoSideEffects bool          // if true, the callback just returns some data
            
            	// Callback is executed on click on the action button.
            	//
            	// Usually it will execute some state change and return the confirmation text
            	// (along with its title). If NoSideEffects is true, it may just fetch and
            	// return some data (which is either too big or too costly to fetch on the
            	// main page).
            	Callback func(c context.Context) (title string, body template.HTML, err error)
            }

              Action corresponds to a button that triggers a parameterless callback.

              type BasePage

              type BasePage struct{}

                BasePage can be embedded into Page implementers to provide default behavior.

                func (BasePage) Actions

                func (BasePage) Actions(c context.Context) ([]Action, error)

                  Actions is additional list of actions to present on the page.

                  func (BasePage) Fields

                  func (BasePage) Fields(c context.Context) ([]Field, error)

                    Fields describes the schema of the settings on the page (if any).

                    func (BasePage) Overview

                    func (BasePage) Overview(c context.Context) (template.HTML, error)

                      Overview is optional HTML paragraph describing this portal page.

                      func (BasePage) ReadSettings

                      func (BasePage) ReadSettings(c context.Context) (map[string]string, error)

                        ReadSettings returns a map "field ID => field value to display".

                        func (BasePage) Title

                        func (BasePage) Title(c context.Context) (string, error)

                          Title is used in UI to name this portal page.

                          func (BasePage) WriteSettings

                          func (BasePage) WriteSettings(c context.Context, values map[string]string, who, why string) error

                            WriteSettings saves settings described as a map "field ID => field value".

                            type Field

                            type Field struct {
                            	ID             string             // page unique ID
                            	Title          string             // human friendly name
                            	Type           FieldType          // how the field is displayed and behaves
                            	ReadOnly       bool               // if true, display the field as immutable
                            	Placeholder    string             // optional placeholder value
                            	Validator      func(string) error // optional value validation
                            	Help           template.HTML      // optional help text
                            	ChoiceVariants []string           // valid only for FieldChoice
                            }

                              Field is description of a single UI element of the page.

                              Its ID acts as a key in map used by ReadSettings\WriteSettings.

                              func YesOrNoField

                              func YesOrNoField(f Field) Field

                                YesOrNoField modifies the field so that it corresponds to YesOrNo value.

                                It sets 'Type', 'ChoiceVariants' and 'Validator' properties.

                                func (*Field) IsEditable

                                func (f *Field) IsEditable() bool

                                  IsEditable returns true for fields that can be edited.

                                  type FieldType

                                  type FieldType string

                                    FieldType describes look and feel of UI field, see the enum below.

                                    const (
                                    	FieldText     FieldType = "text"     // one line of text, editable
                                    	FieldChoice   FieldType = "choice"   // pick one of predefined choices
                                    	FieldStatic   FieldType = "static"   // one line of text, read only
                                    	FieldPassword FieldType = "password" // one line of text, editable but obscured
                                    )

                                      Note: exact values here are important. They are referenced in the HTML template that renders the settings page. See server/portal/*.

                                      type Page

                                      type Page interface {
                                      	// Title is used in UI to name this page.
                                      	Title(c context.Context) (string, error)
                                      
                                      	// Overview is optional HTML paragraph describing this page.
                                      	Overview(c context.Context) (template.HTML, error)
                                      
                                      	// Fields describes the schema of the settings on the page (if any).
                                      	Fields(c context.Context) ([]Field, error)
                                      
                                      	// Actions is additional list of actions to present on the page.
                                      	//
                                      	// Each action is essentially a clickable button that triggers a parameterless
                                      	// callback that either does some state change or (if marked as NoSideEffects)
                                      	// just returns some information that is displayed on a separate page.
                                      	Actions(c context.Context) ([]Action, error)
                                      
                                      	// ReadSettings returns a map "field ID => field value to display".
                                      	//
                                      	// It is called when rendering the settings page.
                                      	ReadSettings(c context.Context) (map[string]string, error)
                                      
                                      	// WriteSettings saves settings described as a map "field ID => field value".
                                      	//
                                      	// Only values of editable, not read only fields are passed here. All values
                                      	// are also validated using field's validators before this call.
                                      	WriteSettings(c context.Context, values map[string]string, who, why string) error
                                      }

                                        Page controls how some portal section (usually corresponding to a key in global settings JSON blob) is displayed and edited in UI.

                                        Packages that wishes to expose UI for managing their settings register a page via RegisterPage(...) call during init() time.

                                        type YesOrNo

                                        type YesOrNo bool

                                          YesOrNo is a bool that serializes to 'yes' or 'no'.

                                          Useful in Fields that define boolean values.

                                          func (*YesOrNo) Set

                                          func (yn *YesOrNo) Set(v string) error

                                            Set changes the value of YesOrNo.

                                            func (YesOrNo) String

                                            func (yn YesOrNo) String() string

                                              String returns "yes" or "no".

                                              Directories

                                              Path Synopsis
                                              internal
                                              assets
                                              Package assets is generated by go.chromium.org/luci/tools/cmd/assets.
                                              Package assets is generated by go.chromium.org/luci/tools/cmd/assets.