This is a CRUDL example with Node.js, Express (REST and GraphQL) and MongoDB.
- CRUDL is still under development and the syntax might change (esp. with connectors and views).
- The relevant part for your admin interface is within the folder crudl-admin-rest/admin/ (resp. crudl-admin-graphql/admin/). All other files and folders are generally given when using CRUDL.
- The views are intentionally verbose in order to illustrate the possibilites with CRUDL.
- Requirements
- Installation
- CRUDL documentation
- Interface
- Connectors & Views
- Notes
- Limitations
- Credits & Links
- Node.js 5+
- MongoDB 2.6+
In order to use this example, you need to setup the API and serve the CRUDL admin interface (either REST or GraphQL or both).
-
Start mongodb:
$ mongod --dbpath "/path/to/my/database/"
-
Clone this repository and cd into the new folder:
$ git clone https://github.com/crudlio/crudl-example-express.git $ cd crudl-example-express
-
Initialize the database and start the server:
$ cd blog blog $ npm install --no-optional blog $ npm run initdb blog $ npm run start
If nodemon is not yet installed, you need to run
npm install -g nodemon
before starting the server. -
Open a new terminal window/tab and build the CRUDL admin file. Go to /crudl-admin-rest/ and type:
crudl-admin-rest $ npm install --no-optional crudl-admin-rest $ npm run watchify
-
Open your browser, go to
http://localhost:3000/crudl-rest/
and login with the demo user (demo/demo).
Steps 1 to 3 are equal to Installation (REST).
-
Open a new terminal window/tab and build the CRUDL admin file. Go to /crudl-admin-graphql/ and type:
crudl-admin-graphql $ npm install --no-optional crudl-admin-graphql $ npm run watchify
-
Open your browser, go to
http://localhost:3000/crudl-graphql/
and login with the demo user (demo/demo).
https://github.com/crudlio/crudl
What you get with CRUDL is an administration interface which consists of these elements:
Dashboard
- The main entry page (currently just contains a description).
listView (per ressource)
- A sortable table with all objects per ressource.
- The objects are usually paginated (either numbered or continuous).
- Includes a sidebar with search and filters.
change/addView (per object)
- The form (fields and fieldsets) for adding/updating an object.
- Optionally with tabs for complex relations (e.g. links with entries).
Moreover, you'll have a Menu/Navigation (on the left hand side), a Login/Logout page and Messages.
While this example is simple, there's still a couple of more advanced features in order to represent a real-world scenario.
In order for CRUDL to work, you mainly need to define connectors and views.
The connectors provide the views with a unified access to different APIs like REST or GraphQL. Each connector usually represents a single API endpoint (or query) and implements the CRUD methods (create, read, update, delete). Moreover, the connector handles pagination and transforms the request/response.
There is a npm package implementing general connectors crudl-connectors-base that can be extended (using middleware) to fit your particular needs.
With views, you create the visual representation by defining the listView, changeView and addView options:
var listView = {
// Required
path: "api/path/to/collection",
title: "Collection Name",
actions: {
list: listConnector.read,
}
fields: [],
// Optional
filters: [],
normalize: (data) => { },
}
var changeView = {
// Required
path: "api/path/to/collection/:_id",
title: "Detail Name",
actions: {
get: req => detailConnector(crudl.path._id).read(req),
save: req => detailConnector(crudl.path._id).update(req),
delete: req => detailConnector(crudl.path._id).delete(req),
},
// Either fields or fieldsets
fields: [],
fieldsets: [],
// Optional
tabs: [],
normalize: (data) => { },
denormalize: (data) => { },
validate: function (values) { },
}
Both the REST and GraphQL API is only accessible for logged-in users based on TokenAuthentication. Besides the Token, we also return an attribute info in order to subsequently have access to the currently logged-in user (e.g. for filtering). The info is exposed in the global variable crudl.auth
.
The REST login connector looks like this:
const login = createExpressConnector('login/')
.use(transformData('create',
data => ({
requestHeaders: { "Authorization": `Token ${data.token}` },
info: data,
})
))
With Entries, the Categories depend on the selected Section. If you change the field Section, the options of field Category are populated based on the chosen Section due to the watch method.
{
name: 'category',
field: 'Autocomplete',
onChange: [
{
in: 'section',
setProps: (section) => {
if (!section.value) {
return {
readOnly: true,
helpText: 'In order to select a category, you have to select a section first',
}
}
// Get the catogories options filtered by section
return options('categories', '_id', 'name')
.read(crudl.req().filter('section', section.value))
.then(({ options }) => {
if (options.length > 0) {
return {
readOnly: false,
helpText: 'Select a category',
options,
}
} else {
return {
readOnly: true,
helpText: 'No categories available for the selected section.'
}
}
})
}
}
],
}
You can use the same syntax with list filters (see entries.js).
There are a couple of foreign keys being used (e.g. Section or Category with Entry) and one many-to-many field (Tags with Entry).
{
name: 'section',
label: 'Section',
field: 'Select',
lazy: () => options('sections', '_id', 'name').read(crudl.req()),
},
{
name: 'category',
label: 'Category',
field: 'Autocomplete',
actions: {
select: req => options('categories', '_id', 'name')
.read(req.filter('idIn', req.data.selection.map(item => item.value).toString()))
.then(({ options }) => options),
search: (req) => {
return options('categories', '_id', 'name')
.read(req.filter('name', req.data.query).filter('section', crudl.context('section')))
.then(({ options }) => options)
},
},
},
{
name: 'tags',
label: 'Tags',
field: 'AutocompleteMultiple',
required: false,
showAll: false,
helpText: 'Select a tag',
actions: {
search: (req) => {
return options('tags', '_id', 'name')
.read(req.filter('name', req.data.query.toLowerCase()))
.then(({ options }) => options)
},
select: (req) => {
return options('tags', '_id', 'name')
.read(req.filter('idIn', req.data.selection.map(item => item.value).toString()))
.then(({ options }) => options)
},
},
}
The descriptor Links is an example of related objects which are assigned through an intermediary table with additional fields.
changeView.tabs = [
{
title: 'Links',
actions: {
list: (req) => links.read(req.filter('entry', crudl.path._id)),
add: (req) => links.create(req),
save: (req) => link(req.data._id).update(req),
delete: (req) => link(req.data._id).delete(req)
},
getItemTitle: (data) => `${data.url} (${data.title})`,
fields: [
{
name: 'url',
label: 'URL',
field: 'URL',
link: true,
},
{
name: 'title',
label: 'Title',
field: 'String',
},
{
name: '_id',
hidden: true,
},
{
name: 'entry',
hidden: true,
initialValue: () => crudl.context.data._id,
},
],
},
]
- The actions
list
,add
,save
anddelete
follow the same logic as the corresponding actions of list, change and add views. getItemTitle: (data) => <string>
defines the displayed title of the item form. If it is not provided, then the value of the first field is used (in this case it would be the URL value).- It's typical for the tab views to make use of hidden fields to include the related object's id in the form data.
With Entries, we set the owner to the currently logged-in user with denormalize:
var addView = {
denormalize: (data) => {
/* set owner on add. alternatively, we could manipulate the data
with the connector by using createRequestData */
if (crudl.auth.user) data.owner = crudl.auth.user
return data
}
}
With Users, we add a custom column full_name with the listView:
var listView = {
normalize: (list) => list.map(item => {
item.full_name = <span><b>{item.last_name}</b>, {item.first_name}</span>
return item
})
}
We have added a custom component SplitDateTimeField.jsx (see admin/fields) in order to show how you're able to implement fields which are not part of the core package. Usage example:
// See users.js (in both examples)
{
name: 'date_joined',
label: 'Date joined',
field: SplitDateTimeField, // Custom component
getTime: (date) => {...}, // getTime is a required prop of SplitDateTimeField
getDate: (date) => {...}, // getDate is a required prop of SplitDateTimeField
},
You can set initial values with every field (based on context, if needed).
{
name: 'date',
label: 'Date',
field: 'Date',
initialValue: () => formatDate(new Date())
},
{
name: 'user',
label: 'User',
field: 'hidden',
initialValue: () => crudl.auth.user
},
Validation should usually be handled with the API. That said, it sometimes makes sense to use frontend validation as well.
{
name: 'date_gt',
label: 'Published after',
field: 'Date',
/* simple date validation */
validate: (value, allValues) => {
const dateReg = /^\d{4}-\d{2}-\d{2}$/
if (value && !value.match(dateReg)) {
return 'Please enter a date (YYYY-MM-DD).'
}
}
},
{
name: 'summary',
label: 'Summary',
field: 'Textarea',
validate: (value, allValues) => {
if (!value && allValues.status == 'Online') {
return 'The summary is required with status "Online".'
}
}
},
In order to validate the complete form, you define a function validate with the changeView or addView:
var changeView = {
path: 'entries/:_id',
title: 'Blog Entry',
actions: { ... },
validate: function (values) {
if (!values.category && !values.tags) {
return { _error: 'Either `Category` or `Tags` is required.' }
}
}
}
With Entries, we added a custom column to the listView based on the currently logged-in user.
var listView = {
path: 'entries',
title: 'Blog Entries',
actions: {
/* here we add a custom column based on the currently logged-in user */
list: req => entries.read(req).then(results => results.map(item => {
item.is_owner = crudl.auth.user === item.owner
return item
}))
},
}
listView.fields = [
{ ... }
{
name: 'is_owner',
label: 'Owner',
render: 'boolean',
},
]
The listView supports ordering by multiple columns (see entries.js).
Filtering is done by defining fields with listView.filters (see entries.js). You have all the options available with the changeView (e.g. initial values, field dependency, autocompletes, ...).
You can only change the password of the currently logged-in User (see views/users.js)
- Sorting with MongoDB is case sensitive. With aggregation, it is possible to implement case-insensitive sorting.
- Searching is only possible on one field per ressource (this is an API limitation). If someome comes up with a decent solution on searching within multiple fiels (including nested fields), please let us know.
CRUDL and crudl-example-express is written and maintained by vonautomatisch (Patrick Kranzlmüller, Axel Swoboda, Václav Pfeifer-Mikolášek).