Customizing Ospriet

couch edited this page Apr 12, 2012 · 42 revisions

To properly customize Ospriet for your event, you'll need to create/edit these files:

application.js

In ospriet/app/config/application.js, you should specify your application and event/UI details.

Twitter

  twitter_app: {
      consumer_key:         'XXXXXXXXXXXXXXXXXXXXX'
    , consumer_secret:      'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
    , access_token_key:     'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
    , access_token_secret:  'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
  }

  , twitter_account: {
      id:           '495336570'
    , screen_name:  'dftg'
  }

All of these values for should come from creating your event's Twitter account/application.

Moderators

  moderators: [
    {
      id_str: '18644328'
    , screen_name: 'philcoffman'
    }
  ]

If you would like to add more than one moderator (the first defaults to the event's Twitter account), you may add them as objects to the moderators array. Moderators have the ability to elect submissions to the 'Current Pick' status by favoriting a submitted status. It is strongly advised to unfavorite a status when it is no longer the 'Current Pick' to ensure proper display in the UI. This oddity should be resolved in a future version of the app.

Blacklist

  blacklist: [
    {
      id_str: '5841'
    , screen_name: 'stirman'
    }
  ]

If you would like to block any specific users you fear may try to spam the event, you made add them as objects to the blacklist array. Any @-replies received from these users will not be posted to the event's account.

Site Details

  site: {
      raw_url:          'http://designfromthegut.com'
    , display_url:      'designfromthegut.com'
    , google_analytics: 'UA-XXXXXXX-X'
  }

Ospriet includes a special web view available at /display on your domain optimized for display on a projector or large screen. The colors are inverted with higher contrast, larger font sizes, and instructions for audience members on how to participate. Accordingly, you'll need to specify your site's full url in raw_url, along with a display URL in display_url for this view. Additionally, Ospriet supports Google Analytics for stats on site usage. Just specify google_analytics with your web property ID.

Event Details

  event: {
      title:        'Design from the Gut'
    , description:  'Debating whether research or intuition is a better approach to design should be a communal discussion.'
    , instructions: '<strong>Submit a question or comment by posting a tweet to <a href="https://twitter.com/intent/user?screen_name=dftg" title="Design from the Gut on Twitter">@dftg</a> via the button below. Review the submissions and favorite the ones you\'d like to see answered</strong>. The moderator will choose from the top picks.'
    , time:         'Friday, 3/9, 3:30p'
    , location:     'Ballroom BC &bull; ACC'
    , details_url:  'http://schedule.sxsw.com/2012/events/event_IAP11592'
  }

Most of these fields should be self-explanatory, but a few notes: event.title will be used on the page as the event title as well as in the <title> tag in the HTML. The event.description value should be a concise description of the event and will be used for the description meta element (<meta name="description" content="…">), as well as be prepended to the event.instructions value in the UI. The event.instructions value is generalized in the default configuration, but should indicate to audience members how to post their submissions. Additionally, you may use HTML in the any of these event fields.

Panelists

  participants: [
    {
        name:     'Phil Coffman'
      , title:    'Principal, Element'
      , twitter:  'philcoffman'
      , img_url:  'coffman.gif'
      , role:     'Moderator'
    }
    , {
        name:     'Bill Couch'
      , title:    'Software engineer, Twitter'
      , twitter:  'couch'
      , img_url:  'couch.gif'
      , role:     'Panelist'
    }
    ...
  ]

The index view of the site is designed to display images of up to five participants indicating each one's role in the event, current title, and Twitter account link. If you don't have or want to show the participants, or have fewer than five, you can adjust the CSS accordingly to optimize the presentation.

Sample fully-hydrated ospriet/app/config/application.js configuration

module.exports = {

  /* Application configuration */
  twitter_app: {
      consumer_key:         'XXXXXXXXXXXXXXXXXXXXX'
    , consumer_secret:      'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
    , access_token_key:     'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
    , access_token_secret:  'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
  }

  , twitter_account: {
      id:           '495336570'
    , screen_name:  'dftg'
  }

  , moderators: [
    {
      id_str: '18644328'
    , screen_name: 'philcoffman'
    }
  ]

  , blacklist: [
    {
      id_str: '5841'
    , screen_name: 'stirman'
    }
  ]
  
  /* Site/UI configuration */
  , site: {
      raw_url:          'http://designfromthegut.com'
    , display_url:      'designfromthegut.com'
    , google_analytics: 'UA-XXXXXXX-X'
  }

  , event: {
      title:        'Design from the Gut'
    , description:  'Debating whether research or intuition is a better approach to design should be a communal discussion.'
    , instructions: '<strong>Submit a question or comment by posting a tweet to <a href="https://twitter.com/intent/user?screen_name=dftg" title="Design from the Gut on Twitter">@dftg</a> via the button below. Review the submissions and favorite the ones you\'d like to see answered</strong>. The moderator will choose from the top picks.'
    , time:         'Friday, 3/9, 3:30p'
    , location:     'Ballroom BC &bull; ACC'
    , details_url:  'http://schedule.sxsw.com/2012/events/event_IAP11592'
  }

  , participants: [
    {
        name:     'Phil Coffman'
      , title:    'Principal, Element'
      , twitter:  'philcoffman'
      , img_url:  'coffman.gif'
      , role:     'Moderator'
    }
    , {
        name:     'Bill Couch'
      , title:    'Software engineer, Twitter'
      , twitter:  'couch'
      , img_url:  'couch.gif'
      , role:     'Panelist'
    }
    , {
        name:     'Naz Hamid'
      , title:    'Principal, Weightshift'
      , twitter:  'weightshift'
      , img_url:  'hamid.gif'
      , role:     'Panelist'
    }
    , {
        name:     'Laurel Hechanova'
      , title:    'Designer, Illustrator, Apocalypse OK'
      , twitter:  'hechanova'
      , img_url:  'hechanova.gif'
      , role:     'Panelist'
    }
    , {
        name:     'Jane Leibrock'
      , title:    'User Experience Researcher, Facebook'
      , twitter:  'fencebreak'
      , img_url:  'leibrock.gif'
      , role:     'Panelist'
    }
  ]
}

development.js + production.js

Ospriet is configurable for various server environments. In ospriet/app/config/ you'll find application.js and environment/. Inside the latter, you can include any number of environment configuration files (see bottom of page for experimental configuration ideas), but the defaults are development.js and production.js. The app defaults to environment/production.js if NODE_ENV is not set when starting the server. If you set NODE_ENV at start, the app will load the configuration file of the same name of the environment you specify. For example, starting your server with NODE_ENV=development node server.js will load environment/development.js which will extend the application.js configuration.

You may specify any key-value pairs you'd like in these files (useful if, for example, you'd like to use different event Twitter accounts in development and production), though you'll likely want to specify you database address and server port values separately.

Example environment/development.js

module.exports = {
    database: 'mongodb://localhost/database-name'
  , server_port: '3000'
}

If you'd like to use the same database address/server port in both development and production, you can specify the key-value pairs in just ospriet/app/config/application.js.

package.json

In package.json, you should specify your preferred subdomain and, if you choose, a custom domain for your site as noted by nodejitsu. If you'd like to setup a different start script, you'll also need to define that here. By default, it's set to server.js. You'll want to add key-value pairs to this file that look something like these:

  "subdomain": "fromthegut",
  "domains": [
    "designfromthegut.com"
  ],
  "scripts": {
    "start": "server.js"
  },

Run multiple events from one instance (EXPERIMENTAL)

Theoretically, this open configuration setup allows you to define multiple configurations for multiple events. If you wanted to run the app for several events on one deployed instance of the app, you'd simply need to empty the module.exports object in ospriet/app/config/application.js and fully define all of the configuration options in different environment configuration files. While this hasn't been tested, the ospriet/app/config/ directory in this scenario would look something like this:

routes.js
application.js
environment/
  sxsw-development.js
  sxsw-production.js
  jsconf-development.js
  jsconf-production.js
  aea-development.js
  aea-production.js

The configuration objects normally contained in application.js would each be individually defined in each file in environment/, and application.js would just contain module.exports = {}. When starting the app, you'd want to specify NODE_ENV as the name of the configuration you'd like to have the app use, e.g. NODE_ENV=jsconf-production node server.js.

Next: Testing Ospriet →