Admin page

Admin page

From v1.42, Gramex ships with an admin page. To include it in your page, use:

import:
  admin/admin:
    path: $GRAMEXAPPS/admin2/gramex.yaml # Note the "admin2" instead of "admin"
    YAMLURL: /$YAMLURL/admin/ # URL to show the admin page at
Source

Admin page example

You can configure the admin page as follows:

import:
  admin/admin-kwargs:
    path: $GRAMEXAPPS/admin2/gramex.yaml
    YAMLURL: /$YAMLURL/admin-kwargs/ # URL to show the admin page at
    ADMIN_KWARGS:
      logo: https://gramener.com/uistatic/gramener.png # Logo URL
      home: /$YAMLURL/ # URL that logo links to
      title: Admin  Page Options # Navbar title
      components: [info, users, shell] # Components to show
      theme: "?font-family-base=roboto" # UI component theme query
    ADMIN_AUTH:
      membership:
        email: [admin1@example.org, admin2@example.org] # Only allow these users

The ADMIN_KWARGS section accepts the following parameters:

The ADMIN_AUTH section is the same as specifying the auth: authorization on all admin pages. For example:

ADMIN_AUTH:
  login_url: /$YAMLURL/login/
  membership:
    email: [admin1@example.org, admin2@example.org] # Only allow these users

… is the same as specifying this on every admin page:

auth:
  login_url: /$YAMLURL/login/
  membership:
    email: [admin1@example.org, admin2@example.org] # Only allow these users
Source

Admin page options example

Admin: User management

To manage users, add roles and other attributes, use the user component. To enable it:

  1. Ensure that users is in components: (e.g. components: [users, ...]) or you don’t specify any components.
  2. Add an authhandler: that has the name of a auth handler that is either a DBAuth or has a lookup section

For example:

import:
  admin/admin-user:
    path: $GRAMEXAPPS/admin2/gramex.yaml
    YAMLURL: /$YAMLURL/admin-user/
    ADMIN_KWARGS:
      authhandler: login        # Manages users via the url: key named "login"

url:
  login:                        # Here is the url: key named "login"
    pattern: ...
    handler: DBAuth             # This must either be DBAuth...
    kwargs:
      ...
      lookup:                   # ... or have a lookup: section
        ...
Source

User management example

User management is available as a component. To embed it in your page, add a FormHandler table component:

<div class="users"></div>
<script>
  $(".users").formhandler({
    src: "admin/users-data", // Assuming the admin page is at admin/
    edit: true, // Allow editing users
    add: true, // Allow adding users
  });
</script>
Source

User management component example

You can specify custom actions & formats using FormHandler table. See the admin page source code for examples of custom actions.

Sign Up Users with a Welcome Email

You can send welcome emails to new users added through the user management component. To enable it, add a signup: key to ADMIN_KWARGS. It supports two values, email_subject and email_body. Both values are template strings that can be formatted with any user attribute.

For example, the following spec

import:
  admin/admin-user:
    path: $GRAMEXAPPS/admin2/gramex.yaml
    YAMLURL: /$YAMLURL/admin-user/
    ADMIN_KWARGS:
      authhandler: login # Manages users via the url: key named "login"
      signup:
        email_subject: Welcome {user} to {org}
        email_body: |
          Hello, {user}! Welcome to {org}.
          Your location is {location}.

sends emails to new users with the subject and body as specified, where user, org and location are user attributes contained in the login authhandler. The templates work for any user attributes.

Filter User Data

You can filter user data, e.g. to clear the password column to avoid exposing it over a network, add a userdata: key to ADMIN_KWARGS. For example:

import:
  admin/admin-user:
    path: $GRAMEXAPPS/admin2/gramex.yaml
    YAMLURL: /$YAMLURL/admin-user/
    ADMIN_KWARGS:
      authhandler: login # Manages users via the url: key named "login"
      userdata:
        # Only on GET (not POST/PUT, when we are adding/updating user info),
        # clear the password column if it exists.
        # Note: Check the name of the password column in your authhandler
        # Note: Always check if the column exists. This modify is used for multiple FormHandlers
        modify: data.assign(password='') if handler.request.method == 'GET' and 'password' in data.columns else data

You can use any modify function here, e.g. to clear more columns or add/transform columns.

Edit User Attribute Rules

The user management component also includes an editor for the rules that modify user attributes. If the authhandler associated with your Admin app contains a rules kwarg, then an editor for those rules appears in the user management component as a FormHandler table.

This table can also be embedded anywhere else as follows:

<div class="user-rules"></div>
<script>
  $(".user-rules").formhandler({
    src: "admin/auth-rules", // Assuming the admin page is at admin/
    // and the corresponding `authhandler` contains `rules`
    edit: true, // Allow editing rules
    add: true, // Allow adding rules
  });
</script>

Admin: Schedule

The schedule component lets you see all scheduler tasks defined under the schedule: section, and run them.

Source

Schedule example

The admin schedule component can be embdded in any page:

<div class="schedule"></div>
<script src="schedule.js"></script>
<script>
  $(".schedule").schedule({
    // Embed the scheduler
    url: "admin/schedule-data", // Assuming the admin page is at admin/
  });
</script>
Source

Schedule component example

Admin: Alert

The alert component lets you see all alerts defined under the alert: section, and preview or run them.

Source

Alert example

The admin alert component can be embedded in any page:

<div class="schedule"></div>
<script src="schedule.js"></script>
<script>
  $(".schedule").schedule({
    // Alerts use the same component as schedulers
    alert: true, // ... but with the alert: true option
    url: "admin/alert-data", // Assuming the admin page is at admin/
  });
</script>

Admin: Shell

The shell adds a web-based Python shell that runs commands within the running Gramex instance. This is useful when debugging a live environment. To enable it, ensure that you specify:

In the shell, you can run these commands:

1 + 2                   # Evaluate Python expressions
import gramex           # All gramex libraries are available
handler.session         # WebsocketHandler instance is available as 'handler'

The web shell is available as a component. To embed it in your page, add:

<div class="webshell"></div>
<script src="admin/webshell.js"></script>
<script>
  $(".webshell").webshell({
    // Embed the web shell here
    url: "admin/webshell-data", // Assuming the admin page is at admin/
    prompt: ">>> ", // Prompt to display at the start of each page
    welcome: [
      // Welcome message as a list of lines.
      "Welcome to the Gramex shell",
      ">>> ",
    ],
  });
</script>
Source

Web shell component example

Admin: Info

The info page shows information about versions, paths and other details about Gramex and its dependencies.

To enable it, ensure that you specify:

This exposes JSON data at <admin-page>/info-data as a list of objects consistent with FormHandler.

[
    {"section":"git","key":"path","value":"D:\\bin\\git.EXE","error":null},
    {"section":"git","key":"version","value":"git version 2.15.1\n","error":""},{"section":"gramex","key":"memory usage","value":153411584,"error":""},
    ...
]

The information provided includes (in a <section>.<key> notation):

The result is stored in the value column. If the value is not available, the error is stored in the error column.

Source

Info page example

Admin: Config

Admin: Logs

Admin access control

Admin page (old)

From v1.33, Gramex used a beta version of the admin page. This was REMOVED in Gramex 1.87.0.

To use it, add this to your gramex.yaml:

import:
  admin1:
    path: $GRAMEXAPPS/admin/gramex.yaml # Source of the app
    YAMLURL: /$YAMLURL/admin1/ # Location to mount at
    ADMIN_LOOKUP:
      url: $YAMLPATH/lookup.xlsx # DB / file with user information
      id: user # Column name that has the user ID

Use ADMIN_* variables to configure your app.

Sample use of role:

import:
  admin:
    path: $GRAMEXAPPS/admin/gramex.yaml
    YAMLURL: /$YAMLURL/admin/
    ADMIN_LOOKUP:
      url: $YAMLPATH/lookup.xlsx
      id: user # user column in Excel sheet has the user name
    ADMIN_USER: ["alpha"] # Always allow user `alpha`
    ADMIN_ROLE: ["admin"] # Also allow anyone with role as admin
    LOGIN_URL: /admin/ # URL to show login page for admin page
    LOGOUT_URL: /logout/ # URL to logout

By default, admin site can be accessed by any user when using 127.0.0.1.