Getting Started

An explanation of core concepts: authenticating your application, user data, display regions, and what's available to you via the JavaScript SDK.

To use the PDX CitySync Javascript SDK in your application, you’ll include the following line in your app’s main page:

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

This will also include the PDX CitySync Base CSS file for you as well, helping to maintain visual consistency between apps on the platform.

Connecting and User Data  

After you’ve included the PDX CitySync JavaScript SDK in your application, you’ll make a CitySync.connect() call once your page has loaded. This method accepts an optional callback function so that your application can continue once the connection is live, and the app and user data is available.

Here's a basic example:

$(function(){
    CitySync.connect(function(){
        // Continue with the application
    });      
});

Once the connection is established, the SDK returns a Javascript object, CitySync.appdata, with the following information:

  • fullurl: The path to your application’s full view page on PDX CitySync
  • catalogurl: The path to your application’s detail page in the PDX CitySync App Catalog

Your application will also have the following Javascript user object, CitySync.user, available:

  • interests: Comma-delimited string of user’s interests
  • location: Object with two variables, lat, and long.

Here's an example user data object:

CitySync.user = {
    interests: "Business, Sports, Outdoors",
    location{
        lat: 45.6012,
        lng: -122.757
    }
}

Display Regions

There are three regions, or contexts, your app will appear in on CitySync. CSS classes for these apps are included in the base stylesheet:

  • .widget-center - 528px wide center column in page templates
  • .widget-side - 230px wide sidebar column in page templates pages
  • .application - 735px full-width app page

When your app’s iframe is placed on the page, the app’s context is passed as a GET variable appended to the URL.

<iframe src="http://sample.com/path-to-app?region=center">

You can use this region variable to route the application’s display.

Passing Data

Currently the CitySync SDK has two methods available:

CitySync.resizeFrame(height)
Whenever your app or widget loads information, you can call resizeFrame to resize the iframe and avoid scroll bars in your display.

CitySync.sendAlert(alert) (not fully implemented yet)
Users have an area on their homepage dedicated to various alerts. Your application can use PDX CitySync’s alert framework to send messages to this area to alert the user to updates, special announcements, or other alerts your application might provide.

In situations where you need to pass data between a center or sidebar widget and your application’s full view, you can append the data onto the end of your app’s fullurl in the variable ‘appvars’. The following is an example from our the Local Schools sample application:

<a href="/app/6842?appvars=schoolID-832">View full</a>

The appvars data will be passed to your application as a string, and will be available for you to transform into usable variables for your code.

Continue reading Building & Submitting Your App