Middlebury

Library & ITS Wiki

Library & ITS Wiki

Kurogo

The Kurogo Framework is a PHP based web application that can help institutions efficiently deliver campus services and information to a wide array of mobile devices. Based on the MIT Framework, this open source project provides a modular way to present mobile versions of various data sources in an extendable, customizable fashion.

Kurogo is being used for our portal implementation.

At a high level, the Kurogo Framework includes:

  • A mechanism for detecting device characteristics and displaying content best suited for that device
  • A object oriented system for retrieving, parsing and displaying data from a variety of external sources
  • A robust templating system that utilizes themeable reusable parts to easily construct consistent user interfaces
  • A series of prebuilt, customizable modules for gathering directory, news and event information
  • A system of authentication and authorization for controlling access to content and administrative functions

Contents

Framework Documentation

Modules

For Launch

Other Ideas

  • Campus Map
  • Course Catalog
  • Course Hub
  • MiddLab
  • MiddSTART
  • MiddTube / MiddMedia
  • Weather

Feeds

FetchProxy

Module feeds should be run through our feed caching proxy, FetchProxy. This is done by calling http://fetchproxy.middlebury.edu/get.php and passing the URL in a URL parameter in the query string (?url=). The URL passed in the parameter should be raw URL encoded.

Here is an example of a feed.ini file:

[0]
TITLE              = "Featured News"
BASE_URL           = "http://fetchproxy.middlebury.edu/get.php?url=http%3A%2F%2Fpipes.yahoo.com%2Fpipes%2Fpipe.run%3F_id%3D1b67ebbeb540b8d778f162182e280320%26_render%3Drss"
SHOW_IMAGES=0

In order to raw URL encode your URL you can run PHP in command mode "php -a" and then print or echo the results of a rawurlencode() of your URL to place in your query string.

Example: print rawurlencode('http://google.com/');

User Specific Config Files/Committing Changes

We've coded our instance of Kurogo to load different configuration files based on the logged-in user. Logged-in user types are: student, faculty, and staff. A feeds.ini file can be followed by "-staff", "-student", or "-fac" to be loaded for that user-type in lieu of the default ini file.

The master branch should be considered to hold the "logged-in" ini files for students, fac, and staff for the various modules. Constituent pages, "students.middlebury.edu" etc... serve their content from the main feeds.ini file. The feeds-students.ini file on master branch should be kept in sync with the feeds.ini file on students branch for instance, so students see the same default items on the constituent page and when logged in.

Example: We want to change a feed for students. The change should be made to feeds-student.ini on master branch. Once committed, master should be merged into facstaff, and student branches. The change should also be made to feeds.ini on the student branch, and only committed to the student branch.

Read More/Leave Comments Links

The News module allows various options to be specified per feed. We've added an option for a link back to the comments form of a post. If this is unavailable, the link will provide a link back to the source article.

Example:

[0]
TITLE              = "Featured News"
BASE_URL           = "http://fetchproxy.middlebury.edu/get.php?url=http%3A%2F%2Fpipes.yahoo.com%2Fpipes%2Fpipe.run%3F_id%3D1b67ebbeb540b8d778f162182e280320%26_render%3Drss"
SHOW_COMMENTS_LINK = 1

Example: Comments link.png

See http://kurogo.org/docs/mw/current/modulenews.html for a full list of supported options.

Icons and Graphics

Icons for new modules need to be provided in vector graphic form so that they can be saved out at multiple sizes and formats.

To create a new icon:

  1. Copy the path in Adobe Illustrator
  2. Create a new document in Adobe Photoshop twice as large as the resultant graphic with a transparent background.
  3. Paste the path into Photoshop, being sure to choose Path in the "Paste As" dialog.
  4. Select all of the path objects, right click and select Free Transform Path.
  5. Resize the graphic to fill the available space.
  6. Click the Paths tab.
  7. Right click Work Path in the Paths tab and select Fill Path, choose the appropriate color and click OK. Make sure Anti-Aliasing is selected.
  8. Choose Image Size from the Image menu and resize the graphic to the desired dimensions.
  9. Choose Save for Web and Devices from the File menu and use one of these two options:
    1. For PNGs, save as PNG-24 with Transparency
    2. For GIFs, save as GIF 128 No Dither with Transparency

Icons should be saved in the following paths with these image dimensions, file type and color. The word "module" in the File Name should be replaced with the name of the module.

File Name Dimensions File Type Color
site/Middlebury/themes/default/common/images
compliant/title-module.png 56x56 PNG #071427
tablet/title-module.png 56x56 PNG #071427
tablet/pane-module.png 36x36 PNG #071427
touch/title-module.gif 28x28 GIF #071427
site/Middlebury/themes/default/modules/customize/images
compliant/module-tiny.png 30x30 PNG #071427
tablet/module-tiny.png 30x30 PNG #071427
site/Middlebury/themes/default/modules/home/images
compliant/module.png 100x100 PNG #73A2E6
compliant-bbplus/module.png 100x100 PNG #73A2E6
compliant-blackberry/module.png 100x100 PNG #73A2E6
tablet/module.png 72x72 PNG #FFFFFF
tablet/module-selected.png 72x72 PNG #071427
touch/module.gif 128x128 GIF #73A2E6
site/Middlebury/themes/default/module/info/images
icons/module.png 56x56 PNG #071427

Panels

When adding a new module that will appear on the Portals "panels", you'll also want to make sure to have an icon in:

site/Middlebury/themes/default/common/images
compliant/pane-module.png 36x36 PNG #071427

Additionally, add a line like this:

.modulename .blockheader .icon {
background-image: url(/common/images/pane-modulename.png);
}

to the CSS file

site/app/modules/home/css/compliant-computer.css

and to

site/app/modules/home/css/tablet-computer.css

if you are going to provide a pane view of the module for iPad.

Also, these image files have been modified from the distribution to be Middlebury-specific:

  • site/Middlebury/themes/default/common/images/compliant/help.png
  • site/Middlebury/themes/default/common/images/compliant/homelink.png
  • site/Middlebury/themes/default/common/images/compliant/icon.png
  • site/Middlebury/themes/default/common/images/compliant/search_button.png
  • site/Middlebury/themes/default/common/images/tablet/homelink.png
  • site/Middlebury/themes/default/common/images/tablet/icon.png
  • site/Middlebury/themes/default/common/images/touch/homelink.png
  • site/Middlebury/themes/default/modules/home/images/logo-home.gif
  • site/Middlebury/themes/default/modules/home/images/logo-home.png
  • site/Middlebury/themes/default/modules/info/images/logo-home.png
  • site/Middlebury/themes/default/modules/news/images/compliant/news-placeholder.png
  • site/Middlebury/themes/default/modules/news/images/tablet/news-placeholder.png
  • site/Middlebury/themes/default/modules/news/images/touch/news-placeholder.jpg

Development Workflow

Creating Your Development Site

  1. cd ~/public_html/
  2. git clone git@chisel.middlebury.edu:kurogo.git
  3. cd kurogo
  4. cp config/kurogo-default.ini config/kurogo.ini
  5. Edit config/kurogo.ini and set ACTIVE_SITE = “Middlebury"
  6. chmod -R 777 site/Middlebury
  7. cp /etc/httpd/conf.d/vhost-imcbride.conf /etc/httpd/conf.d/vhost-myname.conf
  8. emacs /etc/httpd/conf.d/vhost-myname.conf
  9. Edit the entry for mimcbride.middlebury.edu to a new virtual host for your development instance. Make sure to change the directory path and log file strings.
  10. service httpd restart
  11. Edit your HOSTS file to point the address for the virtual host you created in step 8 at chisel (140.233.2.189).

Edit only files in the site/Middlebury directory.

Use git push/pull to get updates of the Middlebury site as normal.

Fetching a New Version of the Kurogo Framework

  1. git checkout master
  2. git fetch kurogo
  3. git merge kurogo/master

Deploying a new site

These steps need to be applied to webtemplate, supersoaker, firehose, and watercannon.

  1. Set up the new instance of the code base
    1. cd /var/www/kurogo
    2. git clone git@chisel.middlebury.edu:kurogo.git site_name
    3. cd site_name
    4. git checkout site_name
    5. cp ../m.middlebury.edu/config/kurogo.ini config/
    6. mkdir site/Middlebury/cache
    7. chown -R apache:apache site/Middlebury/cache
    8. chown -R apache:apache site/Middlebury/data
    9. chown -R apache:apache site/Middlebury/logs
  2. Edit the server configuration
    1. Remove the section from /etc/httpd/conf.d/vhost.conf
    2. Add the section to /etc/httpd/conf.d/vhost-kurogo.conf
  3. Edit the deployment script
    1. Add the new site to /usr/local/bin/update_kurogo

Then restart apache on each server to bring up the new site.

Customizations

Customize Module

From the Kurogo documentation: "The customize module allows users to change the ordering or display of modules on your site’s home screen. The module uses cookies on the user’s browser to save the results, so the effects are limited to the user’s device/browser."

This is based on setting a disabled modules cookie and a module order cookie. Any modules in the disabled modules cookie are not shown.

Site Customize Module

Our Site Customize Module adds additional functionality.

It uses a separate set of navigation modules from the home/module.ini file, portal_primary_modules and portal_secondary_modules as opposed to primary_modules and secondary_modules, for the portal version so separate default navigation modules can be specified from the mobile version.

It also uses the following additions to the home/module.ini file:

  • "fixed_panels_1" and "fixed_panels_2" specify modules to appear at the tops of the two columns in the panel layout that are not customizable; you cannot toggle them on and off or reorder them.
  • "panels_1" and "panels_2" specify the default panels to appear in the first and second columns of the two column panel layout. These are customizable.
  • "available_panels" are all of the modules that are available to be enabled as panels. These will show up in addition to the default customizable panels as unchecked modules that can be checked and enabled for either or both of the two columns in the panel layout.

Example:

[fixed_panels_1]
featurednews = "Featurednews"

[fixed_panels_2]
calendar = "Events"

[panels_1]
news = "News"
video = "Video"
people = "Directory"

[panels_2]
dining = "Dining"
scoreboard = "Scoreboard"
links = "Links"

[available_panels]
news = "News"
video = "Video"
dining = "Dining"
scoreboard = "Scoreboard"
links = "Links"
stories = "Stories"
library = "Library"
emergency = "Emergency"
about = "About"
people = "Directory"

Any modules in the fixed panels should be removed from the available panels as they already appear by default and cannot be changed. If a module is removed from fixed panels it should be added to available panels if appropriate.

Powered by MediaWiki