luci: go.chromium.org/luci/server/portal Index | Files | Directories

package portal

import "go.chromium.org/luci/server/portal"

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

Package Files

handlers.go index.go page.go settings.go yesno.go

func GetPages Uses

func GetPages() map[string]Page

GetPages returns a map with all registered pages.

func InstallHandlers Uses

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.

func RegisterPage Uses

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.

type Action Uses

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

    // Callback is executed on click.
    //
    // The context is derived through the base middleware in the router. The
    // return values is presented to the user as is.
    Callback func(c context.Context) (template.HTML, error)
}

Action corresponds to a button that triggers a parameterless callback.

type BasePage Uses

type BasePage struct{}

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

func (BasePage) Actions Uses

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

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

func (BasePage) Fields Uses

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

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

func (BasePage) Overview Uses

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

Overview is optional HTML paragraph describing this portal page.

func (BasePage) ReadSettings Uses

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

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

func (BasePage) Title Uses

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

Title is used in UI to name this portal page.

func (BasePage) WriteSettings Uses

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 Uses

type Field struct {
    ID             string             // page unique ID
    Title          string             // human friendly name
    Type           FieldType          // how the field is displayed and behaves
    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 Uses

func YesOrNoField(f Field) Field

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

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

type FieldType Uses

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/*.

func (FieldType) IsEditable Uses

func (f FieldType) IsEditable() bool

IsEditable returns true for fields that can be edited.

type Page Uses

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.
    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".
    //
    // All values are validated using field validators first.
    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 Uses

type YesOrNo bool

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

Useful in Fields that define boolean values.

func (*YesOrNo) Set Uses

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

Set changes the value of YesOrNo.

func (YesOrNo) String Uses

func (yn YesOrNo) String() string

String returns "yes" or "no".

Directories

PathSynopsis
internal/assetsPackage assets is generated by go.chromium.org/luci/tools/cmd/assets.

Package portal imports 23 packages (graph) and is imported by 19 packages. Updated 2018-12-19. Refresh now. Tools for package owners.