Skip to content
This repository has been archived by the owner on Jul 14, 2019. It is now read-only.

Home

Jump to bottom
Alex Ford edited this page Mar 3, 2014 · 17 revisions

shotgun-client

Dependencies Status NPM version

shotgun-client is a companion module for shotgun that allows creation of real-time web consoles that communicate with the shotgun shell on the server.

Looking for the main shotgun wiki?

Installation

npm install shotgun-client

Usage

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);
    }).resume();
}).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 into your shell instances and make the name unique for each instance.

// 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 and even provides access to the client shell instance directly if you need it:

var clientShell = $('div#console').shotgunConsole();

You can also access it via JQuery's data function once shotgunConsole has already been called:

var clientShell = $('div#console').data('clientShell');

The JQuery adapter also attaches a ui object to the client shell instance so you can access the HTML elements that make up the terminal generated by the plugin.

var userInput = clientShell.ui.$cli.val();

Note: ui is only available on the client shell if you've accessed the shell instance returned from the JQuery plugin. Manually creating shell instances on the client does not generate any UI-specific functionality; only the JQuery plugin does the extra work of creating a quick UI for you.

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 $cli and $cliText are 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.on('log', function (text, options) {
                console.log(text);
            }).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 can add your own handlers for contextChanged to the client shell and store the context object yourself, but out of the box the client shell will maintain a context internally that is unique to each page (even better than unique to each user so that the user can have multiple browser tabs open). How awesome is that!?

Clone this wiki locally