ChronoZoom Wiki Rss Feed

Updated Wiki: Home

Pax_Equus — Wed, 24 Apr 2013 00:12:00 GMT

See ChronoZoom on Github for source code and bugs, and ChronoZoom on Trello for feature planning.

Welcome to ChronoZoom
ChronoZoom is an open source community project dedicated to visualizing Big History that has been funded and supported by Microsoft Research Connections in collaboration with University California at Berkeley, University of Washington and Moscow State University.

Please be advised that this project is no longer active on CodePlex.
ChronoZoom has been moved to Github: https://github.com/alterm4nn/ChronoZoom

Updated Wiki: How to be a Developer on ChronoZoom

Pax_Equus — Wed, 24 Apr 2013 00:03:32 GMT

ChronoZoom is an open source project. Our team welcomes you support to make ChronoZoom a better, more exciting product.

Please be advised that this project is no longer active on CodePlex.
ChronoZoom has been moved to Github: https://github.com/alterm4nn/ChronoZoom

You can go to Github and contribute, we look forward to seeing you!

Updated Wiki: Home

Pax_Equus — Wed, 24 Apr 2013 00:00:01 GMT

See ChronoZoom on Github for source code and bugs, and ChronoZoom on Trello for feature planning.

Please be advised that this project is no longer active on CodePlex.
ChronoZoom has been moved to Github: https://github.com/alterm4nn/ChronoZoom

Updated Wiki: Documentation

Pax_Equus — Tue, 23 Apr 2013 23:50:35 GMT

Please be advised that this project is no longer active on CodePlex.
ChronoZoom has been moved to Github: https://github.com/alterm4nn/ChronoZoom

Updated Wiki: Home

altermann — Mon, 22 Apr 2013 20:09:50 GMT

See ChronoZoom on Github for new development and ChronoZoom on Trello for our plans for the future.

Project Overview
ChronoZoom is an intuitive on-line tool used to visualize all of time, from the Big Bang to today, using the concept of zooming along the timeline to express distance to highlight the scope of time.

When you see ChronoZoom zoom from the Industrial Revolution all the way back to the Big Bang, you can visualize time in a new way. You can browse through history on ChronoZoom to find data in the form of articles, images, video, sound, and other multimedia. ChronoZoom links a wealth of information from five major regimes that unifies all historical knowledge collectively known as Big History.

The regimes of Big History are:

Cosmos
Earth
Life
Human Pre-History
Human History.

By drawing upon the latest discoveries from many different disciplines, you can visualize the temporal relationships between events, trends, and themes. Some of the disciplines that contribute information to ChronoZoom include biology, astronomy, geology, climatology, prehistory, archeology, anthropology, economics, cosmology, natural history, and population and environmental studies.

ChronoZoom is a collaborative effort of the Department of Earth and Planetary Science at UC Berkeley, Microsoft Research, and originally Microsoft Live Labs.

Detailed Project Description
The last 20 years has seen the emergence of a new discipline invented by the Australian historian, David Christian, called Big History. The aim of Big History is to unify all knowledge of the past into a single field of study. Big History invites humanistic scholars and historical scientists from fields like geology, paleontology, evolutionary biology, astronomy, and cosmology to work together in developing the broadest possible view of the past.

Big History is proving to be an excellent framework for designing undergraduate synthesis courses that attract outstanding students. A serious problem in teaching such courses is conveying the vast stretches of time from the Big Bang, 13.7 billion years ago to the present, and clarifying the wildly different time scales of cosmic history, Earth and life history, human prehistory, and human history.

Our first conception of ChronoZoom was that it should dramatically convey the scales of history, and the first version does in fact do that. To display the scales of history from a single day to the age of the Universe requires the ability to zoom smoothly by a factor of ~1013, and doing this with raster graphics was a remarkable achievement of the team at Live Labs. The immense zoom range also allows us to embed virtually limitless amounts of text and graphical information

ChronoZoom, by letting us move effortlessly through this enormous wilderness of time, getting used to the differences in scale, should help to break down the time-scale barriers to communication between scholars.

The Future of ChronoZoom

We envision a world where scientists, researchers, students, and teachers collaborate through ChronoZoom to share information via data, tours, and insight.

Imagine a world where the leading academics publish their findings to the world in a manner that can easily be accessed and compared to other data.

Imagine a tool that allows teachers to generate tours specific to their classroom needs.

This can happen with your support. As ChronoZoom through the beta release, we need your feedback and support to continue to mold this project to suit your needs.

Help ChronoZoom evolve by take this survey so we can provide the best possible future features:
Click here to take our survey.

Roland Saekow, David Shimabukuro and Walter Alvarez
University of California Berkeley

Updated Wiki: Home

JayBeavers — Sun, 17 Feb 2013 17:05:32 GMT

See ChronoZoom on Github for new development and ChronoZoom on Trello for our plans for the future.

The regimes of Big History are:

Cosmos
Earth
Life
Human Pre-History
Human History.

ChronoZoom is a collaborative effort of the Department of Earth and Planetary Science at UC Berkeley, Microsoft Research, and originally Microsoft Live Labs.

The Future of ChronoZoom

We envision a world where scientists, researchers, students, and teachers collaborate through ChronoZoom to share information via data, tours, and insight.

Imagine a world where the leading academics publish their findings to the world in a manner that can easily be accessed and compared to other data.

Imagine a tool that allows teachers to generate tours specific to their classroom needs.

This can happen with your support. As ChronoZoom through the beta release, we need your feedback and support to continue to mold this project to suit your needs.

Help ChronoZoom evolve by take this survey so we can provide the best possible future features:
Click here to take our survey.

Roland Saekow, David Shimabukuro and Walter Alvarez
University of California Berkeley

Updated Wiki: Home

JayBeavers — Sun, 17 Feb 2013 17:04:13 GMT

FOR ALL DOCUMENTATION ON HOW TO USE CHRONOZOOM, PLEASE VISIT DOCUMENTATION.

The regimes of Big History are:

Cosmos
Earth
Life
Human Pre-History
Human History.

ChronoZoom is a collaborative effort of the Department of Earth and Planetary Science at UC Berkeley, Microsoft Research, and originally Microsoft Live Labs.

The Future of ChronoZoom

We envision a world where scientists, researchers, students, and teachers collaborate through ChronoZoom to share information via data, tours, and insight.

Imagine a world where the leading academics publish their findings to the world in a manner that can easily be accessed and compared to other data.

Imagine a tool that allows teachers to generate tours specific to their classroom needs.

This can happen with your support. As ChronoZoom through the beta release, we need your feedback and support to continue to mold this project to suit your needs.

Help ChronoZoom evolve by take this survey so we can provide the best possible future features:
Click here to take our survey.

Roland Saekow, David Shimabukuro and Walter Alvarez
University of California Berkeley

Updated Wiki: ChronoZoom Developer's Guide

altermann — Tue, 14 Aug 2012 12:44:21 GMT

Note: As of 4/7/2012 this guide was revised. The code base was also modified to support easier adoption. If you downloaded the source code before 4/7/2012, please download again if you plan to use this guide. A new sql script has been submitted (4/25/2012) that eliminates the large number of empty timelines.

Disclaimer

This document is provided “as-is”. Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. You bear the risk of using it.

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.

Distributed under Creative Commons Attribution 3.0 Unported License.

Microsoft, Visual Studio, and Windows are trademarks of Microsoft, Inc. All other trademarks are property of their respective owners.

Introduction

ChronoZoom is an open source community project dedicated to visualizing Big History that has been funded and supported by Microsoft Research Connections in collaboration with University California at Berkeley and Moscow State University.

You can browse through history on ChronoZoom to find data in the form of articles, images, video, sound, and other multimedia. ChronoZoom links a wealth of information from five major regimes that unifies all historical knowledge collectively known as Big History.

This guide is designed to walk developers through the installation process. Some of the APIs for ChronoZoom are not yet available for the public.

Prerequisites

Hardware Requirements:

A computer that can run Visual Studio 2010.
Optionally, a network connection for the content links.

Software Requirements:

Visual Studio 2010 with Service Pack 1 (Check “Help” and “About” to determine if you have SP1 installed. If you don’t, you can get it here.)
Installation of Azure SDK (.net)
- Recommend installing from this page: http://www.windowsazure.com/en-us/develop/downloads/
SQL Data Tools (Click this link to begin download SQL Data Tools) Service pack 2 of Visual Studio must be installed before you attempt this install.
SQL Server 2008 or later Standard, Express, Developer, or Enterprise Edition

Project setup instructions

Here are the steps to get the source code and prepare for execution:

Download the code as zip file from Codeplex at http://chronozoom.codeplex.com/
Extract the zip into a folder.
Open the chronozoom.sln under the source folder (double-click on the file in windows explorer).
Right-click the Chronozoom.Database in Visual Studio Solution Explorer and click Publish.
In the dialog box, select the target database connection string to deploy to.
Click Publish.
In the chronozoom.UI project, under the scripts folder, locate the cz.settings.js
Replace current value of this with contentItemThumbnailBaseUri = 'http://127.0.0.1:10000/devstoreaccount1/images/';
Replace the text [Your domain] in the chronozoom.svc.cs file with localhost:4949 address. Also replace [Your domain] in “var req= WebRequest.Create”.
- Replace the text [Your domain] in the ChronozoomRelay.cs file with localhost:4949
Connect ChronoZoom to the database in the Chronozoom UI project, edit web.config:
1. Go to server explorer
2. Add connection to the database we published before
3. Right clicked on the newly selected connection
4. Select properties
5. Copy connection string from the properties
6. Paste into Web.config “data source = {insert your data source and add “;”
Now go to the Authoring.Azure project and edit Web.config
- Find connection string and inster the data source as before.
Configure thumbnail generation
1. Under ThumbGenApp open app.config
2. Change [add your connection string here] to the connection string you got above.
3. Change [add your blob url here] to 'http://127.0.0.1:10000/devstoreaccount1/images/'
4. Change [add your azure connection string] to “UseDevelopmentStorage=true”
5. Build under configuration “Dev Preview” for platform “X86”
Set ChronoZoom.UI as the startup project. Right click on Chronozoom.UI project and select “set as startup project”. To run authoring tools:
1. Set Authoring.Azure as startup project.
2. Run. Login as “admin” password:”admin$”
Right click on cz.htm and select “Set as startup page” You may get a storage emulator error. If so, please see http://msdn.microsoft.com/en-us/library/windowsazure/gg433134.aspx for an easy fix
Run and execute.
To generate thumbnails (required after adding content items) set ThumbGenApp as startup project.

How to Submit Code to the Project

After you have completed the code you want to add to the project, there are a few steps to follow to get your submission to the project team:

1. Document the code Comment code so that testers and future developers will clearly understand what you have done. It is recommended to create a unit test to cover the fixed functionality and include it in the appropriate test project.

2. Create a zipped file with your changed code

a. Include any source files that have your changes. Please surround your changes/additions with comments that clearly explain what you are doing.

b. Provide a document that explains what you did and how it works.

3. Submit your changes on Codeplex:

Click “Submit a patch” on the chronozoom.codeplex.com site.
On the “Upload a Patch” page, use the the “Browse” button to find your zipped file.
In the description box, describe your patch, suggest a unit test if your can.
Please note the work item that this patch fixes
Click Submit.

Coding Guidelines

One of the key components to delivering that higher productivity is by providing a consistent approach to the programming model and stylistic conventions used throughout the development of the project. Consistency reduces distractions and surprises.

Our intent is to follow the guidelines laid out by the designers of the .NET Framework class library as detailed in the book "Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries" by Krzysztof Cwalina and Brad Abrams, published by Addison-Wesley in 2005 and described in the MSDN documentation delivered with Visual Studio (found online here). While we principally follow the guidelines above, conversations and styles from many other projects and developers have had influence on this document.

Coding Conventions

Document Conventions

Just as writing code in a consistent style makes the code easier to read, this document uses words and formatting to ensure clarity and comprehension. The conventions used herein are recommendations and should be followed in most situations; however, we recognized that there are situations we may not be able to anticipate. Thus our recommendations are stated with a ‘strength’ context verb to help you decide how to apply them in your situation. Our terminology is consistent with the Framework Design Guidelines.

Our strongest recommendations are DO and DO NOT. DO and DO NOT recommendations should be followed 99.999% of the time to obtain the benefits of a consistent coding style. For example:

DO use descriptive parameter names.

DO NOT require user to explicitly instantiate more than one type in the most basic scenarios.

Our general recommendations are CONSIDER and AVOID. These guidelines should generally be followed, but we are aware of circumstances where they may not make sense. If you understand the reasoning for the general recommendation and you fully understand your situation and the reasons you need to violate the recommendation are clear, then go ahead. For example:

CONSIDER defining interfaces to achieve a similar effect to that of multiple inheritances.

AVOID using out or ref parameters.

Naming Conventions

Identifier	Public	Protected	Internal	Private	Notes
Project File	PascalCase	-	-	-	DO match Assembly and Namespace.
Source File	PascalCase	-	-	-	DO match Class name.
Namespace	PascalCase	-	-	-	DO use Project/Assembly name.
Class or Struct	PascalCase	PascalCase	PascalCase	PascalCase	CONSIDER adding suffix of sub-class.
Interface	PascalCase	PascalCase	PascalCase	PascalCase	DO prefix Interfaces with capital I.
Generic Class	PascalCase	PascalCase	PascalCase	PascalCase	DO use T or K as type identifier.
Method	PascalCase	PascalCase	PascalCase	PascalCase	CONSIDER using Verb or Verb-Object pair.
Property	PascalCase	PascalCase	PascalCase	PascalCase	DO NOT prefix with Get or Set.
Field	PascalCase	PascalCase	PascalCase	_camelCase	AVOID use of public Fields.
Static Field	PascalCase	PascalCase	PascalCase	_camelCase
Constant	PascalCase	PascalCase	PascalCase	_camelCase
Enum	PascalCase	PascalCase	PascalCase	PascalCase
Delegate	PascalCase	PascalCase	PascalCase	PascalCase
Event	PascalCase	PascalCase	PascalCase	PascalCase
Local variable	-	-	-	camelCase
Parameter	-	-	-	camelCase

Coding Style and Language Usage Conventions

Coding Style Issue	Style Guideline
Source Files	DO have only one Namespace and one Class per file.
Curly Braces	DO have braces on a new line. DO use a brace, even if syntactically optional.
Indentation	Do indent is 4 and convert tabs to spaces.
Comments	Do use // or ///.
Native Data Types	DO use built-in C# data types.
Enums	AVOID changing the default type.
Generics	CONSIDER generic types before standard or strong-typed classes.
Methods	AVOID large parameter lists (over 7). Use an array or object instead.
foreach	DO NOT modify enumerated objects within the body of the foreach loop.
Conditionals	DO NOT test against true or false. DO NOT embed code with side effects within a conditional. DO NOT embed an assignment. DO NOT embed a method invocation.
Exceptions	DO NOT use exceptions for normal flow control. DO NOT use “throw e;” when re-throwing, use “throw;”. DO avoid exceptions by validating pre/post conditions prior to the exception. DO derive from Exception, not ApplicationException.

Naming Conventions

Consistent naming procedures applied across all the various identifier types in a project goes a long way to making code more accessible to people that use the library or join the project after you.

The CLR supports both case-sensitive and case-insensitive languages. If you want to write libraries that are accessible to both types, you are restricted from on creating names that are identical except for case. Even so, appropriate and consistent capitalization enhances readability and comprehension of code.

Capitalization is used to make identifiers more readable. There are two capitalization conventions in general use for identifier names throughout the library, PascalCase and camelCase. PascalCase capitalizes every word of the descriptive identifier whereas the camelCase does not capitalize the initial word of the identifier but does capitalize every word after the initial one. There are some instances where a PascalCase or camelCase identifier may have a ‘_’ or a capital ‘I’ prefix added.

General Naming Guidelines

DO use PascalCasing for type and method names and constants.
DO use camelCasing for local variable names and method arguments.
DO use ‘I’ to prefix Interface names.
DO NOT create names that vary only by case.
AVOID creating ALLCAPITALNAMES.
DO use easily readable, descriptive, meaningful, and specific names.
- AVOID single character names.
- AVOID Hungarian notation for public or protected members.
- AVOID abbreviations unless the full name is really excessive.
- AVOID adding redundant prefixes and suffixes e.g. public enum ColorsEnum {…}.
DO name types with nouns, noun phrases, or adjective phrases using PascalCasing.
CONSIDER ending the name of a derived classes with the name of the base class.
DO prefix Interface names with the letter ‘I’, to indicate that the type is an interface.
DO give methods names that are verbs or verb phrases.
DO name properties using a noun, noun phrase, or adjective.
CONSIDER giving a property the same name as its type.
DO name fields using a noun or noun phrase.
CONSIDER using common, well known acronyms, e.g. IO instead of InputOutput.
AVOID acronyms that are not common or widely known.
DO use uppercase for two-letter acronyms and PascalCase for other acronyms. It is acceptable to use “BIO” rather than “Bio” in the context of this project.
CONSIDER using C# types rather than aliases in the System namespace.
DO use capital letters for type placeholders in generics.
CONSIDER prefixing Boolean variables with “Can”, “Is”, or “Has”.
CONSIDER appending computational variables with the suffix “Average”, “Count”, “Sum”, “Min”, or “Max”.
DO use meaningful namespaces under the “Bio” root when extending the Framework.
DO use meaningful namespaces under your Product, Company, or Developer name for tools or code using the project.e.g. namespace MyCompany.MyProduct.MyNamespace;

Coding Style and Language Usage

Resolving issues around different coding styles can cause controversy among developers, but consistent layout, format, and organization are key attributes of maintainable code. The following guidelines describe the ‘preferred’ way to write C# code in order to consistently create clear, readable, comprehensible code that you and your team members can maintain over time.

General Style Guidelines

DO have a single file contribute to a single namespace.
DO have a single class in a single source file.
DO group all framework “using” namespaces together before custom or third party namespaces.
AVOID putting a “using” statement inside a namespace.
AVOID using fully qualified type names by using the “using” statement.
CONSIDER grouping internal class implementation by type in the following order:
1. Member variables.
2. Constructors & Finalizers.
3. Nested enums, structs, and classes.
4. Properties
5. Methods
DO explicitly declare the access modifier for all identifiers rather than relying on default.
CONSIDER grouping declarations within each type by their access modifier and visibility:
1. public
2. protected.
3. internal
4. private
DO declare all member variables as private and provide public, protected, or internal property access where required.
DO declare each variable in its own statement.
DO use white space to organize and separate code.
DO maintain strict indentation of 4 spaces. DO NOT use tab characters in the documents.
DO indent all code blocks contained within curly braces.
DO place opening curly braces ( { ) on a new line.
DO indent comments to the same level as the code being described.
DO use correct spelling, grammar, and punctuation in all comments.
DO use // or /// for comments.
AVOID /* … */ for comments.
DO use inline comments to explain assumptions, issues, and algorithmic insights.
DO NOT use comments to explain obvious code.
DO use Task-List keywords in comments to allow filtering e.g.
// TODO:
// UNDONE:
DO use C# comment blocks for documenting the API.
DO use C# comment blocks for every public, protected, and internal declaration.
DO include <summary> comments.
DO include <param>, <return>, and <exception> comments where applicable.
DO declare local variables near their first use.
DO initialize local variables where you declare them.
DO use the simplest data type, collection, or object that meets your requirements.
AVOID specifying the type of an Enum. Use the default of int unless you have an explicit need for a long.
DO NOT use inline numeric literals (‘magic numbers’). Use Constant or Enum.
AVOID declaring string literals. Use Resources, Constants, Configuration Files, Registry or other data sources.

Library Design

A successful framework for biology must be designed for a broad range of developer skills and capabilities. Delivering powerful capabilities with clean, simple abstractions that can be used by the novice, while still allowing the expert to control the details underlying the abstraction is a challenging task.

General Library Design Guidelines

DO design a framework that is both powerful and easy to use.
DO provide a layered framework with high-level APIs optimized for productivity and low-level APIs optimized for power and expressiveness.
AVOID mixing low-level and high-level APIs in a single namespace.
DO ensure that layers of a single feature are well integrated and complete. Developers should be able to migrate from one level to another without re-writing the entire application.
DO base your design on meaningful usage scenarios.
DO ensure scenarios that correspond to an appropriate abstraction level.
DO design APIs by first writing code samples for the main scenario then defining the object model to support the code.
DO organize usability studies to test API in main scenarios.
DO provide simple overloads of constructors and methods with a small number of primitive parameters.
DO NOT require user to explicitly instantiate more than one type in the most basic scenarios.
DO provide good defaults for all properties and parameters if possible.
DO communicate incorrect usage of APIs using exceptions.
DO provide strongly typed APIs if at all possible.
DO NOT create circular references between assemblies.
CONSIDER factoring unsafe code into a separate assembly.
DO use zero-based indexing when developing with the Framework.

Azure Deployment Guidelines

ChronoZoom is powered by Windows Azure and SQL Azure. With Team Foundation Server as the source repository for ChronoZoom, there comes an added benefit of build servers. We leverage the build feature of TFS to automatically deploy packages to Azure.

As part of the Engineering practice, it would be ideal to let TFS handle the deployment to Azure as part of the daily builds. Here are some advantages of doing this:

Being able to build, package, and deploy our projects to multiple Windows Azure environments from a build server using MSBuild
Being able to retain copies of our packages and configurations for our builds in Windows Azure BLOB Storage for safe keeping, history, easy rollback scenarios, etc.
Having a build number generated for a build and make sure that build number is present in the name of our packages, configs, and deployment labels in Azure for consistency
Leveraging the Release Configurations in Visual Studio as much as possible as the designation of our different environments, since Web.Config transformations rely on this pattern already
Being able to still package and deploy locally, in case there is an issue with the build server for some reason

Greater depth on the deployment can be found here - http://blogs.msdn.com/b/tomholl/archive/2011/12/06/automated-build-and-deployment-with-windows-azure-sdk-1-6.aspx

Here are some technical requirements to get setup with automatic deployment:

Install Windows Azure tools on build server
Install Windows Azure powershell cmdlets
Download publish settings from http://windows.azure.com/downloads/publishprofile.aspx
In MSBuild build definition setting, under process set it to /t:Publish /p:PublishDir=C:\Builds\Drops\;Configuration=DevPreview;AzurePublishProfile=<Your profile>.azurePubxml

The Future of ChronoZoom

We envision a world where scientists, researchers, students, and teachers collaborate through ChronoZoom to share information via data, tours, and insight.

Imagine a world where the leading academics publish their findings to the world in a manner that can easily be accessed and compared to other data.

Imagine a tool that allows teachers to generate tours specific to their classroom needs.

This can happen with your support. As ChronoZoom through the beta release, we need your feedback and support to continue to mold this project to suit your needs.

Help ChronoZoom evolve by taking this survey so we can provide the best possible future features: http://www.zoomerang.com/Survey/WEB22EFZBLQL4B/

Updated Wiki: ChronoZoom Developer's Guide

altermann — Tue, 14 Aug 2012 12:40:38 GMT

Note: As of 4/7/2012 this guide was revised. The code base was also modified to support easier adoption. If you downloaded the source code before 4/7/2012, please download again if you plan to use this guide. A new sql script has been submitted (4/25/2012) that eliminates the large number of empty timelines.

Disclaimer

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.

Distributed under Creative Commons Attribution 3.0 Unported License.

Microsoft, Visual Studio, and Windows are trademarks of Microsoft, Inc. All other trademarks are property of their respective owners.

Introduction

This guide is designed to walk developers through the installation process. Some of the APIs for ChronoZoom are not yet available for the public.

Prerequisites

Hardware Requirements:

· A computer that can run Visual Studio 2010.

· Optionally, a network connection for the content links.

Software Requirements:

· Visual Studio 2010 with Service Pack 1 (Check “Help” and “About” to determine if you have SP1 installed. If you don’t, you can get it here.)

· Installation of Azure SDK (.net)

o Recommend installing from this page: http://www.windowsazure.com/en-us/develop/downloads/

· SQL Data Tools (Click this link to begin download SQL Data Tools) Service pack 2 of Visual Studio must be installed before you attempt this install.

· SQL Server 2008 or later Standard, Express, Developer, or Enterprise Edition

Project setup instructions

Here are the steps to get the source code and prepare for execution:

Download the code as zip file from Codeplex at http://chronozoom.codeplex.com/
Extract the zip into a folder.
Open the chronozoom.sln under the source folder (double-click on the file in windows explorer).
Right-click the Chronozoom.Database in Visual Studio Solution Explorer and click Publish.
In the dialog box, select the target database connection string to deploy to.
Click Publish.
In the chronozoom.UI project, under the scripts folder, locate the cz.settings.js
Replace current value of this with contentItemThumbnailBaseUri = 'http://127.0.0.1:10000/devstoreaccount1/images/';
Replace the text [Your domain] in the chronozoom.svc.cs file with localhost:4949 address. Also replace [Your domain] in “var req= WebRequest.Create”.
- Replace the text [Your domain] in the ChronozoomRelay.cs file with localhost:4949
Connect ChronoZoom to the database in the Chronozoom UI project, edit web.config:
1. Go to server explorer
2. Add connection to the database we published before
3. Right clicked on the newly selected connection
4. Select properties
5. Copy connection string from the properties
6. Paste into Web.config “data source = {insert your data source and add “;”
Now go to the Authoring.Azure project and edit Web.config
- Find connection string and inster the data source as before.
Configure thumbnail generation
1. Under ThumbGenApp open app.config
2. Change [add your connection string here] to the connection string you got above.
3. Change [add your blob url here] to 'http://127.0.0.1:10000/devstoreaccount1/images/'
4. Change [add your azure connection string] to “UseDevelopmentStorage=true”
5. Build under configuration “Dev Preview” for platform “X86”
Set ChronoZoom.UI as the startup project. Right click on Chronozoom.UI project and select “set as startup project”. To run authoring tools:
1. Set Authoring.Azure as startup project.
2. Run. Login as “admin” password:”admin$”
Right click on cz.htm and select “Set as startup page” You may get a storage emulator error. If so, please see http://msdn.microsoft.com/en-us/library/windowsazure/gg433134.aspx for an easy fix
Run and execute.
To generate thumbnails (required after adding content items) set ThumbGenApp as startup project.

How to Submit Code to the Project

After you have completed the code you want to add to the project, there are a few steps to follow to get your submission to the project team:

2. Create a zipped file with your changed code

a. Include any source files that have your changes. Please surround your changes/additions with comments that clearly explain what you are doing.

b. Provide a document that explains what you did and how it works.

3. Submit your changes on Codeplex:

Click “Submit a patch” on the chronozoom.codeplex.com site.
On the “Upload a Patch” page, use the the “Browse” button to find your zipped file.
In the description box, describe your patch, suggest a unit test if your can.
Please note the work item that this patch fixes
Click Submit.

Coding Guidelines

Coding Conventions

Document Conventions

Our strongest recommendations are DO and DO NOT. DO and DO NOT recommendations should be followed 99.999% of the time to obtain the benefits of a consistent coding style. For example:

DO use descriptive parameter names.

DO NOT require user to explicitly instantiate more than one type in the most basic scenarios.

CONSIDER defining interfaces to achieve a similar effect to that of multiple inheritances.

AVOID using out or ref parameters.

Naming Conventions

Identifier	Public	Protected	Internal	Private	Notes
Project File	PascalCase	-	-	-	DO match Assembly and Namespace.
Source File	PascalCase	-	-	-	DO match Class name.
Namespace	PascalCase	-	-	-	DO use Project/Assembly name.
Class or Struct	PascalCase	PascalCase	PascalCase	PascalCase	CONSIDER adding suffix of sub-class.
Interface	PascalCase	PascalCase	PascalCase	PascalCase	DO prefix Interfaces with capital I.
Generic Class	PascalCase	PascalCase	PascalCase	PascalCase	DO use T or K as type identifier.
Method	PascalCase	PascalCase	PascalCase	PascalCase	CONSIDER using Verb or Verb-Object pair.
Property	PascalCase	PascalCase	PascalCase	PascalCase	DO NOT prefix with Get or Set.
Field	PascalCase	PascalCase	PascalCase	_camelCase	AVOID use of public Fields.
Static Field	PascalCase	PascalCase	PascalCase	_camelCase
Constant	PascalCase	PascalCase	PascalCase	_camelCase
Enum	PascalCase	PascalCase	PascalCase	PascalCase
Delegate	PascalCase	PascalCase	PascalCase	PascalCase
Event	PascalCase	PascalCase	PascalCase	PascalCase
Local variable	-	-	-	camelCase
Parameter	-	-	-	camelCase

Coding Style and Language Usage Conventions

Coding Style Issue	Style Guideline
Source Files	DO have only one Namespace and one Class per file.
Curly Braces	DO have braces on a new line. DO use a brace, even if syntactically optional.
Indentation	Do indent is 4 and convert tabs to spaces.
Comments	Do use // or ///.
Native Data Types	DO use built-in C# data types.
Enums	AVOID changing the default type.
Generics	CONSIDER generic types before standard or strong-typed classes.
Methods	AVOID large parameter lists (over 7). Use an array or object instead.
foreach	DO NOT modify enumerated objects within the body of the foreach loop.
Conditionals	DO NOT test against true or false. DO NOT embed code with side effects within a conditional. DO NOT embed an assignment. DO NOT embed a method invocation.
Exceptions	DO NOT use exceptions for normal flow control. DO NOT use “throw e;” when re-throwing, use “throw;”. DO avoid exceptions by validating pre/post conditions prior to the exception. DO derive from Exception, not ApplicationException.

Naming Conventions

Consistent naming procedures applied across all the various identifier types in a project goes a long way to making code more accessible to people that use the library or join the project after you.

General Naming Guidelines

DO use PascalCasing for type and method names and constants.
DO use camelCasing for local variable names and method arguments.
DO use ‘I’ to prefix Interface names.
DO NOT create names that vary only by case.
AVOID creating ALLCAPITALNAMES.
DO use easily readable, descriptive, meaningful, and specific names.
- AVOID single character names.
- AVOID Hungarian notation for public or protected members.
- AVOID abbreviations unless the full name is really excessive.
- AVOID adding redundant prefixes and suffixes e.g. public enum ColorsEnum {…}.
DO name types with nouns, noun phrases, or adjective phrases using PascalCasing.
CONSIDER ending the name of a derived classes with the name of the base class.
DO prefix Interface names with the letter ‘I’, to indicate that the type is an interface.
DO give methods names that are verbs or verb phrases.
DO name properties using a noun, noun phrase, or adjective.
CONSIDER giving a property the same name as its type.
DO name fields using a noun or noun phrase.
CONSIDER using common, well known acronyms, e.g. IO instead of InputOutput.
AVOID acronyms that are not common or widely known.
DO use uppercase for two-letter acronyms and PascalCase for other acronyms. It is acceptable to use “BIO” rather than “Bio” in the context of this project.
CONSIDER using C# types rather than aliases in the System namespace.
DO use capital letters for type placeholders in generics.
CONSIDER prefixing Boolean variables with “Can”, “Is”, or “Has”.
CONSIDER appending computational variables with the suffix “Average”, “Count”, “Sum”, “Min”, or “Max”.
DO use meaningful namespaces under the “Bio” root when extending the Framework.
DO use meaningful namespaces under your Product, Company, or Developer name for tools or code using the project.e.g. namespace MyCompany.MyProduct.MyNamespace;

Coding Style and Language Usage

General Style Guidelines

DO have a single file contribute to a single namespace.
DO have a single class in a single source file.
DO group all framework “using” namespaces together before custom or third party namespaces.
AVOID putting a “using” statement inside a namespace.
AVOID using fully qualified type names by using the “using” statement.
CONSIDER grouping internal class implementation by type in the following order:
1. Member variables.
2. Constructors & Finalizers.
3. Nested enums, structs, and classes.
4. Properties
5. Methods
DO explicitly declare the access modifier for all identifiers rather than relying on default.
CONSIDER grouping declarations within each type by their access modifier and visibility:
1. public
2. protected.
3. internal
4. private
DO declare all member variables as private and provide public, protected, or internal property access where required.
DO declare each variable in its own statement.
DO use white space to organize and separate code.
DO maintain strict indentation of 4 spaces. DO NOT use tab characters in the documents.
DO indent all code blocks contained within curly braces.
DO place opening curly braces ( { ) on a new line.
DO indent comments to the same level as the code being described.
DO use correct spelling, grammar, and punctuation in all comments.
DO use // or /// for comments.
AVOID /* … */ for comments.
DO use inline comments to explain assumptions, issues, and algorithmic insights.
DO NOT use comments to explain obvious code.
DO use Task-List keywords in comments to allow filtering e.g.
// TODO:
// UNDONE:
DO use C# comment blocks for documenting the API.
DO use C# comment blocks for every public, protected, and internal declaration.
DO include <summary> comments.
DO include <param>, <return>, and <exception> comments where applicable.
DO declare local variables near their first use.
DO initialize local variables where you declare them.
DO use the simplest data type, collection, or object that meets your requirements.
AVOID specifying the type of an Enum. Use the default of int unless you have an explicit need for a long.
DO NOT use inline numeric literals (‘magic numbers’). Use Constant or Enum.
AVOID declaring string literals. Use Resources, Constants, Configuration Files, Registry or other data sources.

Library Design

General Library Design Guidelines

DO design a framework that is both powerful and easy to use.
DO provide a layered framework with high-level APIs optimized for productivity and low-level APIs optimized for power and expressiveness.
AVOID mixing low-level and high-level APIs in a single namespace.
DO ensure that layers of a single feature are well integrated and complete. Developers should be able to migrate from one level to another without re-writing the entire application.
DO base your design on meaningful usage scenarios.
DO ensure scenarios that correspond to an appropriate abstraction level.
DO design APIs by first writing code samples for the main scenario then defining the object model to support the code.
DO organize usability studies to test API in main scenarios.
DO provide simple overloads of constructors and methods with a small number of primitive parameters.
DO NOT require user to explicitly instantiate more than one type in the most basic scenarios.
DO provide good defaults for all properties and parameters if possible.
DO communicate incorrect usage of APIs using exceptions.
DO provide strongly typed APIs if at all possible.
DO NOT create circular references between assemblies.
CONSIDER factoring unsafe code into a separate assembly.
DO use zero-based indexing when developing with the Framework.

Azure Deployment Guidelines

As part of the Engineering practice, it would be ideal to let TFS handle the deployment to Azure as part of the daily builds. Here are some advantages of doing this:

Being able to build, package, and deploy our projects to multiple Windows Azure environments from a build server using MSBuild
Being able to retain copies of our packages and configurations for our builds in Windows Azure BLOB Storage for safe keeping, history, easy rollback scenarios, etc.
Having a build number generated for a build and make sure that build number is present in the name of our packages, configs, and deployment labels in Azure for consistency
Leveraging the Release Configurations in Visual Studio as much as possible as the designation of our different environments, since Web.Config transformations rely on this pattern already
Being able to still package and deploy locally, in case there is an issue with the build server for some reason

Greater depth on the deployment can be found here - http://blogs.msdn.com/b/tomholl/archive/2011/12/06/automated-build-and-deployment-with-windows-azure-sdk-1-6.aspx

Here are some technical requirements to get setup with automatic deployment:

Install Windows Azure tools on build server
Install Windows Azure powershell cmdlets
Download publish settings from http://windows.azure.com/downloads/publishprofile.aspx
In MSBuild build definition setting, under process set it to /t:Publish /p:PublishDir=C:\Builds\Drops\;Configuration=DevPreview;AzurePublishProfile=<Your profile>.azurePubxml

The Future of ChronoZoom

We envision a world where scientists, researchers, students, and teachers collaborate through ChronoZoom to share information via data, tours, and insight.

Imagine a world where the leading academics publish their findings to the world in a manner that can easily be accessed and compared to other data.

Imagine a tool that allows teachers to generate tours specific to their classroom needs.

This can happen with your support. As ChronoZoom through the beta release, we need your feedback and support to continue to mold this project to suit your needs.

Help ChronoZoom evolve by taking this survey so we can provide the best possible future features: http://www.zoomerang.com/Survey/WEB22EFZBLQL4B/

Updated Wiki: Documentation

saekow — Wed, 20 Jun 2012 21:14:38 GMT

Join the Conversation
Let us know what you think; ask questions, make comments, start a new discussion topic. You are very welcome to become an active part of this project. Click here to join in.

Further Reading
There are several documents that provide additional information about ChronoZoom:

- Quick Reference Guide

- User Guide

- How To Become A Developer For The ChronoZoom Project

- Developer's Guide

- Architecture Guide

- Authoring ChronoZoom timelines, exhibits, artifacts and tours Updated 6/20/2012

Frequently Asked Questions

Q: Why does the animation appear slow or choppy on my Computer?

A: ChronoZoom is designed to support most computers. However, on some machines, the graphics will be slower or less smooth than intended due to limited memory and processor power. ChronoZoom makes extensive use of Javascript and HTML5, so frame rate will depend on CPU performance.

Q. Why do the graphic appear slow or fuzzy in Firefox 10.x ?

A. Firefox 10.x automatically activates the hardware graphics acceleration even though many computers, including some Mac machines might not be able to properly use this functionality. We recommend disabling graphics hardware acceleration.

Q. I am having issues viewing ChronoZoom through Chrome. Everything is very slow. What can I do?

A. This is a known issue for Chrome due to the WebKit canvas performance instability. Chrome is working on a fix for this issue on their next release.

Q. ChronoZoom sometimes stops working for me and I can’t figure out why.

A. ChronoZoom requires network connectivity to work. Sometimes, your browser may cache information that will simulate connectivity, but when you want to access a tour or new information, it will stop without an internet connection. Check your internet connection if you are having issues.

Q. When using Firefox, I am having difficulty with tour audio. What can I do?

A. This is a known issue for Firefox. This article might be able to assist you.

Updated Wiki: Documentation

saekow — Wed, 20 Jun 2012 21:13:52 GMT

Join the Conversation
Let us know what you think; ask questions, make comments, start a new discussion topic. You are very welcome to become an active part of this project. Click here to join in.

Further Reading
There are several documents that provide additional information about ChronoZoom:

- Quick Reference Guide

- User Guide

- How To Become A Developer For The ChronoZoom Project

- Developer's Guide

- Architecture Guide

- Authoring ChronoZoom timelines, exhibits, artifacts and tours

Frequently Asked Questions

Q: Why does the animation appear slow or choppy on my Computer?

Q. Why do the graphic appear slow or fuzzy in Firefox 10.x ?

Q. I am having issues viewing ChronoZoom through Chrome. Everything is very slow. What can I do?

A. This is a known issue for Chrome due to the WebKit canvas performance instability. Chrome is working on a fix for this issue on their next release.

Q. ChronoZoom sometimes stops working for me and I can’t figure out why.

Q. When using Firefox, I am having difficulty with tour audio. What can I do?

A. This is a known issue for Firefox. This article might be able to assist you.

Updated Wiki: Documentation

saekow — Wed, 20 Jun 2012 21:12:28 GMT

Join the Conversation
Let us know what you think; ask questions, make comments, start a new discussion topic. You are very welcome to become an active part of this project. Click here to join in.

Further Reading
There are several documents that provide additional information about ChronoZoom:

- Quick Reference Guide

- User Guide

- How To Become A Developer For The ChronoZoom Project

- Developer's Guide

- Architecture Guide

- Authoring ChronoZoom timelines, exhibits, artifacts and tours

Frequently Asked Questions

Q: Why does the animation appear slow or choppy on my Computer?

Q. Why do the graphic appear slow or fuzzy in Firefox 10.x ?

Q. I am having issues viewing ChronoZoom through Chrome. Everything is very slow. What can I do?

A. This is a known issue for Chrome due to the WebKit canvas performance instability. Chrome is working on a fix for this issue on their next release.

Q. ChronoZoom sometimes stops working for me and I can’t figure out why.

Q. When using Firefox, I am having difficulty with tour audio. What can I do?

A. This is a known issue for Firefox. This article might be able to assist you.

Updated Wiki: Documentation

bobwalter — Thu, 07 Jun 2012 20:33:21 GMT

Join the Conversation
Let us know what you think; ask questions, make comments, start a new discussion topic. You are very welcome to become an active part of this project. Click here to join in.

Further Reading
There are several documents that provide additional information about ChronoZoom:

- Quick Reference Guide

- User Guide

- How To Become A Developer For The ChronoZoom Project

- Developer's Guide

- Architecture Guide

- Authoring ChronoZoom timelines, content items, and exhibits New 6/7/2012

Frequently Asked Questions

Q: Why does the animation appear slow or choppy on my Computer?

Q. Why do the graphic appear slow or fuzzy in Firefox 10.x ?

Q. I am having issues viewing ChronoZoom through Chrome. Everything is very slow. What can I do?

A. This is a known issue for Chrome due to the WebKit canvas performance instability. Chrome is working on a fix for this issue on their next release.

Q. ChronoZoom sometimes stops working for me and I can’t figure out why.

Q. When using Firefox, I am having difficulty with tour audio. What can I do?

A. This is a known issue for Firefox. This article might be able to assist you.

Updated Wiki: ChronoZoom Developer's Guide

bobwalter — Mon, 30 Apr 2012 21:30:01 GMT

Note: As of 4/7/2012 this guide was revised. The code base was also modified to support easier adoption. If you downloaded the source code before 4/7/2012, please download again if you plan to use this guide. A new sql script has been submitted (4/25/2012) that eliminates the large number of empty timelines.

Disclaimer

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.

Distributed under Creative Commons Attribution 3.0 Unported License.

Microsoft, Visual Studio, and Windows are trademarks of Microsoft, Inc. All other trademarks are property of their respective owners.

Introduction

This guide is designed to walk developers through the installation process. Some of the APIs for ChronoZoom are not yet available for the public.

Prerequisites

Hardware Requirements:

· A computer that can run Visual Studio 2010.

· Optionally, a network connection for the content links.

Software Requirements:

· Visual Studio 2010 with Service Pack 1 (Check “Help” and “About” to determine if you have SP1 installed. If you don’t, you can get it here.)

· Installation of Azure SDK (.net)

o Recommend installing from this page: http://www.windowsazure.com/en-us/develop/downloads/

· SQL Data Tools (Click this link to begin download SQL Data Tools) Service pack 2 of Visual Studio must be installed before you attempt this install.

· SQL Server 2008 or later Standard, Express, Developer, or Enterprise Edition

Project setup instructions

Here are the steps to get the source code and prepare for execution:

1. Download the code as zip file from Codeplex at http://chronozoom.codeplex.com/

2. Extract the zip into a folder.

3. Open the chronozoom.sln under the source folder (double-click on the file in windows explorer).

4. Right-click the Chronozoom.Database in Visual Studio Solution Explorer and click Publish.

5. In the dialog box, select the target database connection string to deploy to.

6. Click Publish.

7. In the chronozoom.UI project, under the scripts folder, locate the cz.settings.js

8. Replace current value of this with contentItemThumbnailBaseUri = 'http://127.0.0.1:10000/devstoreaccount1/images/';

a. Replace the text [Your domain] in the chronozoom.svc.cs file with localhost:4949 address. Also replace [Your domain] in “var req= WebRequest.Create”

9. Replace the text [Your domain] in the ChronozoomRelay.cs file with localhost:4949

10. Connect ChronoZoom to the database in the Chronozoom UI project, edit web.config

a. Go to server explorer

b. Add connection to the database we published before

c. Right clicked on the newly selected connection

d. Select properties

e. Copy connection string from the properties

f. Paste into Web.config “data source = {insert your data source and add “;”

11. Now go to the Authoring.Azure project and edit Web.config

a. Find connection string and inster the data source as before.

12. Configure thumbnail generation

a. Under ThumbGenApp open app.config

b. Change [add your connection string here] to the connection string you got above.

c. Change [add your blob url here] to 'http://127.0.0.1:10000/devstoreaccount1/images/'

d. Change [add your azure connection string] to “UseDevelopmentStorage=true”

e. Build under configuration “Dev Preview” for platform “X86”

13. Set ChronoZoom.UI as the startup project. Right click on Chronozoom.UI project and select “set as startup project”. To run authoring tools:

a. Set Authoring.Azure as startup project.

b. Run. Login as “admin” password:”admin$”

14. Right click on cz.htm and select “Set as startup page” You may get a storage emulator error. If so, please see http://msdn.microsoft.com/en-us/library/windowsazure/gg433134.aspx for an easy fix

15. Run and execute.

16. To generate thumbnails (required after adding content items) set ThumbGenApp as startup project.

How to Submit Code to the Project

After you have completed the code you want to add to the project, there are a few steps to follow to get your submission to the project team:

2. Create a zipped file with your changed code

a. Include any source files that have your changes. Please surround your changes/additions with comments that clearly explain what you are doing.

b. Provide a document that explains what you did and how it works.

3. Submit your changes on Codeplex:

i. Click “Submit a patch” on the chronozoom.codeplex.com site.

ii. On the “Upload a Patch” page, use the the “Browse” button to find your zipped file.

iii. In the description box, describe your patch, suggest a unit test if your can.

iv. Please note the work item that this patch fixes

v. Click Submit.

Coding Guidelines

Coding Conventions

Document Conventions

Our strongest recommendations are DO and DO NOT. DO and DO NOT recommendations should be followed 99.999% of the time to obtain the benefits of a consistent coding style. For example:

DO use descriptive parameter names.

DO NOT require user to explicitly instantiate more than one type in the most basic scenarios.

CONSIDER defining interfaces to achieve a similar effect to that of multiple inheritances.

AVOID using out or ref parameters.

Naming Conventions

Identifier	Public	Protected	Internal	Private	Notes
Project File	PascalCase	-	-	-	DO match Assembly and Namespace.
Source File	PascalCase	-	-	-	DO match Class name.
Namespace	PascalCase	-	-	-	DO use Project/Assembly name.
Class or Struct	PascalCase	PascalCase	PascalCase	PascalCase	CONSIDER adding suffix of sub-class.
Interface	PascalCase	PascalCase	PascalCase	PascalCase	DO prefix Interfaces with capital I.
Generic Class	PascalCase	PascalCase	PascalCase	PascalCase	DO use T or K as type identifier.
Method	PascalCase	PascalCase	PascalCase	PascalCase	CONSIDER using Verb or Verb-Object pair.
Property	PascalCase	PascalCase	PascalCase	PascalCase	DO NOT prefix with Get or Set.
Field	PascalCase	PascalCase	PascalCase	_camelCase	AVOID use of public Fields.
Static Field	PascalCase	PascalCase	PascalCase	_camelCase
Constant	PascalCase	PascalCase	PascalCase	_camelCase
Enum	PascalCase	PascalCase	PascalCase	PascalCase
Delegate	PascalCase	PascalCase	PascalCase	PascalCase
Event	PascalCase	PascalCase	PascalCase	PascalCase
Local variable	-	-	-	camelCase
Parameter	-	-	-	camelCase

Coding Style and Language Usage Conventions

Coding Style Issue	Style Guideline
Source Files	DO have only one Namespace and one Class per file.
Curly Braces	DO have braces on a new line. DO use a brace, even if syntactically optional.
Indentation	Do indent is 4 and convert tabs to spaces.
Comments	Do use // or ///.
Native Data Types	DO use built-in C# data types.
Enums	AVOID changing the default type.
Generics	CONSIDER generic types before standard or strong-typed classes.
Methods	AVOID large parameter lists (over 7). Use an array or object instead.
foreach	DO NOT modify enumerated objects within the body of the foreach loop.
Conditionals	DO NOT test against true or false. DO NOT embed code with side effects within a conditional. DO NOT embed an assignment. DO NOT embed a method invocation.
Exceptions	DO NOT use exceptions for normal flow control. DO NOT use “throw e;” when re-throwing, use “throw;”. DO avoid exceptions by validating pre/post conditions prior to the exception. DO derive from Exception, not ApplicationException.

Naming Conventions

Consistent naming procedures applied across all the various identifier types in a project goes a long way to making code more accessible to people that use the library or join the project after you.

General Naming Guidelines

1. DO use PascalCasing for type and method names and constants.

2. DO use camelCasing for local variable names and method arguments.

3. DO use ‘I’ to prefix Interface names.

4. DO NOT create names that vary only by case.

5. AVOID creating ALLCAPITALNAMES.

6. DO use easily readable, descriptive, meaningful, and specific names.

a. AVOID single character names.

b. AVOID Hungarian notation for public or protected members.

c. AVOID abbreviations unless the full name is really excessive.

d. AVOID adding redundant prefixes and suffixes e.g. public enum ColorsEnum {…}.

7. DO name types with nouns, noun phrases, or adjective phrases using PascalCasing.

8. CONSIDER ending the name of a derived classes with the name of the base class.

9. DO prefix Interface names with the letter ‘I’, to indicate that the type is an interface.

10. DO give methods names that are verbs or verb phrases.

11. DO name properties using a noun, noun phrase, or adjective.

12. CONSIDER giving a property the same name as its type.

13. DO name fields using a noun or noun phrase.

14. CONSIDER using common, well known acronyms, e.g. IO instead of InputOutput.

15. AVOID acronyms that are not common or widely known.

16. DO use uppercase for two-letter acronyms and PascalCase for other acronyms. It is acceptable to use “BIO” rather than “Bio” in the context of this project.

17. CONSIDER using C# types rather than aliases in the System namespace.

18. DO use capital letters for type placeholders in generics.

19. CONSIDER prefixing Boolean variables with “Can”, “Is”, or “Has”.

20. CONSIDER appending computational variables with the suffix “Average”, “Count”, “Sum”, “Min”, or “Max”.

21. DO use meaningful namespaces under the “Bio” root when extending the Framework.

22. DO use meaningful namespaces under your Product, Company, or Developer name for tools or code using the project.e.g. namespace MyCompany.MyProduct.MyNamespace;

Coding Style and Language Usage

General Style Guidelines

1. DO have a single file contribute to a single namespace.

2. DO have a single class in a single source file.

3. DO group all framework “using” namespaces together before custom or third party namespaces.

4. AVOID putting a “using” statement inside a namespace.

5. AVOID using fully qualified type names by using the “using” statement.

6. CONSIDER grouping internal class implementation by type in the following order:

a. Member variables.

b. Constructors & Finalizers.

c. Nested enums, structs, and classes.

d. Properties

e. Methods

7. DO explicitly declare the access modifier for all identifiers rather than relying on default.

8. CONSIDER grouping declarations within each type by their access modifier and visibility:

a. public

b. protected

c. internal

d. private

9. DO declare all member variables as private and provide public, protected, or internal property access where required.

10. DO declare each variable in its own statement.

11. DO use white space to organize and separate code.

12. DO maintain strict indentation of 4 spaces. DO NOT use tab characters in the documents.

13. DO indent all code blocks contained within curly braces.

14. DO place opening curly braces ( { ) on a new line.

15. DO indent comments to the same level as the code being described.

16. DO use correct spelling, grammar, and punctuation in all comments.

17. DO use // or /// for comments.

18. AVOID /* … */ for comments.

19. DO use inline comments to explain assumptions, issues, and algorithmic insights.

20. DO NOT use comments to explain obvious code.

21. DO use Task-List keywords in comments to allow filtering e.g.
// TODO:
// UNDONE:

22. DO use C# comment blocks for documenting the API.

23. DO use C# comment blocks for every public, protected, and internal declaration.

24. DO include <summary> comments.

25. DO include <param>, <return>, and <exception> comments where applicable.

26. DO declare local variables near their first use.

27. DO initialize local variables where you declare them.

28. DO use the simplest data type, collection, or object that meets your requirements.

29. AVOID specifying the type of an Enum. Use the default of int unless you have an explicit need for a long.

30. DO NOT use inline numeric literals (‘magic numbers’). Use Constant or Enum.

31. AVOID declaring string literals. Use Resources, Constants, Configuration Files, Registry or other data sources.

Library Design

General Library Design Guidelines

1. DO design a framework that is both powerful and easy to use.

2. DO provide a layered framework with high-level APIs optimized for productivity and low-level APIs optimized for power and expressiveness.

3. AVOID mixing low-level and high-level APIs in a single namespace.

4. DO ensure that layers of a single feature are well integrated and complete. Developers should be able to migrate from one level to another without re-writing the entire application.

5. DO base your design on meaningful usage scenarios.

6. DO ensure scenarios that correspond to an appropriate abstraction level.

7. DO design APIs by first writing code samples for the main scenario then defining the object model to support the code.

8. DO organize usability studies to test API in main scenarios.

9. DO provide simple overloads of constructors and methods with a small number of primitive parameters.

10. DO NOT require user to explicitly instantiate more than one type in the most basic scenarios.

11. DO provide good defaults for all properties and parameters if possible.

12. DO communicate incorrect usage of APIs using exceptions.

13. DO provide strongly typed APIs if at all possible.

14. DO NOT create circular references between assemblies.

15. CONSIDER factoring unsafe code into a separate assembly.

16. DO use zero-based indexing when developing with the Framework.

Azure Deployment Guidelines

As part of the Engineering practice, it would be ideal to let TFS handle the deployment to Azure as part of the daily builds. Here are some advantages of doing this:

· Being able to build, package, and deploy our projects to multiple Windows Azure environments from a build server using MSBuild

· Being able to retain copies of our packages and configurations for our builds in Windows Azure BLOB Storage for safe keeping, history, easy rollback scenarios, etc.

· Having a build number generated for a build and make sure that build number is present in the name of our packages, configs, and deployment labels in Azure for consistency

· Leveraging the Release Configurations in Visual Studio as much as possible as the designation of our different environments, since Web.Config transformations rely on this pattern already

· Being able to still package and deploy locally, in case there is an issue with the build server for some reason

Greater depth on the deployment can be found here - http://blogs.msdn.com/b/tomholl/archive/2011/12/06/automated-build-and-deployment-with-windows-azure-sdk-1-6.aspx

Here are some technical requirements to get setup with automatic deployment:

· Install Windows Azure tools on build server

· Install Windows Azure powershell cmdlets

· Download publish settings from http://windows.azure.com/downloads/publishprofile.aspx

· In MSBuild build definition setting, under process set it to

o /t:Publish /p:PublishDir=C:\Builds\Drops\;Configuration=DevPreview;AzurePublishProfile=<Your profile>.azurePubxml

The Future of ChronoZoom

We envision a world where scientists, researchers, students, and teachers collaborate through ChronoZoom to share information via data, tours, and insight.

Imagine a world where the leading academics publish their findings to the world in a manner that can easily be accessed and compared to other data.

Imagine a tool that allows teachers to generate tours specific to their classroom needs.

This can happen with your support. As ChronoZoom through the beta release, we need your feedback and support to continue to mold this project to suit your needs.

Help ChronoZoom evolve by taking this survey so we can provide the best possible future features: http://www.zoomerang.com/Survey/WEB22EFZBLQL4B/

Updated Wiki: ChronoZoom Developer's Guide

BobWalter — Sat, 14 Apr 2012 02:04:05 GMT

Note: As of 4/7/2012 this guide was revised. The code base was also modified to support easier adoption. If you downloaded the source code before 4/7/2012, please download again if you plan to use this guide.

Disclaimer

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.

Distributed under Creative Commons Attribution 3.0 Unported License.

Microsoft, Visual Studio, and Windows are trademarks of Microsoft, Inc. All other trademarks are property of their respective owners.

Introduction

This guide is designed to walk developers through the installation process. Some of the APIs for ChronoZoom are not yet available for the public.

Prerequisites

Hardware Requirements:

· A computer that can run Visual Studio 2010.

· Optionally, a network connection for the content links.

Software Requirements:

· Visual Studio 2010 with Service Pack 1 (Check “Help” and “About” to determine if you have SP1 installed. If you don’t, you can get it here.)

· Installation of Azure SDK (.net)

o Recommend installing from this page: http://www.windowsazure.com/en-us/develop/downloads/

· SQL Data Tools (Click this link to begin download SQL Data Tools) Service pack 2 of Visual Studio must be installed before you attempt this install.

· SQL Server 2008 or later Standard, Express, Developer, or Enterprise Edition

Project setup instructions

Here are the steps to get the source code and prepare for execution:

1. Download the code as zip file from Codeplex at http://chronozoom.codeplex.com/

2. Extract the zip into a folder.

3. Open the chronozoom.sln under the source folder (double-click on the file in windows explorer).

4. Right-click the Chronozoom.Database in Visual Studio Solution Explorer and click Publish.

5. In the dialog box, select the target database connection string to deploy to.

6. Click Publish.

7. In the chronozoom.UI project, under the scripts folder, locate the cz.settings.js

8. Replace current value of this with contentItemThumbnailBaseUri = 'http://127.0.0.1:10000/devstoreaccount1/images/';

a. Replace the text [Your domain] in the chronozoom.svc.cs file with localhost:4949 address. Also replace [Your domain] in “var req= WebRequest.Create”

9. Replace the text [Your domain] in the ChronozoomRelay.cs file with localhost:4949

10. Connect ChronoZoom to the database in the Chronozoom UI project, edit web.config

a. Go to server explorer

b. Add connection to the database we published before

c. Right clicked on the newly selected connection

d. Select properties

e. Copy connection string from the properties

f. Paste into Web.config “data source = {insert your data source and add “;”

11. Now go to the Authoring.Azure project and edit Web.config

a. Find connection string and inster the data source as before.

12. Configure thumbnail generation

a. Under ThumbGenApp open app.config

b. Change [add your connection string here] to the connection string you got above.

c. Change [add your blob url here] to 'http://127.0.0.1:10000/devstoreaccount1/images/'

d. Change [add your azure connection string] to “UseDevelopmentStorage=true”

e. Build under configuration “Dev Preview” for platform “X86”

13. Set ChronoZoom.UI as the startup project. Right click on Chronozoom.UI project and select “set as startup project”. To run authoring tools:

a. Set Authoring.Azure as startup project.

b. Run. Login as “admin” password:”admin$”

15. Run and execute.

16. To generate thumbnails (required after adding content items) set ThumbGenApp as startup project.

How to Submit Code to the Project

After you have completed the code you want to add to the project, there are a few steps to follow to get your submission to the project team:

2. Create a zipped file with your changed code

a. Include any source files that have your changes. Please surround your changes/additions with comments that clearly explain what you are doing.

b. Provide a document that explains what you did and how it works.

3. Submit your changes on Codeplex:

i. Click “Submit a patch” on the chronozoom.codeplex.com site.

ii. On the “Upload a Patch” page, use the the “Browse” button to find your zipped file.

iii. In the description box, describe your patch, suggest a unit test if your can.

iv. Please note the work item that this patch fixes

v. Click Submit.

Coding Guidelines

Coding Conventions

Document Conventions

Our strongest recommendations are DO and DO NOT. DO and DO NOT recommendations should be followed 99.999% of the time to obtain the benefits of a consistent coding style. For example:

DO use descriptive parameter names.

DO NOT require user to explicitly instantiate more than one type in the most basic scenarios.

CONSIDER defining interfaces to achieve a similar effect to that of multiple inheritances.

AVOID using out or ref parameters.

Naming Conventions

Identifier	Public	Protected	Internal	Private	Notes
Project File	PascalCase	-	-	-	DO match Assembly and Namespace.
Source File	PascalCase	-	-	-	DO match Class name.
Namespace	PascalCase	-	-	-	DO use Project/Assembly name.
Class or Struct	PascalCase	PascalCase	PascalCase	PascalCase	CONSIDER adding suffix of sub-class.
Interface	PascalCase	PascalCase	PascalCase	PascalCase	DO prefix Interfaces with capital I.
Generic Class	PascalCase	PascalCase	PascalCase	PascalCase	DO use T or K as type identifier.
Method	PascalCase	PascalCase	PascalCase	PascalCase	CONSIDER using Verb or Verb-Object pair.
Property	PascalCase	PascalCase	PascalCase	PascalCase	DO NOT prefix with Get or Set.
Field	PascalCase	PascalCase	PascalCase	_camelCase	AVOID use of public Fields.
Static Field	PascalCase	PascalCase	PascalCase	_camelCase
Constant	PascalCase	PascalCase	PascalCase	_camelCase
Enum	PascalCase	PascalCase	PascalCase	PascalCase
Delegate	PascalCase	PascalCase	PascalCase	PascalCase
Event	PascalCase	PascalCase	PascalCase	PascalCase
Local variable	-	-	-	camelCase
Parameter	-	-	-	camelCase

Coding Style and Language Usage Conventions

Coding Style Issue	Style Guideline
Source Files	DO have only one Namespace and one Class per file.
Curly Braces	DO have braces on a new line. DO use a brace, even if syntactically optional.
Indentation	Do indent is 4 and convert tabs to spaces.
Comments	Do use // or ///.
Native Data Types	DO use built-in C# data types.
Enums	AVOID changing the default type.
Generics	CONSIDER generic types before standard or strong-typed classes.
Methods	AVOID large parameter lists (over 7). Use an array or object instead.
foreach	DO NOT modify enumerated objects within the body of the foreach loop.
Conditionals	DO NOT test against true or false. DO NOT embed code with side effects within a conditional. DO NOT embed an assignment. DO NOT embed a method invocation.
Exceptions	DO NOT use exceptions for normal flow control. DO NOT use “throw e;” when re-throwing, use “throw;”. DO avoid exceptions by validating pre/post conditions prior to the exception. DO derive from Exception, not ApplicationException.

Naming Conventions

Consistent naming procedures applied across all the various identifier types in a project goes a long way to making code more accessible to people that use the library or join the project after you.

General Naming Guidelines

1. DO use PascalCasing for type and method names and constants.

2. DO use camelCasing for local variable names and method arguments.

3. DO use ‘I’ to prefix Interface names.

4. DO NOT create names that vary only by case.

5. AVOID creating ALLCAPITALNAMES.

6. DO use easily readable, descriptive, meaningful, and specific names.

a. AVOID single character names.

b. AVOID Hungarian notation for public or protected members.

c. AVOID abbreviations unless the full name is really excessive.

d. AVOID adding redundant prefixes and suffixes e.g. public enum ColorsEnum {…}.

7. DO name types with nouns, noun phrases, or adjective phrases using PascalCasing.

8. CONSIDER ending the name of a derived classes with the name of the base class.

9. DO prefix Interface names with the letter ‘I’, to indicate that the type is an interface.

10. DO give methods names that are verbs or verb phrases.

11. DO name properties using a noun, noun phrase, or adjective.

12. CONSIDER giving a property the same name as its type.

13. DO name fields using a noun or noun phrase.

14. CONSIDER using common, well known acronyms, e.g. IO instead of InputOutput.

15. AVOID acronyms that are not common or widely known.

16. DO use uppercase for two-letter acronyms and PascalCase for other acronyms. It is acceptable to use “BIO” rather than “Bio” in the context of this project.

17. CONSIDER using C# types rather than aliases in the System namespace.

18. DO use capital letters for type placeholders in generics.

19. CONSIDER prefixing Boolean variables with “Can”, “Is”, or “Has”.

20. CONSIDER appending computational variables with the suffix “Average”, “Count”, “Sum”, “Min”, or “Max”.

21. DO use meaningful namespaces under the “Bio” root when extending the Framework.

22. DO use meaningful namespaces under your Product, Company, or Developer name for tools or code using the project.e.g. namespace MyCompany.MyProduct.MyNamespace;

Coding Style and Language Usage

General Style Guidelines

1. DO have a single file contribute to a single namespace.

2. DO have a single class in a single source file.

3. DO group all framework “using” namespaces together before custom or third party namespaces.

4. AVOID putting a “using” statement inside a namespace.

5. AVOID using fully qualified type names by using the “using” statement.

6. CONSIDER grouping internal class implementation by type in the following order:

a. Member variables.

b. Constructors & Finalizers.

c. Nested enums, structs, and classes.

d. Properties

e. Methods

7. DO explicitly declare the access modifier for all identifiers rather than relying on default.

8. CONSIDER grouping declarations within each type by their access modifier and visibility:

a. public

b. protected

c. internal

d. private

9. DO declare all member variables as private and provide public, protected, or internal property access where required.

10. DO declare each variable in its own statement.

11. DO use white space to organize and separate code.

12. DO maintain strict indentation of 4 spaces. DO NOT use tab characters in the documents.

13. DO indent all code blocks contained within curly braces.

14. DO place opening curly braces ( { ) on a new line.

15. DO indent comments to the same level as the code being described.

16. DO use correct spelling, grammar, and punctuation in all comments.

17. DO use // or /// for comments.

18. AVOID /* … */ for comments.

19. DO use inline comments to explain assumptions, issues, and algorithmic insights.

20. DO NOT use comments to explain obvious code.

21. DO use Task-List keywords in comments to allow filtering e.g.
// TODO:
// UNDONE:

22. DO use C# comment blocks for documenting the API.

23. DO use C# comment blocks for every public, protected, and internal declaration.

24. DO include <summary> comments.

25. DO include <param>, <return>, and <exception> comments where applicable.

26. DO declare local variables near their first use.

27. DO initialize local variables where you declare them.

28. DO use the simplest data type, collection, or object that meets your requirements.

29. AVOID specifying the type of an Enum. Use the default of int unless you have an explicit need for a long.

30. DO NOT use inline numeric literals (‘magic numbers’). Use Constant or Enum.

31. AVOID declaring string literals. Use Resources, Constants, Configuration Files, Registry or other data sources.

Library Design

General Library Design Guidelines

1. DO design a framework that is both powerful and easy to use.

2. DO provide a layered framework with high-level APIs optimized for productivity and low-level APIs optimized for power and expressiveness.

3. AVOID mixing low-level and high-level APIs in a single namespace.

4. DO ensure that layers of a single feature are well integrated and complete. Developers should be able to migrate from one level to another without re-writing the entire application.

5. DO base your design on meaningful usage scenarios.

6. DO ensure scenarios that correspond to an appropriate abstraction level.

7. DO design APIs by first writing code samples for the main scenario then defining the object model to support the code.

8. DO organize usability studies to test API in main scenarios.

9. DO provide simple overloads of constructors and methods with a small number of primitive parameters.

10. DO NOT require user to explicitly instantiate more than one type in the most basic scenarios.

11. DO provide good defaults for all properties and parameters if possible.

12. DO communicate incorrect usage of APIs using exceptions.

13. DO provide strongly typed APIs if at all possible.

14. DO NOT create circular references between assemblies.

15. CONSIDER factoring unsafe code into a separate assembly.

16. DO use zero-based indexing when developing with the Framework.

Azure Deployment Guidelines

As part of the Engineering practice, it would be ideal to let TFS handle the deployment to Azure as part of the daily builds. Here are some advantages of doing this:

· Being able to build, package, and deploy our projects to multiple Windows Azure environments from a build server using MSBuild

· Being able to retain copies of our packages and configurations for our builds in Windows Azure BLOB Storage for safe keeping, history, easy rollback scenarios, etc.

· Having a build number generated for a build and make sure that build number is present in the name of our packages, configs, and deployment labels in Azure for consistency

· Leveraging the Release Configurations in Visual Studio as much as possible as the designation of our different environments, since Web.Config transformations rely on this pattern already

· Being able to still package and deploy locally, in case there is an issue with the build server for some reason

Greater depth on the deployment can be found here - http://blogs.msdn.com/b/tomholl/archive/2011/12/06/automated-build-and-deployment-with-windows-azure-sdk-1-6.aspx

Here are some technical requirements to get setup with automatic deployment:

· Install Windows Azure tools on build server

· Install Windows Azure powershell cmdlets

· Download publish settings from http://windows.azure.com/downloads/publishprofile.aspx

· In MSBuild build definition setting, under process set it to

o /t:Publish /p:PublishDir=C:\Builds\Drops\;Configuration=DevPreview;AzurePublishProfile=<Your profile>.azurePubxml

The Future of ChronoZoom

We envision a world where scientists, researchers, students, and teachers collaborate through ChronoZoom to share information via data, tours, and insight.

Imagine a world where the leading academics publish their findings to the world in a manner that can easily be accessed and compared to other data.

Imagine a tool that allows teachers to generate tours specific to their classroom needs.

This can happen with your support. As ChronoZoom through the beta release, we need your feedback and support to continue to mold this project to suit your needs.

Help ChronoZoom evolve by taking this survey so we can provide the best possible future features: http://www.zoomerang.com/Survey/WEB22EFZBLQL4B/

Updated Wiki: ChronoZoom Developer's Guide

BobWalter — Sat, 14 Apr 2012 02:02:55 GMT

Note: As of 4/7/2012 this guide was revised. The code base was also modified to support easier adoption. If you downloaded the source code before 4/7/2012, please download again if you plan to use this guide.

Disclaimer

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.

Distributed under Creative Commons Attribution 3.0 Unported License.

Microsoft, Visual Studio, and Windows are trademarks of the Microsoft group of companies. All other trademarks are property of their respective owners.

Introduction

This guide is designed to walk developers through the installation process. Some of the APIs for ChronoZoom are not yet available for the public.

Prerequisites

Hardware Requirements:

· A computer that can run Visual Studio 2010.

· Optionally, a network connection for the content links.

Software Requirements:

· Visual Studio 2010 with Service Pack 1 (Check “Help” and “About” to determine if you have SP1 installed. If you don’t, you can get it here.)

· Installation of Azure SDK (.net)

o Recommend installing from this page: http://www.windowsazure.com/en-us/develop/downloads/

· SQL Data Tools (Click this link to begin download SQL Data Tools) Service pack 2 of Visual Studio must be installed before you attempt this install.

· SQL Server 2008 or later Standard, Express, Developer, or Enterprise Edition

Project setup instructions

Here are the steps to get the source code and prepare for execution:

1. Download the code as zip file from Codeplex at http://chronozoom.codeplex.com/

2. Extract the zip into a folder.

3. Open the chronozoom.sln under the source folder (double-click on the file in windows explorer).

4. Right-click the Chronozoom.Database in Visual Studio Solution Explorer and click Publish.

5. In the dialog box, select the target database connection string to deploy to.

6. Click Publish.

7. In the chronozoom.UI project, under the scripts folder, locate the cz.settings.js

8. Replace current value of this with contentItemThumbnailBaseUri = 'http://127.0.0.1:10000/devstoreaccount1/images/';

a. Replace the text [Your domain] in the chronozoom.svc.cs file with localhost:4949 address. Also replace [Your domain] in “var req= WebRequest.Create”

9. Replace the text [Your domain] in the ChronozoomRelay.cs file with localhost:4949

10. Connect ChronoZoom to the database in the Chronozoom UI project, edit web.config

a. Go to server explorer

b. Add connection to the database we published before

c. Right clicked on the newly selected connection

d. Select properties

e. Copy connection string from the properties

f. Paste into Web.config “data source = {insert your data source and add “;”

11. Now go to the Authoring.Azure project and edit Web.config

a. Find connection string and inster the data source as before.

12. Configure thumbnail generation

a. Under ThumbGenApp open app.config

b. Change [add your connection string here] to the connection string you got above.

c. Change [add your blob url here] to 'http://127.0.0.1:10000/devstoreaccount1/images/'

d. Change [add your azure connection string] to “UseDevelopmentStorage=true”

e. Build under configuration “Dev Preview” for platform “X86”

13. Set ChronoZoom.UI as the startup project. Right click on Chronozoom.UI project and select “set as startup project”. To run authoring tools:

a. Set Authoring.Azure as startup project.

b. Run. Login as “admin” password:”admin$”

15. Run and execute.

16. To generate thumbnails (required after adding content items) set ThumbGenApp as startup project.

How to Submit Code to the Project

After you have completed the code you want to add to the project, there are a few steps to follow to get your submission to the project team:

2. Create a zipped file with your changed code

a. Include any source files that have your changes. Please surround your changes/additions with comments that clearly explain what you are doing.

b. Provide a document that explains what you did and how it works.

3. Submit your changes on Codeplex:

i. Click “Submit a patch” on the chronozoom.codeplex.com site.

ii. On the “Upload a Patch” page, use the the “Browse” button to find your zipped file.

iii. In the description box, describe your patch, suggest a unit test if your can.

iv. Please note the work item that this patch fixes

v. Click Submit.

Coding Guidelines

Coding Conventions

Document Conventions

Our strongest recommendations are DO and DO NOT. DO and DO NOT recommendations should be followed 99.999% of the time to obtain the benefits of a consistent coding style. For example:

DO use descriptive parameter names.

DO NOT require user to explicitly instantiate more than one type in the most basic scenarios.

CONSIDER defining interfaces to achieve a similar effect to that of multiple inheritances.

AVOID using out or ref parameters.

Naming Conventions

Identifier	Public	Protected	Internal	Private	Notes
Project File	PascalCase	-	-	-	DO match Assembly and Namespace.
Source File	PascalCase	-	-	-	DO match Class name.
Namespace	PascalCase	-	-	-	DO use Project/Assembly name.
Class or Struct	PascalCase	PascalCase	PascalCase	PascalCase	CONSIDER adding suffix of sub-class.
Interface	PascalCase	PascalCase	PascalCase	PascalCase	DO prefix Interfaces with capital I.
Generic Class	PascalCase	PascalCase	PascalCase	PascalCase	DO use T or K as type identifier.
Method	PascalCase	PascalCase	PascalCase	PascalCase	CONSIDER using Verb or Verb-Object pair.
Property	PascalCase	PascalCase	PascalCase	PascalCase	DO NOT prefix with Get or Set.
Field	PascalCase	PascalCase	PascalCase	_camelCase	AVOID use of public Fields.
Static Field	PascalCase	PascalCase	PascalCase	_camelCase
Constant	PascalCase	PascalCase	PascalCase	_camelCase
Enum	PascalCase	PascalCase	PascalCase	PascalCase
Delegate	PascalCase	PascalCase	PascalCase	PascalCase
Event	PascalCase	PascalCase	PascalCase	PascalCase
Local variable	-	-	-	camelCase
Parameter	-	-	-	camelCase

Coding Style and Language Usage Conventions

Coding Style Issue	Style Guideline
Source Files	DO have only one Namespace and one Class per file.
Curly Braces	DO have braces on a new line. DO use a brace, even if syntactically optional.
Indentation	Do indent is 4 and convert tabs to spaces.
Comments	Do use // or ///.
Native Data Types	DO use built-in C# data types.
Enums	AVOID changing the default type.
Generics	CONSIDER generic types before standard or strong-typed classes.
Methods	AVOID large parameter lists (over 7). Use an array or object instead.
foreach	DO NOT modify enumerated objects within the body of the foreach loop.
Conditionals	DO NOT test against true or false. DO NOT embed code with side effects within a conditional. DO NOT embed an assignment. DO NOT embed a method invocation.
Exceptions	DO NOT use exceptions for normal flow control. DO NOT use “throw e;” when re-throwing, use “throw;”. DO avoid exceptions by validating pre/post conditions prior to the exception. DO derive from Exception, not ApplicationException.

Naming Conventions

Consistent naming procedures applied across all the various identifier types in a project goes a long way to making code more accessible to people that use the library or join the project after you.

General Naming Guidelines

1. DO use PascalCasing for type and method names and constants.

2. DO use camelCasing for local variable names and method arguments.

3. DO use ‘I’ to prefix Interface names.

4. DO NOT create names that vary only by case.

5. AVOID creating ALLCAPITALNAMES.

6. DO use easily readable, descriptive, meaningful, and specific names.

a. AVOID single character names.

b. AVOID Hungarian notation for public or protected members.

c. AVOID abbreviations unless the full name is really excessive.

d. AVOID adding redundant prefixes and suffixes e.g. public enum ColorsEnum {…}.

7. DO name types with nouns, noun phrases, or adjective phrases using PascalCasing.

8. CONSIDER ending the name of a derived classes with the name of the base class.

9. DO prefix Interface names with the letter ‘I’, to indicate that the type is an interface.

10. DO give methods names that are verbs or verb phrases.

11. DO name properties using a noun, noun phrase, or adjective.

12. CONSIDER giving a property the same name as its type.

13. DO name fields using a noun or noun phrase.

14. CONSIDER using common, well known acronyms, e.g. IO instead of InputOutput.

15. AVOID acronyms that are not common or widely known.

16. DO use uppercase for two-letter acronyms and PascalCase for other acronyms. It is acceptable to use “BIO” rather than “Bio” in the context of this project.

17. CONSIDER using C# types rather than aliases in the System namespace.

18. DO use capital letters for type placeholders in generics.

19. CONSIDER prefixing Boolean variables with “Can”, “Is”, or “Has”.

20. CONSIDER appending computational variables with the suffix “Average”, “Count”, “Sum”, “Min”, or “Max”.

21. DO use meaningful namespaces under the “Bio” root when extending the Framework.

22. DO use meaningful namespaces under your Product, Company, or Developer name for tools or code using the project.e.g. namespace MyCompany.MyProduct.MyNamespace;

Coding Style and Language Usage

General Style Guidelines

1. DO have a single file contribute to a single namespace.

2. DO have a single class in a single source file.

3. DO group all framework “using” namespaces together before custom or third party namespaces.

4. AVOID putting a “using” statement inside a namespace.

5. AVOID using fully qualified type names by using the “using” statement.

6. CONSIDER grouping internal class implementation by type in the following order:

a. Member variables.

b. Constructors & Finalizers.

c. Nested enums, structs, and classes.

d. Properties

e. Methods

7. DO explicitly declare the access modifier for all identifiers rather than relying on default.

8. CONSIDER grouping declarations within each type by their access modifier and visibility:

a. public

b. protected

c. internal

d. private

9. DO declare all member variables as private and provide public, protected, or internal property access where required.

10. DO declare each variable in its own statement.

11. DO use white space to organize and separate code.

12. DO maintain strict indentation of 4 spaces. DO NOT use tab characters in the documents.

13. DO indent all code blocks contained within curly braces.

14. DO place opening curly braces ( { ) on a new line.

15. DO indent comments to the same level as the code being described.

16. DO use correct spelling, grammar, and punctuation in all comments.

17. DO use // or /// for comments.

18. AVOID /* … */ for comments.

19. DO use inline comments to explain assumptions, issues, and algorithmic insights.

20. DO NOT use comments to explain obvious code.

21. DO use Task-List keywords in comments to allow filtering e.g.
// TODO:
// UNDONE:

22. DO use C# comment blocks for documenting the API.

23. DO use C# comment blocks for every public, protected, and internal declaration.

24. DO include <summary> comments.

25. DO include <param>, <return>, and <exception> comments where applicable.

26. DO declare local variables near their first use.

27. DO initialize local variables where you declare them.

28. DO use the simplest data type, collection, or object that meets your requirements.

29. AVOID specifying the type of an Enum. Use the default of int unless you have an explicit need for a long.

30. DO NOT use inline numeric literals (‘magic numbers’). Use Constant or Enum.

31. AVOID declaring string literals. Use Resources, Constants, Configuration Files, Registry or other data sources.

Library Design

General Library Design Guidelines

1. DO design a framework that is both powerful and easy to use.

2. DO provide a layered framework with high-level APIs optimized for productivity and low-level APIs optimized for power and expressiveness.

3. AVOID mixing low-level and high-level APIs in a single namespace.

4. DO ensure that layers of a single feature are well integrated and complete. Developers should be able to migrate from one level to another without re-writing the entire application.

5. DO base your design on meaningful usage scenarios.

6. DO ensure scenarios that correspond to an appropriate abstraction level.

7. DO design APIs by first writing code samples for the main scenario then defining the object model to support the code.

8. DO organize usability studies to test API in main scenarios.

9. DO provide simple overloads of constructors and methods with a small number of primitive parameters.

10. DO NOT require user to explicitly instantiate more than one type in the most basic scenarios.

11. DO provide good defaults for all properties and parameters if possible.

12. DO communicate incorrect usage of APIs using exceptions.

13. DO provide strongly typed APIs if at all possible.

14. DO NOT create circular references between assemblies.

15. CONSIDER factoring unsafe code into a separate assembly.

16. DO use zero-based indexing when developing with the Framework.

Azure Deployment Guidelines

As part of the Engineering practice, it would be ideal to let TFS handle the deployment to Azure as part of the daily builds. Here are some advantages of doing this:

· Being able to build, package, and deploy our projects to multiple Windows Azure environments from a build server using MSBuild

· Being able to retain copies of our packages and configurations for our builds in Windows Azure BLOB Storage for safe keeping, history, easy rollback scenarios, etc.

· Having a build number generated for a build and make sure that build number is present in the name of our packages, configs, and deployment labels in Azure for consistency

· Leveraging the Release Configurations in Visual Studio as much as possible as the designation of our different environments, since Web.Config transformations rely on this pattern already

· Being able to still package and deploy locally, in case there is an issue with the build server for some reason

Greater depth on the deployment can be found here - http://blogs.msdn.com/b/tomholl/archive/2011/12/06/automated-build-and-deployment-with-windows-azure-sdk-1-6.aspx

Here are some technical requirements to get setup with automatic deployment:

· Install Windows Azure tools on build server

· Install Windows Azure powershell cmdlets

· Download publish settings from http://windows.azure.com/downloads/publishprofile.aspx

· In MSBuild build definition setting, under process set it to

o /t:Publish /p:PublishDir=C:\Builds\Drops\;Configuration=DevPreview;AzurePublishProfile=<Your profile>.azurePubxml

The Future of ChronoZoom

We envision a world where scientists, researchers, students, and teachers collaborate through ChronoZoom to share information via data, tours, and insight.

Imagine a world where the leading academics publish their findings to the world in a manner that can easily be accessed and compared to other data.

Imagine a tool that allows teachers to generate tours specific to their classroom needs.

This can happen with your support. As ChronoZoom through the beta release, we need your feedback and support to continue to mold this project to suit your needs.

Help ChronoZoom evolve by taking this survey so we can provide the best possible future features: http://www.zoomerang.com/Survey/WEB22EFZBLQL4B/

Updated Wiki: ChronoZoom Developer's Guide

BobWalter — Sat, 14 Apr 2012 02:01:59 GMT

Note: As of 4/7/2012 this guide was revised. The code base was also modified to support easier adoption. If you downloaded the source code before 4/7/2012, please download again.

Disclaimer

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.

Distributed under Creative Commons Attribution 3.0 Unported License.

Microsoft, Visual Studio, and Windows are trademarks of the Microsoft group of companies. All other trademarks are property of their respective owners.

Introduction

This guide is designed to walk developers through the installation process. Some of the APIs for ChronoZoom are not yet available for the public.

Prerequisites

Hardware Requirements:

· A computer that can run Visual Studio 2010.

· Optionally, a network connection for the content links.

Software Requirements:

· Visual Studio 2010 with Service Pack 1 (Check “Help” and “About” to determine if you have SP1 installed. If you don’t, you can get it here.)

· Installation of Azure SDK (.net)

o Recommend installing from this page: http://www.windowsazure.com/en-us/develop/downloads/

· SQL Data Tools (Click this link to begin download SQL Data Tools) Service pack 2 of Visual Studio must be installed before you attempt this install.

· SQL Server 2008 or later Standard, Express, Developer, or Enterprise Edition

Project setup instructions

Here are the steps to get the source code and prepare for execution:

1. Download the code as zip file from Codeplex at http://chronozoom.codeplex.com/

2. Extract the zip into a folder.

3. Open the chronozoom.sln under the source folder (double-click on the file in windows explorer).

4. Right-click the Chronozoom.Database in Visual Studio Solution Explorer and click Publish.

5. In the dialog box, select the target database connection string to deploy to.

6. Click Publish.

7. In the chronozoom.UI project, under the scripts folder, locate the cz.settings.js

8. Replace current value of this with contentItemThumbnailBaseUri = 'http://127.0.0.1:10000/devstoreaccount1/images/';

a. Replace the text [Your domain] in the chronozoom.svc.cs file with localhost:4949 address. Also replace [Your domain] in “var req= WebRequest.Create”

9. Replace the text [Your domain] in the ChronozoomRelay.cs file with localhost:4949

10. Connect ChronoZoom to the database in the Chronozoom UI project, edit web.config

a. Go to server explorer

b. Add connection to the database we published before

c. Right clicked on the newly selected connection

d. Select properties

e. Copy connection string from the properties

f. Paste into Web.config “data source = {insert your data source and add “;”

11. Now go to the Authoring.Azure project and edit Web.config

a. Find connection string and inster the data source as before.

12. Configure thumbnail generation

a. Under ThumbGenApp open app.config

b. Change [add your connection string here] to the connection string you got above.

c. Change [add your blob url here] to 'http://127.0.0.1:10000/devstoreaccount1/images/'

d. Change [add your azure connection string] to “UseDevelopmentStorage=true”

e. Build under configuration “Dev Preview” for platform “X86”

13. Set ChronoZoom.UI as the startup project. Right click on Chronozoom.UI project and select “set as startup project”. To run authoring tools:

a. Set Authoring.Azure as startup project.

b. Run. Login as “admin” password:”admin$”

15. Run and execute.

16. To generate thumbnails (required after adding content items) set ThumbGenApp as startup project.

How to Submit Code to the Project

After you have completed the code you want to add to the project, there are a few steps to follow to get your submission to the project team:

2. Create a zipped file with your changed code

a. Include any source files that have your changes. Please surround your changes/additions with comments that clearly explain what you are doing.

b. Provide a document that explains what you did and how it works.

3. Submit your changes on Codeplex:

i. Click “Submit a patch” on the chronozoom.codeplex.com site.

ii. On the “Upload a Patch” page, use the the “Browse” button to find your zipped file.

iii. In the description box, describe your patch, suggest a unit test if your can.

iv. Please note the work item that this patch fixes

v. Click Submit.

Coding Guidelines

Coding Conventions

Document Conventions

Our strongest recommendations are DO and DO NOT. DO and DO NOT recommendations should be followed 99.999% of the time to obtain the benefits of a consistent coding style. For example:

DO use descriptive parameter names.

DO NOT require user to explicitly instantiate more than one type in the most basic scenarios.

CONSIDER defining interfaces to achieve a similar effect to that of multiple inheritances.

AVOID using out or ref parameters.

Naming Conventions

Identifier	Public	Protected	Internal	Private	Notes
Project File	PascalCase	-	-	-	DO match Assembly and Namespace.
Source File	PascalCase	-	-	-	DO match Class name.
Namespace	PascalCase	-	-	-	DO use Project/Assembly name.
Class or Struct	PascalCase	PascalCase	PascalCase	PascalCase	CONSIDER adding suffix of sub-class.
Interface	PascalCase	PascalCase	PascalCase	PascalCase	DO prefix Interfaces with capital I.
Generic Class	PascalCase	PascalCase	PascalCase	PascalCase	DO use T or K as type identifier.
Method	PascalCase	PascalCase	PascalCase	PascalCase	CONSIDER using Verb or Verb-Object pair.
Property	PascalCase	PascalCase	PascalCase	PascalCase	DO NOT prefix with Get or Set.
Field	PascalCase	PascalCase	PascalCase	_camelCase	AVOID use of public Fields.
Static Field	PascalCase	PascalCase	PascalCase	_camelCase
Constant	PascalCase	PascalCase	PascalCase	_camelCase
Enum	PascalCase	PascalCase	PascalCase	PascalCase
Delegate	PascalCase	PascalCase	PascalCase	PascalCase
Event	PascalCase	PascalCase	PascalCase	PascalCase
Local variable	-	-	-	camelCase
Parameter	-	-	-	camelCase

Coding Style and Language Usage Conventions

Coding Style Issue	Style Guideline
Source Files	DO have only one Namespace and one Class per file.
Curly Braces	DO have braces on a new line. DO use a brace, even if syntactically optional.
Indentation	Do indent is 4 and convert tabs to spaces.
Comments	Do use // or ///.
Native Data Types	DO use built-in C# data types.
Enums	AVOID changing the default type.
Generics	CONSIDER generic types before standard or strong-typed classes.
Methods	AVOID large parameter lists (over 7). Use an array or object instead.
foreach	DO NOT modify enumerated objects within the body of the foreach loop.
Conditionals	DO NOT test against true or false. DO NOT embed code with side effects within a conditional. DO NOT embed an assignment. DO NOT embed a method invocation.
Exceptions	DO NOT use exceptions for normal flow control. DO NOT use “throw e;” when re-throwing, use “throw;”. DO avoid exceptions by validating pre/post conditions prior to the exception. DO derive from Exception, not ApplicationException.

Naming Conventions

Consistent naming procedures applied across all the various identifier types in a project goes a long way to making code more accessible to people that use the library or join the project after you.

General Naming Guidelines

1. DO use PascalCasing for type and method names and constants.

2. DO use camelCasing for local variable names and method arguments.

3. DO use ‘I’ to prefix Interface names.

4. DO NOT create names that vary only by case.

5. AVOID creating ALLCAPITALNAMES.

6. DO use easily readable, descriptive, meaningful, and specific names.

a. AVOID single character names.

b. AVOID Hungarian notation for public or protected members.

c. AVOID abbreviations unless the full name is really excessive.

d. AVOID adding redundant prefixes and suffixes e.g. public enum ColorsEnum {…}.

7. DO name types with nouns, noun phrases, or adjective phrases using PascalCasing.

8. CONSIDER ending the name of a derived classes with the name of the base class.

9. DO prefix Interface names with the letter ‘I’, to indicate that the type is an interface.

10. DO give methods names that are verbs or verb phrases.

11. DO name properties using a noun, noun phrase, or adjective.

12. CONSIDER giving a property the same name as its type.

13. DO name fields using a noun or noun phrase.

14. CONSIDER using common, well known acronyms, e.g. IO instead of InputOutput.

15. AVOID acronyms that are not common or widely known.

16. DO use uppercase for two-letter acronyms and PascalCase for other acronyms. It is acceptable to use “BIO” rather than “Bio” in the context of this project.

17. CONSIDER using C# types rather than aliases in the System namespace.

18. DO use capital letters for type placeholders in generics.

19. CONSIDER prefixing Boolean variables with “Can”, “Is”, or “Has”.

20. CONSIDER appending computational variables with the suffix “Average”, “Count”, “Sum”, “Min”, or “Max”.

21. DO use meaningful namespaces under the “Bio” root when extending the Framework.

22. DO use meaningful namespaces under your Product, Company, or Developer name for tools or code using the project.e.g. namespace MyCompany.MyProduct.MyNamespace;

Coding Style and Language Usage

General Style Guidelines

1. DO have a single file contribute to a single namespace.

2. DO have a single class in a single source file.

3. DO group all framework “using” namespaces together before custom or third party namespaces.

4. AVOID putting a “using” statement inside a namespace.

5. AVOID using fully qualified type names by using the “using” statement.

6. CONSIDER grouping internal class implementation by type in the following order:

a. Member variables.

b. Constructors & Finalizers.

c. Nested enums, structs, and classes.

d. Properties

e. Methods

7. DO explicitly declare the access modifier for all identifiers rather than relying on default.

8. CONSIDER grouping declarations within each type by their access modifier and visibility:

a. public

b. protected

c. internal

d. private

9. DO declare all member variables as private and provide public, protected, or internal property access where required.

10. DO declare each variable in its own statement.

11. DO use white space to organize and separate code.

12. DO maintain strict indentation of 4 spaces. DO NOT use tab characters in the documents.

13. DO indent all code blocks contained within curly braces.

14. DO place opening curly braces ( { ) on a new line.

15. DO indent comments to the same level as the code being described.

16. DO use correct spelling, grammar, and punctuation in all comments.

17. DO use // or /// for comments.

18. AVOID /* … */ for comments.

19. DO use inline comments to explain assumptions, issues, and algorithmic insights.

20. DO NOT use comments to explain obvious code.

21. DO use Task-List keywords in comments to allow filtering e.g.
// TODO:
// UNDONE:

22. DO use C# comment blocks for documenting the API.

23. DO use C# comment blocks for every public, protected, and internal declaration.

24. DO include <summary> comments.

25. DO include <param>, <return>, and <exception> comments where applicable.

26. DO declare local variables near their first use.

27. DO initialize local variables where you declare them.

28. DO use the simplest data type, collection, or object that meets your requirements.

29. AVOID specifying the type of an Enum. Use the default of int unless you have an explicit need for a long.

30. DO NOT use inline numeric literals (‘magic numbers’). Use Constant or Enum.

31. AVOID declaring string literals. Use Resources, Constants, Configuration Files, Registry or other data sources.

Library Design

General Library Design Guidelines

1. DO design a framework that is both powerful and easy to use.

2. DO provide a layered framework with high-level APIs optimized for productivity and low-level APIs optimized for power and expressiveness.

3. AVOID mixing low-level and high-level APIs in a single namespace.

4. DO ensure that layers of a single feature are well integrated and complete. Developers should be able to migrate from one level to another without re-writing the entire application.

5. DO base your design on meaningful usage scenarios.

6. DO ensure scenarios that correspond to an appropriate abstraction level.

7. DO design APIs by first writing code samples for the main scenario then defining the object model to support the code.

8. DO organize usability studies to test API in main scenarios.

9. DO provide simple overloads of constructors and methods with a small number of primitive parameters.

10. DO NOT require user to explicitly instantiate more than one type in the most basic scenarios.

11. DO provide good defaults for all properties and parameters if possible.

12. DO communicate incorrect usage of APIs using exceptions.

13. DO provide strongly typed APIs if at all possible.

14. DO NOT create circular references between assemblies.

15. CONSIDER factoring unsafe code into a separate assembly.

16. DO use zero-based indexing when developing with the Framework.

Azure Deployment Guidelines

As part of the Engineering practice, it would be ideal to let TFS handle the deployment to Azure as part of the daily builds. Here are some advantages of doing this:

· Being able to build, package, and deploy our projects to multiple Windows Azure environments from a build server using MSBuild

· Being able to retain copies of our packages and configurations for our builds in Windows Azure BLOB Storage for safe keeping, history, easy rollback scenarios, etc.

· Having a build number generated for a build and make sure that build number is present in the name of our packages, configs, and deployment labels in Azure for consistency

· Leveraging the Release Configurations in Visual Studio as much as possible as the designation of our different environments, since Web.Config transformations rely on this pattern already

· Being able to still package and deploy locally, in case there is an issue with the build server for some reason

Greater depth on the deployment can be found here - http://blogs.msdn.com/b/tomholl/archive/2011/12/06/automated-build-and-deployment-with-windows-azure-sdk-1-6.aspx

Here are some technical requirements to get setup with automatic deployment:

· Install Windows Azure tools on build server

· Install Windows Azure powershell cmdlets

· Download publish settings from http://windows.azure.com/downloads/publishprofile.aspx

· In MSBuild build definition setting, under process set it to

o /t:Publish /p:PublishDir=C:\Builds\Drops\;Configuration=DevPreview;AzurePublishProfile=<Your profile>.azurePubxml

The Future of ChronoZoom

We envision a world where scientists, researchers, students, and teachers collaborate through ChronoZoom to share information via data, tours, and insight.

Imagine a world where the leading academics publish their findings to the world in a manner that can easily be accessed and compared to other data.

Imagine a tool that allows teachers to generate tours specific to their classroom needs.

This can happen with your support. As ChronoZoom through the beta release, we need your feedback and support to continue to mold this project to suit your needs.

Help ChronoZoom evolve by taking this survey so we can provide the best possible future features: http://www.zoomerang.com/Survey/WEB22EFZBLQL4B/

Updated Wiki: Documentation

BobWalter — Sat, 14 Apr 2012 01:59:23 GMT

Join the Conversation
Let us know what you think; ask questions, make comments, start a new discussion topic. You are very welcome to become an active part of this project. Click here to join in.

Further Reading
There are several documents that provide additional information about ChronoZoom:

- Quick Reference Guide

- User Guide

- How To Become A Developer For The ChronoZoom Project

- Developer's Guide Revised 4/7/2012

- Architecture Guide

Frequently Asked Questions

Q: Why does the animation appear slow or choppy on my Computer?

Q. Why do the graphic appear slow or fuzzy in Firefox 10.x ?

Q. I am having issues viewing ChronoZoom through Chrome. Everything is very slow. What can I do?

A. This is a known issue for Chrome due to the WebKit canvas performance instability. Chrome is working on a fix for this issue on their next release.

Q. ChronoZoom sometimes stops working for me and I can’t figure out why.

Q. When using Firefox, I am having difficulty with tour audio. What can I do?

A. This is a known issue for Firefox. This article might be able to assist you.

Updated Wiki: Documentation

bobwalter — Thu, 05 Apr 2012 19:13:31 GMT

Join the Conversation
Let us know what you think; ask questions, make comments, start a new discussion topic. You are very welcome to become an active part of this project. Click here to join in.

Further Reading
There are several documents that provide additional information about ChronoZoom:

- Quick Reference Guide

- User Guide

- How To Become A Developer For The ChronoZoom Project

- Developer's Guide Revised!

- Architecture Guide

Frequently Asked Questions

Q: Why does the animation appear slow or choppy on my Computer?

Q. Why do the graphic appear slow or fuzzy in Firefox 10.x ?

Q. I am having issues viewing ChronoZoom through Chrome. Everything is very slow. What can I do?

A. This is a known issue for Chrome due to the WebKit canvas performance instability. Chrome is working on a fix for this issue on their next release.

Q. ChronoZoom sometimes stops working for me and I can’t figure out why.

Q. When using Firefox, I am having difficulty with tour audio. What can I do?

A. This is a known issue for Firefox. This article might be able to assist you.

Updated Wiki: ChronoZoom Developer's Guide

bobwalter — Fri, 30 Mar 2012 21:53:33 GMT

Disclaimer

This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal, reference purposes.

Distributed under Creative Commons Attribution 3.0 Unported License.

Microsoft, Visual Studio, and Windows are trademarks of the Microsoft group of companies. All other trademarks are property of their respective owners.

Introduction

This guide is designed to walk developers through the installation process. Some of the APIs for ChronoZoom are not yet available for the public.

Prerequisites

Hardware Requirements:

· A computer that can run Visual Studio 2010.

· Optionally, a network connection for the content links.

Software Requirements:

· Visual Studio 2010 with Service Pack 1 (Check “Help” and “About” to determine if you have SP1 installed. If you don’t, you can get it here.)

· Installation of Azure SDK (.net)

o Recommend installing from this page: http://www.windowsazure.com/en-us/develop/downloads/

· SQL Data Tools (Click this link to begin download SQL Data Tools) Service pack 2 of Visual Studio must be installed before you attempt this install.

· SQL Server 2008 or later Standard, Express, Developer, or Enterprise Edition

Project setup instructions

Here are the steps to get the source code and prepare for execution:

1. Download the code as zip file from Codeplex at http://chronozoom.codeplex.com/

2. Extract the zip into a folder.

3. Open the chronozoom.sln under the source folder (double-click on the file in windows explorer).

4. Right-click the Chronozoom.Database in Visual Studio Solution Explorer and click Publish.

5. In the dialog box, select the target database connection string to deploy to.

6. Click Publish.

7. In the chronozoom.UI project, under the scripts folder, locate the cz.settings.js

8. Replace current value of this with contentItemThumbnailBaseUri = 'http://127.0.0.1:10000/devstoreaccount1/images/';

a. Replace the text [Your domain] in the chronozoom.svc.cs file with localhost:4949 address. Also replace [Your domain] in “var req= WebRequest.Create”

9. Replace the text [Your domain] in the ChronozoomRelay.cs file with localhost:4949

10. Connect ChronoZoom to the database in the Chronozoom UI project, edit web.config

a. Go to server explorer

b. Add connection to the database we published before

c. Right clicked on the newly selected connection

d. Select properties

e. Copy connection string from the properties

f. Paste into Web.config “data source = {insert your data source and add “;”

11. Now go to the Authoring.Azure project and edit Web.config

a. Find connection string and inster the data source as before.

12. Configure thumbnail generation

a. Under ThumbGenApp open app.config

b. Change [add your connection string here] to the connection string you got above.

c. Change [add your blob url here] to 'http://127.0.0.1:10000/devstoreaccount1/images/'

d. Change [add your azure connection string] to “UseDevelopmentStorage=true”

e. Build under configuration “Dev Preview” for platform “X86”

13. Set ChronoZoom.UI as the startup project. Right click on Chronozoom.UI project and select “set as startup project”. To run authoring tools:

a. Set Authoring.Azure as startup project.

b. Run. Login as “admin” password:”admin$”

15. Run and execute.

16. To generate thumbnails (required after adding content items) set ThumbGenApp as startup project.

How to Submit Code to the Project

After you have completed the code you want to add to the project, there are a few steps to follow to get your submission to the project team:

2. Create a zipped file with your changed code

a. Include any source files that have your changes. Please surround your changes/additions with comments that clearly explain what you are doing.

b. Provide a document that explains what you did and how it works.

3. Submit your changes on Codeplex:

i. Click “Submit a patch” on the chronozoom.codeplex.com site.

ii. On the “Upload a Patch” page, use the the “Browse” button to find your zipped file.

iii. In the description box, describe your patch, suggest a unit test if your can.

iv. Please note the work item that this patch fixes

v. Click Submit.

Coding Guidelines

Coding Conventions

Document Conventions

Our strongest recommendations are DO and DO NOT. DO and DO NOT recommendations should be followed 99.999% of the time to obtain the benefits of a consistent coding style. For example:

DO use descriptive parameter names.

DO NOT require user to explicitly instantiate more than one type in the most basic scenarios.

CONSIDER defining interfaces to achieve a similar effect to that of multiple inheritances.

AVOID using out or ref parameters.

Naming Conventions

Identifier	Public	Protected	Internal	Private	Notes
Project File	PascalCase	-	-	-	DO match Assembly and Namespace.
Source File	PascalCase	-	-	-	DO match Class name.
Namespace	PascalCase	-	-	-	DO use Project/Assembly name.
Class or Struct	PascalCase	PascalCase	PascalCase	PascalCase	CONSIDER adding suffix of sub-class.
Interface	PascalCase	PascalCase	PascalCase	PascalCase	DO prefix Interfaces with capital I.
Generic Class	PascalCase	PascalCase	PascalCase	PascalCase	DO use T or K as type identifier.
Method	PascalCase	PascalCase	PascalCase	PascalCase	CONSIDER using Verb or Verb-Object pair.
Property	PascalCase	PascalCase	PascalCase	PascalCase	DO NOT prefix with Get or Set.
Field	PascalCase	PascalCase	PascalCase	_camelCase	AVOID use of public Fields.
Static Field	PascalCase	PascalCase	PascalCase	_camelCase
Constant	PascalCase	PascalCase	PascalCase	_camelCase
Enum	PascalCase	PascalCase	PascalCase	PascalCase
Delegate	PascalCase	PascalCase	PascalCase	PascalCase
Event	PascalCase	PascalCase	PascalCase	PascalCase
Local variable	-	-	-	camelCase
Parameter	-	-	-	camelCase

Coding Style and Language Usage Conventions

Coding Style Issue	Style Guideline
Source Files	DO have only one Namespace and one Class per file.
Curly Braces	DO have braces on a new line. DO use a brace, even if syntactically optional.
Indentation	Do indent is 4 and convert tabs to spaces.
Comments	Do use // or ///.
Native Data Types	DO use built-in C# data types.
Enums	AVOID changing the default type.
Generics	CONSIDER generic types before standard or strong-typed classes.
Methods	AVOID large parameter lists (over 7). Use an array or object instead.
foreach	DO NOT modify enumerated objects within the body of the foreach loop.
Conditionals	DO NOT test against true or false. DO NOT embed code with side effects within a conditional. DO NOT embed an assignment. DO NOT embed a method invocation.
Exceptions	DO NOT use exceptions for normal flow control. DO NOT use “throw e;” when re-throwing, use “throw;”. DO avoid exceptions by validating pre/post conditions prior to the exception. DO derive from Exception, not ApplicationException.

Naming Conventions

Consistent naming procedures applied across all the various identifier types in a project goes a long way to making code more accessible to people that use the library or join the project after you.

General Naming Guidelines

1. DO use PascalCasing for type and method names and constants.

2. DO use camelCasing for local variable names and method arguments.

3. DO use ‘I’ to prefix Interface names.

4. DO NOT create names that vary only by case.

5. AVOID creating ALLCAPITALNAMES.

6. DO use easily readable, descriptive, meaningful, and specific names.

a. AVOID single character names.

b. AVOID Hungarian notation for public or protected members.

c. AVOID abbreviations unless the full name is really excessive.

d. AVOID adding redundant prefixes and suffixes e.g. public enum ColorsEnum {…}.

7. DO name types with nouns, noun phrases, or adjective phrases using PascalCasing.

8. CONSIDER ending the name of a derived classes with the name of the base class.

9. DO prefix Interface names with the letter ‘I’, to indicate that the type is an interface.

10. DO give methods names that are verbs or verb phrases.

11. DO name properties using a noun, noun phrase, or adjective.

12. CONSIDER giving a property the same name as its type.

13. DO name fields using a noun or noun phrase.

14. CONSIDER using common, well known acronyms, e.g. IO instead of InputOutput.

15. AVOID acronyms that are not common or widely known.

16. DO use uppercase for two-letter acronyms and PascalCase for other acronyms. It is acceptable to use “BIO” rather than “Bio” in the context of this project.

17. CONSIDER using C# types rather than aliases in the System namespace.

18. DO use capital letters for type placeholders in generics.

19. CONSIDER prefixing Boolean variables with “Can”, “Is”, or “Has”.

20. CONSIDER appending computational variables with the suffix “Average”, “Count”, “Sum”, “Min”, or “Max”.

21. DO use meaningful namespaces under the “Bio” root when extending the Framework.

22. DO use meaningful namespaces under your Product, Company, or Developer name for tools or code using the project.e.g. namespace MyCompany.MyProduct.MyNamespace;

Coding Style and Language Usage

General Style Guidelines

1. DO have a single file contribute to a single namespace.

2. DO have a single class in a single source file.

3. DO group all framework “using” namespaces together before custom or third party namespaces.

4. AVOID putting a “using” statement inside a namespace.

5. AVOID using fully qualified type names by using the “using” statement.

6. CONSIDER grouping internal class implementation by type in the following order:

a. Member variables.

b. Constructors & Finalizers.

c. Nested enums, structs, and classes.

d. Properties

e. Methods

7. DO explicitly declare the access modifier for all identifiers rather than relying on default.

8. CONSIDER grouping declarations within each type by their access modifier and visibility:

a. public

b. protected

c. internal

d. private

9. DO declare all member variables as private and provide public, protected, or internal property access where required.

10. DO declare each variable in its own statement.

11. DO use white space to organize and separate code.

12. DO maintain strict indentation of 4 spaces. DO NOT use tab characters in the documents.

13. DO indent all code blocks contained within curly braces.

14. DO place opening curly braces ( { ) on a new line.

15. DO indent comments to the same level as the code being described.

16. DO use correct spelling, grammar, and punctuation in all comments.

17. DO use // or /// for comments.

18. AVOID /* … */ for comments.

19. DO use inline comments to explain assumptions, issues, and algorithmic insights.

20. DO NOT use comments to explain obvious code.

21. DO use Task-List keywords in comments to allow filtering e.g.
// TODO:
// UNDONE:

22. DO use C# comment blocks for documenting the API.

23. DO use C# comment blocks for every public, protected, and internal declaration.

24. DO include <summary> comments.

25. DO include <param>, <return>, and <exception> comments where applicable.

26. DO declare local variables near their first use.

27. DO initialize local variables where you declare them.

28. DO use the simplest data type, collection, or object that meets your requirements.

29. AVOID specifying the type of an Enum. Use the default of int unless you have an explicit need for a long.

30. DO NOT use inline numeric literals (‘magic numbers’). Use Constant or Enum.

31. AVOID declaring string literals. Use Resources, Constants, Configuration Files, Registry or other data sources.

Library Design

General Library Design Guidelines

1. DO design a framework that is both powerful and easy to use.

2. DO provide a layered framework with high-level APIs optimized for productivity and low-level APIs optimized for power and expressiveness.

3. AVOID mixing low-level and high-level APIs in a single namespace.

4. DO ensure that layers of a single feature are well integrated and complete. Developers should be able to migrate from one level to another without re-writing the entire application.

5. DO base your design on meaningful usage scenarios.

6. DO ensure scenarios that correspond to an appropriate abstraction level.

7. DO design APIs by first writing code samples for the main scenario then defining the object model to support the code.

8. DO organize usability studies to test API in main scenarios.

9. DO provide simple overloads of constructors and methods with a small number of primitive parameters.

10. DO NOT require user to explicitly instantiate more than one type in the most basic scenarios.

11. DO provide good defaults for all properties and parameters if possible.

12. DO communicate incorrect usage of APIs using exceptions.

13. DO provide strongly typed APIs if at all possible.

14. DO NOT create circular references between assemblies.

15. CONSIDER factoring unsafe code into a separate assembly.

16. DO use zero-based indexing when developing with the Framework.

Azure Deployment Guidelines

As part of the Engineering practice, it would be ideal to let TFS handle the deployment to Azure as part of the daily builds. Here are some advantages of doing this:

· Being able to build, package, and deploy our projects to multiple Windows Azure environments from a build server using MSBuild

· Being able to retain copies of our packages and configurations for our builds in Windows Azure BLOB Storage for safe keeping, history, easy rollback scenarios, etc.

· Having a build number generated for a build and make sure that build number is present in the name of our packages, configs, and deployment labels in Azure for consistency

· Leveraging the Release Configurations in Visual Studio as much as possible as the designation of our different environments, since Web.Config transformations rely on this pattern already

· Being able to still package and deploy locally, in case there is an issue with the build server for some reason

Greater depth on the deployment can be found here - http://blogs.msdn.com/b/tomholl/archive/2011/12/06/automated-build-and-deployment-with-windows-azure-sdk-1-6.aspx

Here are some technical requirements to get setup with automatic deployment:

· Install Windows Azure tools on build server

· Install Windows Azure powershell cmdlets

· Download publish settings from http://windows.azure.com/downloads/publishprofile.aspx

· In MSBuild build definition setting, under process set it to

o /t:Publish /p:PublishDir=C:\Builds\Drops\;Configuration=DevPreview;AzurePublishProfile=<Your profile>.azurePubxml

The Future of ChronoZoom

We envision a world where scientists, researchers, students, and teachers collaborate through ChronoZoom to share information via data, tours, and insight.

Imagine a world where the leading academics publish their findings to the world in a manner that can easily be accessed and compared to other data.

Imagine a tool that allows teachers to generate tours specific to their classroom needs.

This can happen with your support. As ChronoZoom through the beta release, we need your feedback and support to continue to mold this project to suit your needs.

Help ChronoZoom evolve by taking this survey so we can provide the best possible future features: http://www.zoomerang.com/Survey/WEB22EFZBLQL4B/