Sample Applications

A look at some of the applications we’ve built for PDX CitySync, to give you some reference in building your own.

Sample App: Local Schools

Overview

As an example, we’ll take a look at the Local Schools app currently on the PDX CitySync website. This particular app is made with a combination of PHP and jQuery, but the principles will be the same no matter what language you choose to develop in.

App Structure

First, let’s look at the app’s directory structure:

Local Schools app directory

This app is constructed in a very informal MVC fashion. The index.php file accepts the app’s context, or region, passed to it by PDX CitySync, and routes the display accordingly. The views directory contains one file for each view, but the links to the app’s stylesheet and PDX CitySync js file are only called once in the index. If you’d like to take a moment to see how the views are set up, browse the source code on github.

The first page to load, index.php, is where we include the PDX CitySync App Core JS:

<script type="text/JavaScript" src="http://pdxcitysync.org/apps/citysync-app.js">

We'll also call the PDX CitySync JS SDK method init() here, passing our appID and appURL to authenticate and initialize our app:

<script type="text/JavaScript">
    
    // Initialize the app
    var init = CitySync.init({
        appID:'1234',
        appURL:'http://path-to-your-app'               
    });
    
</script>
                

The index.php file also has a simple block of PHP to grab the GET variable 'region' and route the view:

<?php 

    $region = $_GET['region'];  
    
    switch($region){
        case('center'):
            include('views/center.php');
            break;
        case('sidebar'):
            include('views/side.php');
            break;
        case('full'):
            include('views/full.php');
            break;
    }
    
?>
                

Data Sources

The Local Schools app makes use of open data from the Oregon State Board of Education, made available through the CivicApps API, also from the eGovernment Team, City of Portland, OR. Other data sets currently available through the API include new business licenses and employment data, with more to come later. You can learn more by browsing the CivicApps API documentation.

Views and Frame Resizing

Let's take a quick look at the application's simplest display, sidebar.php in views.

sidebar.php

<div class="widget-side">

    <div id="cs-schools-news">
        Loading news...
    </div>
    
    <div id="cs-schools-events">
        Loading events...
    </div>    

</div>

<!-- Apps JS -->
<script src="libs/js/schools.js" type="text/JavaScript"></script>
<script src="libs/js/ui.js" type="text/JavaScript"></script>

<script type="text/JavaScript">
    $(function(){
        
        var newsFeed = 'http://www.pps.k12.or.us/news/feed.xml',
            eventsFeed = 'http://www.trumba.com/calendars/ppss_calendar.rss';
        
        // These functions are a part of schools.js
        getRSSfeed(newsFeed, "news");
        getRSSfeed(eventsFeed, "events"); 
            
    });
</script>
            

The most simple view in the app simply grabs the RSS feeds for Portland Public Schools events calendar and news, parses them, and displays them in the .widget-side div. The getRSSFeed() function is app-specific and not a part of the PDX CitySync SDK.

center.php

<script type="text/JavaScript" src="libs/js/schools.center.js"></script>
<div class="widget-center">
    <h3>Browse data for schools in your neighborhood.</h3>
    <div id="type-selection">
        <label for="type">Show me:</label>
        <select id="type" id="type">
            <option value="e">Elementary Schools</option>
            <option value="m">Middle Schools</option>
            <option value="hsg">High Schools</option>
        </select> 
    </div>
    <div id="range-selection">
        <label for="range">Within:</label>
        <select id="range" id="range">
            <option value="1">Walking</option>
            <option value="5">Biking</option>
            <option value="20">Driving</option>
        </select> 
        <span class="after-label">distance.</span>
    </div>
    <div id="submit-button">
        <p class="button">Search</p>
    </div>
</div>
            

This view presents a widget which takes advantage of the user data, allowing them to search for schools by type, and filtered by radius in miles, centered around the user's location. This allows the user to quickly compare local schools, and provides links to the app's full view, where the user can see the complete performance data for the selected school.

When the list of schools is returned and displayed, the app calls CitySync.resizeFrame(), which sends a request to adjust the height of the widget to display the new data. You can call this at any time to resize your app's iframe as needed.

CitySync.resizeFrame(document.body.scrollHeight);
            

This view also contains an example of how to pass data from a widget to your app's full view page:

<a href="http://dev.pdxcitysync.org/app/6842?appvars=schoolID-841">César Chávez K-8 School</a>

The GET variable appvars is used to pass data from a widget to your app's full page view. Here the data, schoolID-841 is sent, and parsed by the full app's JavaScript. You can pass data through appvars however you'd like, as long as you can parse it in your full application.

full.php

This view represents the application's full view. This view mostly contains the HTML layout for the data to be plugged into once retrieved via the app's JavaScript. It first fetches a full list of schools in the Portland area, presented to the user as a drop down. Once the user selects a school, it fetches the data from the API by school ID, and parses the JSON response for display. It also retrieves news and events from the Portland Public School's RSS feeds.

Source Code

The full source for this app is available on the City of Portland's eGovernment Team repo on GitHub for download.

Return Home.