@nxus/admin-ui

An Admin UI Framework for Nxus Apps

Usage no npm install needed!

<script type="module">
  import nxusAdminUi from 'https://cdn.skypack.dev/@nxus/admin-ui';
</script>

README

@nxus/admin-ui

Build Status">

An Admin UI Framework for Nxus Apps.

Installation

> npm install @nxus/admin-ui --save

Optional Module Configuration

There are two configuration options you can specify in your package.json file to change the way the admin-ui module functions. All configuration should be under the admin-ui section of the config key.

  • basePath: the base path, defaults to /admin
  • adminTemplate: the admin template to use, defaults to 'admin'

For example:

"config": {
  "admin-ui": {
    "basePath": "/otherRoute",
    "adminTemplate": "myAdmin"
  }
}

Usage

The Admin Interface is made up of pages and routes. Pages are rendered content displayed in the Admin Interface. Routes are callbacks that don't render anything, but perform application logic (like a save handler).

Admin Pages

You can define pages in three ways using the adminPage provider.

A partial

If you supply a valid filepath, the Admin interface will use that partial to render the page content for display.

admin.adminPage('Page Title', '/partial', {iconClass: 'fa fa-file'}, __dirname+"/views/page.ejs")
A string

If you provide a string, the string will be passed to the admin page template as is.

admin.adminPage('Page Title', '/content', {iconClass: 'fa fa-file'}, (req, res) => {
  return "this is handler content"
})
A callback

If you provide a callback, the return should either a string or a Promise for a string.

admin.adminPage('Page Title', '/function', (req, res) => {
  return Promise.resolve('Some text');
})
Page Configuration Options
  • class: string
  • iconClass: string
  • nav: boolean
  • order: integer

Admin Routes

A handler function
admin.adminRoute('get', '/redirect', (req, res) => {
  res.redirect('/admin')
})

Model View helpers

The module provides a helper for generating list/detail views from a model:

app.get('admin-ui').adminModel('user', {base: '/users', titleField: 'email'})

You may pass in an options object, as in this example, or subclass of ViewBase, or a string path to a subclass of ViewBase.

import {AdminBase} from '@nxus/admin-ui'

class UserView extends AdminBase {
  model() {
    return 'user'
  }
  base() {
    return '/users'
  }
  titleField() {
    return 'email
  }
}

app.get('admin-ui').adminModel(UserView)

Customizing

If you want to provide your own 404 or 500 page, define the relevant new template. Base-ui will use these to handle the routes above.

List and Detail View

You can specify your own list view template to use instead of the default. The base-ui module looks for a template matching the following pattern: admin-<model>-list and admin-<model>-detail.

Each template will be passed either a model instance (for detail view) or an array of models (for list view), using the model name.

So using the examples above:

app.get('templater').templateFunction('admin-user-list', (opts) => {
  return app.get('renderer').render("ejs", "<% users.forEach(function(user){ .... }) %>", opts)
})

app.get('templater').template('admin-user-detail', 'ejs', () => {
  return app.get('renderer').render("ejs", "Email: <%= user.email %>", opts)
})

API

AdminBase

The AdminBase class provides a set of helper CRUD classes for defining Admin-UI based admin pages.

Examples

class TodoAdmin extends AdminBase {
 base () {
    return '/todo'
  }
 model () {
    return 'todo'
  }
 templateDir () {
    return __dirname+'/views'
  }
}

base

The base url for the Admin CRUD UI.

Returns string Defaults to /<models>

display

Fields in the model to show

Returns array

displayName

The display name for the model to use in the Admin UI

Returns string Defaults to <model>

iconClass

The class to use for the nav icon.

Returns string Defaults to fa fa-file

ignore

Fields in the model to ignore in the UI

Returns string

model

Define the primary model for this admin module

Returns string

modelNames

Returns a hash of currently used models.

Returns [type] [description]

modelPopulate

Define any populated relationships for the model

Returns array

templateDir

The directory to find the templates.

Returns string Defaults to null.

templatePrefix

The prefix to use for the templates. Defaults to admin-<model>-

Returns string

uploadOptions

Options for data-loader on upload

Examples

return {identityFields: ['name'], mapping: {Name: 'name'}}

Returns string

uploadType

Allow upload of models by this file type

Examples

return 'csv'

Returns string

AdminUI

The AdminUI module provides default templates and nav for an administrative section of your site. If the @nxus/users module is installed, the admin section will require admin-level authentication.

Examples

Configuration (defaults):
 {adminUI: {
   basePath: '/admin',    # urls registered for admin will start with this path
   adminTemplate: 'admin' # name of the main admin template to use
 }}

adminModel

Creates a CRUD UI for the specified model, including all routes and views. You can pass in the following combinations:

  1. a model name and opts hash.
  2. a path to a file which is a subclass of AdminBase
  3. a class which is a subclass of AdminBase

Routes created are:

  • /admin/<base>: list page
  • /admin/<base>/create: create new instance
  • /admin/<base>/edit/:id: edit existing instance
  • /admin/<base>/destroy/:id: destroy existing instance

Views which can be overriden are:

  • admin-<model>-form: the create/edit form
  • admin-<model>-list: the list page view

The generated form for edit/create currently handles simple types (string, float, boolean, etc) and foreign key fields as a dropdown of all the related models.

Options available are:

  • base: the url at which the CRUD paths are created. For example, '/users'.
  • iconClass: the icon class to use in the Nav. Used in tag.
  • templatePrefix: a custom prefix for generated templates. Defaults to admin-<model>.
  • ignore: an array of model fields to ignore in the UI. Defaults to ['id', 'createdAt', 'updatedAt']
  • templateDir: a directory containing the list/form templates for the model. Defaults to none.
  • displayName: an alternate name to use for the display in the Admin UI. Defaults to model.

Parameters

  • model (string|class) Can either be a model name, a path to a file or an AdminBase Subclass.
  • opts Object=(default {}) An options hash, wich is used to configure the CRUD UI.

adminPage

Register a page for inclusion in the admin site and navigation Page template will receive (and can set in opts):

  • class: string
  • iconClass: string
  • nav: boolean
  • order: integer

Parameters

  • title String The title of the page, and navigation link
  • path String The url path for the page
  • opts object Additional options for the rendering of this page
  • handler (string|template-partial|function) for rendering this page

adminRoute

Register a raw route for inclusion in the admin site

Parameters

  • method String The HTTP method to handle
  • path String The url path for the page
  • handler function for rendering this page

getInstanceActions

Get the registered actions for model instances

Parameters

  • model String The model identity

getModelActions

Get the registered actions for model

Parameters

  • model String The model identity

instanceAction

Register an action for the model detail page

Parameters

  • model String The model identity to include this action, or '*'
  • label String The button label for this action
  • subURL String The url for this action (register this as an adminPage separately)
  • opts object Additional options: class, iconClass, suffixName

modelAction

Register an action for the model list page

Parameters

  • model String The model identity to include this action, or '*'
  • label String The button label for this action
  • subURL String The url for this action (register this as an adminPage separately)
  • opts object Additional options: class, iconClass, suffixName