admiraljs
v2.5.0
Published
Lightweight plug and play admin interface
Downloads
98
Maintainers
Readme
AdmiralJS 2.x Beta
Lightweight plug and play admin interface
http://www.admiraljs.com
github page: https://github.com/StudioDeTelevision/admiraljs
a web app for admin generation + a node server for api + file upload.
IRC:
server: irc.freenode.net
channel: #admiraljs
#ADMIRALJS is still in development. Any help is precious, please give feedback/bugs/requests at [email protected]
#NEW: EMBEDDED SCHEMA (see below)
Demo
About
AdmiralJS allows quick generation of an admin interface, letting you spend more interesting time on the design of the front end with your favorite framework.
- Customisable field editors for your models
- Instant admin generation from a schema.json
- That means you can change your models'structure on the fly ! (great for development)
- Pluggable on any CRUD or RESTFUL API (optimized for SailsJS)
- Written in javascript with requirejs / jquery / backbone
- Usable with the bundled server or as a standalone webapp
AdmiralJS was developped as a client-side webapp, to make it as much as possible independant from frameworks and platforms.
It can be used with its own api server developped with expressjs under node It can easily be used with SAILSJS under node (see SailsJS Configuration) It can also just be used as a standalone webapp, and you might provide your own api server, under node, or under apache with php or whatever.
Use it with its bundled express/node server
It maybe the simplest way to start. AdmiralJS comes as a nodejs module, offering a restful api server which can be used to manipulate your mongo database for your project.
Installation
** Requirements: **
** NodeJS **
** A mongo database to connect to **
sudo npm install admiraljs
var admiral=require('admiraljs');
admiral.setConfig(
{"projectName":"example",
api: {"database":{host:"your-mongodb-host-address",
name:"your-database-name"}
},
fileserver: {
uploadDir:__dirname+"/public"
}
}
)
admiral.start();
** Next Step ** configure the web application
Server Configuration Options
** webappPath ** you might want to change your webapp path...
** projectName ** must correspond to your configuration folder name inside the webapp // needed for security and overrides
** api ** You must specify your database connection settings / if not set won't run the api, maybe you'll prefer to use yours ?
api:{database:{host:"",name:"",username:"",password:"",port:27017}}
** fileserver ** if not set won't run the fileserver, maybe you'll want to use yours ?
** auth: ** false/true/{username:"AdminName",password:"whatever"}
true will use default login: {username:"admin",password:"admiraljs"} if you use auth, you must set auth:{mode:"ajax"} in the webapp config.json (see further)
- ** projectCustomPath ** /local/path/to/custom defines your own client config file path
will avoid you to make changes in the /nodes_modules/admiraljs/custom folder
Use it with SAILSJS
In order to correctly bind admiraljs model's relations with sails's (waterline), you need to use sail's restful api. Here's how to configure your sails project.
Sails server configuration
Add some blueprints override for pagination.
http://www.admiraljs.com/blueprints.zip
place it in your api folder api/blueprintsin config/cors.js set allRoutes: true and headers: 'content-type,Content-Disposition'
For auth and fileupload, documentation is coming ...
- to override sails bodyparser, create config/express.js with:
var express = require('sails/node_modules/express');
module.exports.express = { bodyParser: function() { return function (req, res, next){
if (!(req.path === '/upload' && req.method === 'POST')) { return express.bodyParser()(req, res, next); } else { return next(); }
} } }
Start AdmiralJS
var admiral=require('admiraljs');
admiral.start();
Configure AdmiralJS
in your custom/myproject/config/config.json :
{
"title":"LOKREMISE",
"recordID":"id",
"api":"http://yoursailsserver:sailsport/",
"fileUploadUrl":"http://yoursailsserver:sailsport/upload/",
"fileDir":"http://yoursailsserver:sailsport/files/",
"thumbDir":"http://yoursailsserver:sailsport/files/thumbnail/",
"orm":"waterline",
"login":{"mode":"fake"}
}
Use it with any other server
The webapp itself is located in the admiraljs subfolder, it can be easily extracted and started on any server that can serve an index.html file :)
See the configuration options below, to be able to plug it on any restful api.
If you want to develop your own api script, don't hesitate to contact me for mode details
Admiral Webapp Configuration
Configuration files must be set in the "Custom" folder
which will be reserved to all your project settings and hooks
maintaining the core of the app as cleaner as possible :-)
Let's choose a configuration name, "myproject"
Create a folder named "myproject" in "custom"
Create a subfolder named "config" in "myproject"
Create 2 configurations files schema.json and config.json ( See the related sections for creating those or make a copy of the example project )
2 ways to activate your configuration: in main.js, replace AJS.path.customFolder="example"; by AJS.path.customFolder="myproject";
OR start admiraljs with a config param: http://localhost:9999/admiraljs?config=myproject
Config.json
admiraljs/custom/myproject/config/config.json
It's just a JSON object that MUST BE SET, minimum with a "title" parameter
title: project title displayed in the top bar
debug(optionnal): true/false
recordID(optionnal): depending on your database can be "_id" or "id" or ...
api(optionnal): default configuration targets the bundled api on "http://localhost:9999/" , you might target yours
"fileUploadUrl(optionnal)": url for file upload, defaults to "http://localhost:9999/upload"
"fileDir(optionnal)": url for file reading, defaults to "http://localhost:9999/files/",
"thumbDir(optionnal)": url for file thumbnails reading, defaults to "http://localhost:9999/files/thumbnail/",
"login(optionnal)": {"mode":"ajax"} or {"mode":"fake"} , defaults to "fake" (fake mode will provide a fake login, with "admin/admin" credentials)
Schemas.json
admiraljs/custom/myproject/config/schemas.json
It's just a Array of schema definition objects [{...},{....}] that MUST BE SET IN ORDER TO EDIT SOMETHING FROM THE DATABASE :)
Live schema edition
You can edit your schemas.json file at runtime, using the params button in the bottom left corner. Changes will be applied to the current admiraljs instance running, but won't change the original schemas.json file - this has to be done manually.
Schema Object Structure:
**Example of a minimal "post" schema structure: **
{"schemaName":"posts",
"model":"posts",
"label":"My posts",
"listFields":["title","published"],
"fields":[{"name":"title","editor":"stringmultilangotf","label":"Title"},
{"name":"content","editor":"textareamultilangotf","label":"Content"},
{"name":"published","editor":"yesno","label":"Published"}]
}
schemaName , a name for your schema to make it unique in the running instance
model , the data model name to target
label , the name displayed in the sidebar
listFields , a array containing the names of the fields you want to be displayed in the list view.
fields , an array containing the description of your fields and their edition mode.
extends , name of the schema to extend (its "schemaName") , will extends an existing schema configuration
findFilter , default filter in the list view , can be a function if needed
"findFilter":function() { return {"sort":{ createdAt: 'asc'},"where":{"name":"kino","date_end":{'<': moment().format('YYYY-MM-DD HH:mm')}}} } },
type , for special schema types: multischema (see below) , abstract (see multischema paragraph) , normal (default)
**You can also specify custom crud routes with: **
find , url
create , url
update , url
destroy , url
Multischema Document Structure
Using the flexibility of mongo's document structure, you might want to use one data collection containing documents with different schema structure.
This is the purpose of the Multischema Object Structure.
Two different approach: SCHEMA DEFINED
- define some schemas and type them with "abstract". > ex: {"schemaName":"pageabout",
"type":"abstract",
"fields" : [ {"name":"title","editor":"stringmultilangotf","label":"Titre"},
{"name":"content","editor":"textareamultilangotf","label":"Contenu"},
{"name" : "video","editor" : "string","label" : "Video Vimeo ID"}]}
- define a schema with a "multischema" type and a "_schemaSchema" string field. > ex: {"schemaName":"mymultischema",
"type":"multischema",
"fields" : [ {"name":"_schemaSchema","editor":"string","label":"SchemaModel"}]}
as soon as you will have give a valid abstract schema name in a "mymultischema" document,
refresh the edit page and you'll be able to use your abstract schema for that document.
Two different approach: EMBEDDED SCHEMA
- just add the option: "editor":true to a schema definition, and a new field will appear in the edition page : SCHEMA - with its [edit] button. This will give you the ability to add any kind of fields in the current document.
Hooks and Customisation
The Custom folder is the place to add your own extensions data structure should be custom -> myproject -> editors custom -> myproject -> sidebar etc... to keep a clean code
At startup the admiral will try to load a index.js file located in:
custom/myproject/index.js
this file will load and trigger all hooks
it's a simple requirejs module
define([],function() {
var Custom;
// init your hooks
return Custom; } )
If you need to add custom editors, you could do:
define(["./editors/editors"],function() {
var Custom;
new Editors();
return Custom; } )
Then define your editors in a custom/myproject/editors/ folder
Ex: custom/myproject/editors/editors.js
define(["./import/import","./datetimearray/datetimearray",'./textareacounter/textareacounter'],function(Import,Datetimearray,TextAC) {
var MyClass=function() {
/// HERE THE EDITORS.JS WILL DECLARE THE CUSTOM EDITORS FOR USE IN YOURS PROJECT
/// THOSE MUST INHERIT FROM core/editor as a Backbone View: var View=EditorClass.extend({...
AJS.fieldClasses["import"]=Import;
AJS.fieldClasses["datetimearray"]=Datetimearray;
AJS.fieldClasses["textareacounter"]=TextAC;
}
return MyClass;
});
Themes
Field Editors
AdmiralJS provide some basic field editors but you can write and add your own by extending the core/editor module
Basic Editors
Located in the editors folder, those editors are used to defined the fields'edition strategies in schemas.json
###collection {"name":"myfieldnameindatabase",editor:"collection",relatedModel:"mySchemaModelName",label:"MyCollection"]}
###collectionembed
{"name" : "myfieldnameindatabase",
"type" : "collectionembed",
"schema" : {"listFields" : ["title"],
"fields" : [ {"name":"myfieldnameindatabase",editor:"string",label:"MyString"]},
{"name":"myfieldnameindatabase",editor:"string",label:"MyString"]}]},
"editor" : "collectionembed",
"label" : "MyCollection"
}
###date
###datetime
###file
###image
{"name":"src","editor":"image","label":"Image", "formats": {"normal": {"width": 400,"height": 300},"thumbnail": {"width": 84,"height": 84}}}
will upload the original image in the root folder, and create 2 versions for the 2 differents formats provided here. they will be located in subfolders corresponding to the format name. (normal and thumbnail)
###imagecropresize
{"name" : "myfieldnameindatabase",
"editor" : "imagecropresize",
"label" : "Image",
size:{"width" : 400,"height" : 300} // the final size
}
###imagedropdown
###imagescollection
###select {"name":"myfieldnameindatabase",editor:"select",label:"myfieldname",options:["bananas","potatoes","parrots"]}
###selectincollection
###string {"name":"myfieldnameindatabase",editor:"string",label:"MyString"]}
###stringmultilangotf
###textarea
###textareamultilangotf
###textareasimple
###yesno {"name":"myfieldnameindatabase",editor:"yesno",label:"ActiveStuff"]}
Edition View Templates
For certains project you might want to design some specific edition views for your admin users. In such a case admiraljs offers a little templating system.
Declare your template name for your model Schema, in the schemas.json
in Your custom Folder, from the index.js file, add html templates to AJS.templates['YOURTEMPLATENAME]=templateHTML;
the templateHTML is a text object (loaded via the requirejs text plugin for example) and that must contain place holders for your field. Place Holders must provide an "for" attribute with the name of your editable field. ex:
Better Documentation upcoming ...
Security
AdmiralJS provides 2 approches
1 For developement purpose, you can use a fake auth method. Set the server with auth:false and the webapp with auth:{mode:"fake"}
2 For production, you might use our minimalist security implementation based on PassportJS. Set auth:{username:"AdminName",password:"whatever"} on server side and auth:{mode:"ajax"} on client side
Issues, Contributions and Proposals
Please, post questions, proposals, bugs in the Issues on github.
https://github.com/StudioDeTelevision/admiraljs/issues
Please contribute and share your own field editor, themes etc...
Contact & Support
Frédéric Jean: [email protected]
http://www.studiodetelevision.com
Or send me a postcard here:
http://postcardify.com/[email protected]&name=Frédéric
IRC:
server: irc.freenode.net
channel: #admiraljs