Skip to content

Dev_ChronoZoom Developer Guide

Jump to bottom
William French edited this page Mar 3, 2015 · 14 revisions

Introduction

This guide covers everything you need to know to install the ChronoZoom development environment tools, use GitHub to get ChronoZoom source code, and deploy ChronoZoom to an Azure hosted website.

If you are new to GitHub, we recommend reading Learning to use GitHub for ChronoZoom development for more information on setting up your source code repository.

Contents

Overview and Technology

ChronoZoom is a zoomable interactive timeline for all of history, which you can see at www.chronozoom.com.

Spending a few minutes on the Introductory Tour can give a great overview of why ChronoZoom's zoomable timeline can powerfully represent the vast expanse of time, and how humanity and recorded history is such an infinitesimally small part of the chronological clock.

Explore all of the past - from the Big Bang, to the dinosaurs, to ancient and modern history, or use ChronoZoom to create and share your own historical collections and content.

The site is open source and built on a Microsoft technology stack utilizing HTML5, with the interactive timelines using HTML5's canvas, LESS and CSS3, plus over 20,000 lines of custom object-orientated JavaScript using jQuery, as a rich single page JavaScript application (SPA) on the web client side.

The server side is written in C# and runs under .NET 4.0 with a thin ASP.NET MVC page framework, a RESTful JSON API using WCF, a data entity layer, and a back-end Microsoft SQL Server database. As such, the site is designed to run on a Microsoft web server (IIS or Azure) and utilizes an Azure Access Control Service to manage log-ins from Microsoft, Google or Yahoo accounts.

return to contents

Tools and Requirements

Required

Recommended

Optional

return to contents

Configure Web Essentials

Follow these steps to set the appropriate options for Web Essentials.

  1. In Visual Studio, click Tools, then Options.
  2. In the Options dialog, expand the Web Essentials node.
  3. Click the LESS item and set Compile files on save to True.
  4. Click the JavaScript item and set the following options to True:
    • Create source map files
    • Minify files on save

return to contents

Get the ChronoZoom Source Code

This section walks through the recommended steps for cloning the ChronoZoom GitHub repository.

  1. If you have not already done so, install Git for Windows and sign up for GitHub.

  2. The master branch is here: https://github.com/alterm4nn/ChronoZoom.

  3. Fork the repo by clicking Fork. For more information see Fork a Repo.

  4. Clone the fork to your local computer by running the following command:

    git clone https://github.com/[your-GitHub-ID]/ChronoZoom.git

    You now have your own fork of the ChronoZoom project.

  5. Navigate to the newly cloned directory.

    cd ChronoZoom

  6. Add a new remote for the master repository (alterm4nn) (in this guide our is called "blessed").

    git remote add blessed https://github.com/alterm4nn/ChronoZoom.git

  7. To view your remotes and their associated URLs, use the git remote command:

    git remote -v

return to contents

Workflow Overview

This section describes a recommended workflow for working on features and bug fixes.

Get the Latest Version

  1. First, get the latest version of the code from the upstream repository ('blessed'). It is a good habit to do this on a regular basis.

    git checkout master
git pull blessed master

Create a Topic Branch

  1. For each feature or bug fix you are working on, create a topic branch (also known as a feature branch). Topic branches are typically lightweight branches that you create locally and that have a name that is meaningful for you. Make all of your changes in the topic branch, and consider the master branch to be an "untouched" master that can be updated to get the latest changes with git pull.

  2. Use the git checkout command to create, and then switch to, a topic branch:

    git branch branch_name
git checkout branch_name

Save your Changes

  1. Save a set of changes locally by using the git commit command. If you have added any new files, you'll need to add those first using the git add command.

    git commit -a -m "A description of the code changes I have just made."

  2. Save your changes to your git remote by using the git Push command.

    git push origin branch_name

    This will create a new branch named 'branch_name' on your git remote, and copy all of your changes to that branch.

Make a Pull Request

  1. Switch to your master branch and get the latest version.

    git checkout master
git pull blessed master

  2. Change back to your topic branch and merge with the master branch.

    git checkout branch_name
git merge master

  3. Resolve any conflicts that arise.

  4. Build the project! This is important, since the build process compiles the various individual JavaScript files into one large file which is used in production. This composite file MUST be part of the check-in.

  5. Push your changes to your repo.

    git push origin branch_name

  6. Go to your GitHub repository and create a pull request. This will alert Alterm4nn or other ChronoZoom project gatekeepers that you have made changes which must be reviewed.

    IMPORTANT: Any further checkins you make to the branch will automatically be included as an update to your pull request. If you have more work to check in that should not be included in the pull request, create a new topic branch to work in, and submit a new pull request later. If the pull request is not accepted and you need to make some minor changes, you can submit those on the original branch to update the pull request.

Best Practices

  • Always build the project before pushing your changes.
  • If you add a new JavaScript file, update \Source\Chronozoom.UI\Merge.cmd to include the new file. This file is used by the build process to combine all JavaScript source files at build time.
  • Do not make changes to the master branch. Instead, create a topic branch for each feature or bug fix you are working on.
  • Always merge your topic branch with the master branch BEFORE submitting a pull request. If you get a change conflict warning then the following may help:
  • If you have made a lot of commits, consider rebasing to squash a long list of commits into a single commit. This will make it easier for code reviewers to review your code.
  • If you've made a lot of changes and are still unfinished, you might want to check in each time you've finished a sub-task of your work, both as a back-up, and so you can more easily delineate each logical part in a different check-in note. This can also be useful if you use multiple workstations, or want to give someone else access to look at, pull or test a work in progress.

Helpful Git Resources

If you're new to Git, there is a bit of a learning curve. Here are some helpful links:

return to contents

Create Databases for Testing and Development

ChronoZoom requires Microsoft SQL Server (2012 or 2014), which can be installed on a server or workstation, or hosted on Azure. Developers should create a local database for daily development, and an Azure database for testing. The local database offers better performance, and it is easier to use from SQL Server Management Studio. An Azure database is required for testing, since ChronoZoom uses an Azure database in its production environment. Testing with an Azure database is critical, since it is possible for code that runs perfectly with a local database to fail with an Azure database. Some key differences include the following:

  • You need to use the full WITH (NOLOCK) locking hint syntax, rather than just (NOLOCK).
  • You cannot specify a partition in your scripts (this makes sense for a cloud-based solution).
  • Most stored procedures that are built in to other editions aren't available on the Azure platform.

Read more about Azure SQL Guidelines and Limitations.

Install SQL Server on a Workstation

ChronoZoom can be run with the following SQL versions:

You can also use SQL Server Express LocalDB, which lets you use a specified file as the database, but does not provide the management tools. SQL Server Compact Edition (CE) has been deprecated in the ChronoZoom project due to the large number of syntax differences between this edition and others.

Install SQL Server on Azure

There are no special requirements for ChronoZoom, so choose whichever options are appropriate for your circumstances (for example, hosting in a geographic region close to where you or your users reside).

Create and Populate a New ChronoZoom Database

You can create a local database for development work on your local computer. To do this, update your web.config with a connection string named "Storage", pointing to a blank SQL database named "ChronoZoom". Upon launch, ChronoZoom will create a schema and populate the database with content including ChronoZoom's Cosmos ("Big History") collection from December 2014.

TIP: If you add the Initial Catalog parameter to your connection string, ChronoZoom will automatically create the database for you.

  • Add a connection string called "Storage" in web.config. The following example connection string will create a new database called "ChronoZoom" for a named instance called "MyInstance":

    <add name="Storage" connectionString="Data Source=.\MyInstance;Initial Catalog=ChronoZoom;Trusted_Connection=True" providerName="System.Data.SqlClient" />

    If you are not using a named instance, point to 127.0.0.1:

    <add name="Storage" connectionString="Data Source=127.0.0.1;Initial Catalog=ChronoZoom;Trusted_Connection=True" providerName="System.Data.SqlClient" />

    For more details about connecting to a SQL database, refer to the example connection strings in web.config, or consult connectionstrings.com.

Notes:

  • You can use the following SQL query to get the physical location of all SQL database files (and log files) on your local computer: SELECT name, physical_name AS current_file_location FROM sys.master_files
  • If you are running an Azure website, you can omit the connection string from web.config, and instead place the value in Azure's website configuration panel. This is a more secure option since your connection string does not need to be checked-in.

Reset a ChronoZoom Database

If you need to "reset" your database later, to zap all of its contents, you can either delete and then create a new empty database, (recommended except on Azure,) and restart ChronoZoom, or you can run the following SQL script against your Azure database: Chronozoom.Entities\SQL\UtilityScripts\DropTablesAzure.sql.

Customize the Featured Content Tiles

Because the newly created database will only have one of the collections that appears in the Featured Content tiles, only the first two features content tiles will work. You can edit your web.config to point to a different list of featured items if this is the case. This is only necessary if your instance of the database is for production use. See the FeaturedContentListLocation appKey setting, which points to a JSON file that provides a static list of featured items.

return to contents

Set up Access Control Service

You only need to set up an Access Control Service (ACS) if users will be logging in to ChronoZoom. Logging in lets users bookmark favorites, create their own custom content, and edit edit content created by others (the content owner must explicitly add users to the list of editors for each collection).

The ACS lets users use their Microsoft, Google, and Yahoo credentials to log in to ChronoZoom. ChronoZoom does not store or have access to these credentials. Instead we hand over to the appropriate Microsoft, Google, or Yahoo site to handle the log in, and then users are redirected back to ChronoZoom, once logged in.

Even if your website and database are not on Azure (for example if you are developing on a local workstation with a local database), you can still use the Azure ACS.

IMPORTANT: You will need to create a Microsoft Azure account to use an Azure ACS (or any Azure services).

Create a new ACS

  1. Go to the Azure Management Console at https://manage.windowsazure.com/.

  2. In the lower left corner, click the + NEW button.

  3. Click APP SERVICES, then click ACTIVE DIRECTORY.

  4. Click ACCESS CONTROL, then click QUICK CREATE.

  5. Enter a value for Namespace, and select the appropriate region.

  6. Click CREATE.

  7. Follow the steps in Configure an ACS to add the ACS to your web.config, add identity providers, and set additional options for the ACS.

Configure an ACS

First, follow these steps to update your web.config.

  1. Open web.config for editing.
  2. Search for cz-nodelete-chronozoom-test.accesscontrol.windows.net.
  3. Replace each occurrence with the name of your ACS. For example cz-demo.accesscontrol.windows.net.

Next, work through the ACS configuration pages in the following order:

Add identity providers

When you first create an ACS, the Windows Live ID provider is already set up. Follow these steps to add additional identity providers (Google and Yahoo are recommended) to the list. If you're just adding a new site's domain name to an pre-existing ACS, you can skip this section.

IMPORTANT: You may not be able to set up Google logins with ChronoZoom at this time. This temporary issue is because the Google API which is currently in use, has been deprecated. The ChronoZoom dev team is working on a fix. Microsoft and Yahoo logins are unaffected.

  1. Follow the steps in Manage an ACS to open the Access Control Service page.
  2. In the left pane, click Identity providers.
  3. At the top of the screen, click Add.
  4. Check the radio button for the provider to add, then click Next.
  5. Click Save to save your changes.

Add rule groups

If you have created a new ACS, you will need to add a rule group. If you're just adding a new site's domain name to an pre-existing ACS, you can skip this section.

  1. If you haven't already done so, follow the steps in Add identity providers to add one or more providers.
  2. Follow the steps in Manage an ACS to open the Access Control Service page.
  3. In the left pane, click Rule groups.
  4. At the top of the screen, click Add.
  5. Pick "Add", and give your new rule group the following name: Default Rule Group - Microsoft, Google, Yahoo.
  6. Click Save.
  7. At the bottom of the main page, click Generate.
  8. Check all three boxes (Windows Live ID, Google, Yahoo!).
  9. Click Generate to generate the rules. Once rules have been generated, you will not need to customize them.
  10. Click Save to save your rule group.

Add certificate thumbprint

Follow these steps to add the X.509 certificate GUID to web.config.

  1. Follow the steps in Manage an ACS to open the Access Control Service page.
  2. In the left pane, click Certificates and keys.
  3. Next to the X.509 certificate, click Service Namespace.
  4. Under Certificate, copy the Thumbprint GUID.
  5. Open web.config and search for thumbprint="".
  6. Paste the GUID into both locations.
  7. Save the changes to web.config.

NOTE: If you have created a new ACS, the certificates and keys are already set up and should be good for one year. If this is a pre-existing ACS, it is worthwhile to check the expiration for the certificates, and renew them if they are set to expire soon. The process for doing this is outside the scope of this documentation. For further details, see Certificates and Keys Management Guidelines.

Add relying party applications

Follow these steps to add a URL for each website that will use the ACS. Note that all associated URLs must be present, including those for local dev/test sites (for example http://localhost:4949).

  1. Follow the steps in Manage an ACS to open the Access Control Service page.

  2. In the left pane, click Relying party applications.

  3. At the top of the Relying party applications page, click Add. The Add Relying Party Information page will appear.

  4. If you are adding a new relying party application, select Enter settings manually under Mode.

  5. Fill in the Name, Realm, Return URL and Error URL. Make sure your settings are identical to the following example URLs (substitute localhost:4949 with your own domain name):

  6. Copy the Realm URL to the clipboard.

  7. Set any other appropriate options (for example you could specify a longer token lifetime).

  8. Click Save.

  9. Add the Realm URL to the audienceUris list in web.config. For example:

    <audienceUris>
    <add value="http://www.chronozoom.com/"  />
    <add value="http://test.chronozoom.com/" />
    <add value="http://localhost:4949/"      />
</audienceUris>

  10. Save your changes to web.config.

  11. Repeat these steps to add other URLs to the list.

Application integration

Follow these steps to get the connection strings for your relying party applications, and add them to web.config. Prior to taking these steps you will need to take the steps to add relying party applications.

  1. Follow the steps in Manage an ACS to open the Access Control Service page.

  2. In the left pane, click Application integration.

  3. Click Login Pages.

  4. Select a relying party application from the list.

  5. Click the Download Example Login Page button and save the file to your computer.

  6. Open the file using Google Chrome (IE will not work for this part). The page will look something like this:

    IMPORTANT: You don't need to actually log in!

  7. Press F12 to open Chrome Developer Tools.

  8. Click Sources.

  9. Expand the xxx.accesscontrol.windows.net node until you see IdentityProviders.js.

  10. Click IdentityProviders.js to view the file (the URL cannot be opened directly).

  11. Copy the contents of IdentityProviders.js to your clipboard. It will be in the form of a compressed JSON string.

  12. Format the JSON so that it is readable. You can use an online tool such as JSON Formatter and Validator, or JSONLint. Alternatively you could use a tool such as Notepad++ in conjunction with the JSON Viewer plugin (add it using the Notepad++ plugin manager). Of course you are free to use any tool you like to do this.

  13. Open your web.config file.

  14. For each provider, copy the LoginUrl value and paste it into the appropriate SignInUrl* value in web.config. For example:

    <add key="SignInUrlMicrosoft" value=""/>
<add key="SignInUrlGoogle" value=""/>
<add key="SignInUrlYahoo" value=""/>

  15. If you get build errors, you may need to edit the string values to escape characters (for example, replace occurrences of & with &amp;).

NOTE: For improved security, if the web.config file is for an Azure-hosted site, you do not need to save any appSettings keys in web.config. Instead, enter them into the website's Azure control panel where they will override settings keys in web.config.

To get the ACS endpoint URL

  1. Follow the steps in Manage an ACS to open the Access Control Service page.
  2. In the left pane, click Application integration.
  3. Under Endpoint Reference there are several URLs. Copy the inner URL from the Management Portal reference: xxx.accesscontrol.windows.net where "xxx" is the namespace prefix for your ACS.

Manage an ACS

  1. Go to the Azure Management Console at https://manage.windowsazure.com/.
  2. In the left pane, click ACTIVE DIRECTORY.
  3. At the top of the screen, select ACCESS CONTROL NAMESPACES.
  4. Select the ACS you want to use, then click the MANAGE button at the bottom of the screen. This will open the Access Control Service page. Here you can configure all of the settings for the ACS.

return to contents

Deploy ChronoZoom to Azure

Why developers should test changes on Azure

During development, it is most convenient to use Visual Studio's web server to preview client-side changes. There is no reliance on remote publishing (a slow process), and you can quickly see the results of your changes by refreshing your browser. However, it is critical to test your changes on an Azure website prior to making a pull request. There are a number of potential issues that will only come to light while running on an Azure website. For example, the following C# code will prevent the successful publication of your website on Azure, since the name of the parameter in the triple-slash comment does not match the actual parameter name in the code:

/// <param name="collection">missing parameter indicates current collection</param>
public string GetTours(Guid collectionId)

This issue does not occur when publishing to a local IIS server. The only way to find it is to test on Azure. Any code that you submit must be runnable on Azure, since www.chronozoom.com runs on Azure, as do other versions of ChronoZoom at universities and museums.

A note about publishing from GitHub

Azure has a wonderful option to directly publish from GitHub, which can conveniently monitor for check-in changes. You can then set your database connection strings and app keys in Azure's website management panel (this keeps them from being published on GitHub, since ChronoZoom forks are publicly readable).

If your website uses Access Control Service to enable user sign-in, you will NOT be able to publish from GitHub. This is because of the additional web.config settings required by ACS.

Add a New Website

Follow these instructions to create a new Azure website.

  1. Login to Azure Management Portal.

  2. At the bottom of the page, click the + NEW bar and select the following options: Compute -> Web Site -> Custom Create

  3. In the Create Web Site dialog, fill in the fields as follows:

    • Url: Enter a name for your website (in this example the website name is mycz).
    • Region: Leave the default value.
    • Database: Select the Create New Sql Database option.
    • DB Connection String Name: Enter "Storage" (omit quotation marks).
    • Publish from Source Control: Checked
    • Click the arrow icon to go to page 2.

Specify Database Settings

Fill in the fields as follows:

  • Name: Enter "ChronoZoom" (omit the quotes).
  • Server: Select New SQL Database server. It's okay to select a pre-existing database if you have already created one.
  • Login name: Enter the user name for the database. In this example the user name is myDatabaseUsername.
  • Password: Enter the password for the database. In this example the password is myDatabasePassword.
  • Click the arrow icon to go to page 3.

Specify Source Control Settings

  • Source Control Type: Select GitHub.
  • **Repository Location **: Select Local Repository.
  • It is possible to set up continuous replication from GitHub here, however this example uses a local repository for simplicity. For more details about continuous replication, read this.
  • Click the arrow icon to go to page 4.

New user name and password (for Git)

  • Username: Enter a user name for Git. In this example it is myGitUsername.
  • Password: Enter a password for Git. In this example it is myGitPassword.

Go to Dashboard for Web Site

Add a connection to the Azure Web Site

Now you can make changes to the source code.

Publish your changes to the Azure Web Site

Open the Git command prompt and use the following command. You will be prompted for your Azure password.

  • git push --set-upstream azure master

NOTES:

  • This process copies a large number of files, so be patient. Do not attempt to view the website until all of the files have been copied.

  • If you receive the following error: Unable to rewind rpc post data - try increasing http.postBuffer, use the following command to increase Git's buffer size:

    git config http.postBuffer 210000000

Preview Your Site!

Browse to http://mycz.azurewebsites.net/ (substitute "mycz" with the name of your site) and behold your own copy of ChronoZoom! Your site URL is listed in the quick glance column of the Azure dashboard. For operational management details, see Chronozoom Operations Guide.

NOTES: If you get runtime errors (for example "Could not load file or assembly 'System.Web.Mvc' or one of its dependencies."), try the following:

  1. Open the ChronoZoom project in Visual Studio.
  2. Click Tools, NuGet Package Manager, then select Manage NuGet Packages for Solution....
  3. Reinstall the missing package(s) (Microsoft ASP.NET MVC in this example).
  4. If there are any other missing NuGet packages, install those as well (the NuGet Package Manager will display an error message to inform you if any packages are missing).
  5. Save your changes, rebuild the solution, and push the project to Azure.

return to contents

Configure an Azure web server

This section describes connection strings and AppKeys you should be aware of when configuring an Azure web server.

Connection Strings and AppKeys

The settings for connection strings and application keys are found in web.config, but if you are running an Azure website these settings can be entered in the site's management console. Some example connection strings are shown in web.config as comments. For further information, consult www.connectionstrings.com.

The key configurable AppKeys are:

FeaturedContentListLocation

Default value: "/featured/featured.json"

If you are making ChronoZoom available to users on a site other than www.chronozoom.com, you will need to change this to point to a different JSON file containing a list of the featured items for your website. You can use the existing default list as an example of how to structure your JSON file.

UseMergedJavaScriptFiles

Sets whether custom JavaScript is loaded in the client as individual files, or combined into one large file. For development, the former is preferable, making it easier to find code. For production (and therefore test as well) the latter is preferable as it is faster to load the code as a single file.

UseMinifiedJavaScriptFiles

Sets whether custom JavaScript is minified in the client. Since minified JavaScript loads faster it is preferred for production and testing. Non-minified JavaScript is easier to read, so it is suitable for development.

FederationMetadataLocation

Only required if users will log in to your site. Please see Set up Access Control Services for configuration details.

SignInUrlMicrosoft

Only required if users will log in to your site. Please see Set up Access Control Services for configuration details.

SignInUrlGoogle

Only required if users will log in to your site. Please see Set up Access Control Services for configuration details.

SignInUrlYahoo

Only required if users will log in to your site. Please see Set up Access Control Services for configuration details.

AzureMarketplaceAccountKey

Only required if users will log in to your site. Please see Set up the Bing Search API for details.

OneDriveClientID

Only required if users will log in to your site. Please see Set up Access Control Services for configuration details.

When logged in ChronoZoom users add content, they have the option of using their OneDrive account to select media content. In order to use OneDrive in ChronoZoom, you will need to register your website application. Note that each domain needs to have its own registration.

AnalyticsServiceId

If you have a Google Analytics account set up for your ChronoZoom website, you can enter the ID here. This should only be done for production sites, never for development or test sites. Azure also offers usage analytics.

Airbrake Keys

If you have a paid Airbrake account, then you can set up keys to log errors in JavaScript or C#.

  • To track C# errors, set Airbrake.TrackServer to True.
  • To track JavaScript errors, set Airbrake.TrackClient to True.

If you do not have an Airbrake account or do not want to use the feature, set both of these keys to False.

To identify which environment is reporting an error, set Airbrake.Environment to an appropriate value (for example "production").

SearchEngineIndexing

Sets whether search engines such as Bing or Google should index your site's contents. Set this to True for only production systems.

Possibly Defunct AppKeys

It appears that the following are no longer used and can likely be removed from the project:

  • ClientValidationEnabled
  • UnobtrusiveJavaScriptEnabled

return to contents

Set up the Bing search API

When logged in ChronoZoom users add content, they have the option of using Bing to perform a search for an image. In order to use the Bing Search API, you'll need an Azure Marketplace Account Key. This is free for up to 5,000 searches per month. In order to use the Bing Search API, you need to provide a Windows Azure Marketplace Account Key.

  1. Login to [Windows Azure Marketplace] (https://datamarket.azure.com).

  2. Subscribe to [Bing search API] (https://datamarket.azure.com/dataset/bing/search).

  3. Go to [Account Keys] (https://datamarket.azure.com/account/keys) in [My Account] (https://datamarket.azure.com/account).

  4. Create a new Account Key and copy it.

  5. In web.config file of Chronozoom.UI find

<add key="AzureMarketplaceAccountKey" value="" />

and paste your copied Account Key in value field.

IMPORTANT: Never share the default key. Instead, create a new one for use with ChronoZoom. If your key is compromized, delete it and create a new one. To keep your keys secret, DO NOT check in web.config edits!

return to contents

How to Document Code

When making additions to ChronoZoom code it may be necessary to add or update triple-slash documentation comments. Documentation is currently generated for the following classes:

  • Chronozoom.Entities
  • Chronozoom.UI

If you make any changes to any members in either of these classes, you will need to:

  1. Add new triple-slash comments or edit existing triple-slash comments according to your changes.
  2. Run the API doc conversion tool.
Clone this wiki locally