Home
shotgun-client is a plugin for node-shotgun that allows creation of real-time web consoles that communicate with the shotgun shell on the server.
_NOTE: shotgun-client 4.0.0 and higher now uses a new asynchronous model allowing for a more intuitive API. This document has been updated to reflect the changes to the API. Version 4.0.0 and higher is no longer compatible with previous versions.
Looking for the main shotgun wiki?
npm install shotgun-client
Using the client couldn't be easier. All it takes is some minor configuration on the server and a script reference on the client.
Simple Http Server:
// app.js
// Create a simple http server.
var static = require('node-static'),
http = require('http'),
file = new(static.Server)('./public');
// Start the server and do things as you normally would.
var server = http.createServer(function (req, res) {
req.addListener('end', function () {
file.serve(req, res);
});
}).listen(1337, '127.0.0.1');
// Require shotgun and shotgun-client then create a new shell.
var shotgun = require('shotgun'),
shotgunClient = require('shotgun-client'),
shell = new shotgun.Shell();
// Use shotgun-client to wire up the server and the shell.
shotgunClient.attach(server, shell);
console.log('Server running at http://127.0.0.1:1337/');
If you'd like to see an example of shotgun-client running in an Express app then check out my example application. It's not really any different, but sometimes it helps to have a working example.
Client w/jQuery:
<html>
<head>
<title>shotgun-client demo</title>
<style type="text/css">
body {
color: #fff;
background-color: #000;
padding: 50px;
}
</style>
<script type="text/javascript" src="/scripts/jquery.js" />
<script type="text/javascript" src="/shotgun/shotgun.client.js" />
<script type="text/javascript">
$(function () {
$('body').shotgunConsole();
});
</script>
</head>
<body>
</body>
</html>
The included jQuery adapter is designed to get you up and running quickly. Just call .shotgunConsole() on any element and it will be instantly transformed into a simple console that communicates directly, in realtime, with your shotgun shell on the server. This is more for the user who wants some sort of admin interface for their website. If you want to create more than one console and have it tied to different shotgun shell instances then pass in an options object with a namespace property.
// server
var shotgun = require('shotgun'),
shotgunClient = require('shotgun-client'),
shell1 = new shotgun.Shell({ namespace: 'shell1' }),
shell2 = new shotgun.Shell({ namespace: 'shell2' });
shotgunClient.attach(server, shell1, shell2);
// client
$(function () {
$('div#shell1').shotgunConsole({ namespace: 'shell1' });
$('div#shell2').shotgunConsole({ namespace: 'shell2' });
});
If a namespace is not specified then it defaults to "shotgun". The JQuery adapter is convenient, but what if you want to do some additional work while letting it do it's usual thing? The adapter allows you to pass in a callback. This callback will receive both the data object from shotgun as well as the context object.
$('body').shotgunConsole(null, function (data, context, ui) {
// data - The object sent from the shotgun shell on the server.
// context - The context object shotgun is currently using.
// ui - An object containing references to each UI component making up the web console.
// These are already JQuery wrapped sets, hence the dollar sign prefix on the variables.
if (data.exit) {
ui.$console.slideUp('fast', function () {
ui.$console.empty();
});
}
});
In this example we checked data.exit and used the JQuery wrapped set for the entire console element to make the console element disappear. Here is a list of all the UI components:
-
$console- The original element you invoked the JQuery adapter on. The main container. -
$display- The element where lines of text are displayed. You can safely empty this element without breaking the web console. Just don't remove it. -
$cli- The textbox element where the user supplies input. -
$cliText- A SPAN tag just to the left of the$cli. By default it shows the angle bracket>, or if there is a passive context set it will display context information to the left of the bracket. -
$cliContainer- To help with alignment both$cliand$cliTextare nested within a container element. I'm not sure why you would need to access this element, but it's the final element that makes up the console so I exposed it here anyway just in case.
If you need something even more customized or simply don't want to use jQuery then it's still really simple. Just instantiate and use the client shell directly.
Client w/out jQuery
<html>
<head>
<title>node-client demo</title>
<style type="text/css">
body {
color: #fff;
background-color: #000;
padding: 50px;
}
</style>
<script type="text/javascript" src="/scripts/jquery.js" />
<script type="text/javascript" src="/shotgun/shotgun.client.js" />
<script type="text/javascript">
var clientShell = new shotgun.ClientShell();
clientShell.onData(function (data, context) {
console.log(data);
console.log(context);
}).execute('help');
</script>
</head>
<body>
</body>
</html>
The vanilla client also accepts an options object. You can specify a namespace the same way we have everywhere else.
var clientShell = new shotgun.ClientShell({ namespace: 'shell1' });
Note that you have access to clientShell.context but you don't have to worry about context storage. Shotgun-client already does this for you on the client side, ensuring that web users each have their own unique context. How awesome is that!?
However, if for some reason you do need to manipulate the context then you can access it via clientShell.context.