Hypercities

When preparing a KML file produced by Google Earth, Google Maps, or by hand, it’s important to ensure that it’s compatible with HyperCities before uploading it. HyperCities supports most, but not all, of the standard KML tags. The following is a diagram of all the tags that HyperCities supports:

Tags recognized by HyperCities in a KML file.

This diagram does not include elements that describe placemarks and folders, like “title”, but these should be interpreted correctly.

Please also note that the link, location, scale, and orientation tags only work if they are associated with a model, not a 2D object.

Snapshots are a useful feature of Hypercities. They allow you to save a certain configuration of Hypercities — objects, maps, and viewport settings — and reload it later. The links you use can be embedded as links within Hypercities objects themselves, so that clicking on a link can take a user to a different time and place. Xreatig them is fairly simple. It requires a little bit of knowledge of HTML, but not too much. Here’s how:

1. Create your snapshot. To do this, set up Hypercities exactly as you want it, then click on the snapshot button. Remember the number at the end of the URL that you’ll be given.

2. Open the object that you want to put the link to the snapshot inside. Click on the “HTML” button. This will display the HTML source code of the text in your object. Find the text you want the user to click on to display the snapshot. Just before the text, without leaving a space, enter the following:

<a snapshotid=”1234″>

Replace 1234 with the number you were given when you created the snapshot.

Just after the text, again without leaving a space, enter this: </a>

What you should end up with is something like the following:

<a snapshotid=”1234″>Click me to display the snapshot!</a>

3. Save your edits as normal. Now, when a user clicks on the link, they should be taken to the exact state you created. Clicking on the link again will take them back.

On the web, like in Project Muse or Wikipedia, citations generally take the form of endnotes: clicking on a note in a piece of text scrolls your browser to the bottom of the page, where the corresponding endnote is contained. This doesn’t work in Hypercities, unfortunately, but Hypercitities has something better: citations that open a new window with the text inside them. The procedure for creating these is a little bit complex, but it’s easy once you get the hang of it.

First, each citation must have a reference code unique within that particular piece of content. This code can be something as simple as ‘1′ for the first one, ‘2′ for the second, and so on, but the important thing is that they must be unique within the description of that particular object. You can reuse the same codes in different objects, even if they’re within the same collection. Codes are used to link the links (the piece of text you click on) to the text that is displayed in the window when it pops up. They can contain letters and numbers, but please avoid other characters or spaces.

Once you have your list of codes, you can begin to enter them. If the content is already in Hypercities, you enter it using the editor. You can also add them to a KML file if you’re planning to upload your collection as a KML file.

Using the edit window:

1) Open the edit window. Once it’s open, click on the HTML button. Your text should look different now, with a lot of codes you didn’t see before between greater-than and less-than characters. This is because you are now editing the HTML code that controls how your text is displayed.

2) Find the piece of text you would like the user to click on to display the footnote.

3) Just before this piece of text, without a space, insert the following code:

<citation ref=”refcode“>

Replace “refcode” with the code for this citation.

4) After the text the user will click on to display the citation, you must close the tag. Again, right after that text, enter the following text:

</citation>

Do this for all your citations.

5) At the very end of the document, you enter the text that will be displayed for each citation.

If not, what this means is that you need to create another list of all the text you want to create. Use the following template.

<CitationList> (This needs to appear before the first citation)

<citation ref=”refcode“>Here is the text to be displayed</citation>

<citation ref=”refcode2“>Here is the text to be displayed for your second footnote</citation>

(Put more citations here)

</CitationList> (This needs to appear after the last citation)

HTML is allowed within the <citation> elements, but don’t put anything else between the <CitationList> and the <citation> tags inside it.

If you know XML, we are creating a CitationList element with citation children that have “ref” attributes with the same refcodes that you used before. The text of these children will be what is displayed in the new window when the user clicks on the link.

Please note: the text that the user clicks on to display the citation will automatically appear blue, superscripted, and underlined. Do not apply these styles yourself. In fact, if you put a <sup> tag around the text, it will be double-superscripted.

If you’re uploading a KML file, just follow steps 2-5, and make sure these all of this appears in the CDATA section of the description element of each object. The CitationList must also appear inside the CDATA element at the end of it.

Uploading a KML file is a relatively simple process. Reproducing a complex collection structure is less simple, however, but still fairly easy. Since each KML file you upload becomes its own collection, it takes some time to reproduce a complex collection structure. This article attempts to explain how to do this with the least pain possible:

1. Outline your collection hierarchy.

While it’s easy to change the hierarchy once your items are already in Hypercities, creating the hierarchy first will save you some time. For our example, let’s suppose we’re working on a project called “The Programmer and the Author,” and we have four files, houseofleaves.kml, infinitejest.kml, whitenoise.kml, and neuromancer.kml. Let’s also suppose we want to have the following hierarchy:

• The Programmer and the Author
  • The 1980s
    • William Gibson, Neuromancer (neuromancer.kml)
    • Don DeLillo, White Noise (whitenoise.kml)
  • The 1990s
    • David Foster Wallace, Infinite Jest (infinitejest.kml)
    • Mark Z. Danielewski, House of Leaves (houseofleaves.kml)

2. Create the top-level collection.

This is the “meta-collection.” Once you’re logged in, go to “My Profile” and click on “Create a New Collection.”

how to create a new collection

Fill in the required information. In this case, the collection is called “The Programmer and the Author.” This collection may not show up in Hypercities yet because it doesn’t have anything in it.

3. Create any subcollections that will contain more than one collection.

Collections with more than one collection should be the next thing you add. Click on “Create a New Collection” again and enter the appropriate name, e.g. “The 1980s.” Be sure when you do this to add the collection to the collection it will be inside on the “Add To …” tab.

Here, we would add “The 1980s” to “The Programmer and the Author.” Again, these collections may not show up in Collection List view (though they will show up in the Add To … tab) if they have nothing in them.

4. Upload the KML into the appropriate place.

Now is when the real fun begins. Once you have created the collections, upload your first KML file. Click on the Add Media button.

The bottom button is the “Import K ML” button. Click on this.

In the window that pops up, fill in the required information. You must fill in a title, but this will be ignored if a name is specified in the file.

Once you have entered the appropriate information on the first two tabs, click on the Add To tab. Put this in the appropriate collection. Here, we would be putting whitenoise.kml into “The 1980s.”

Click the “submit” button.

Repeat the process for all the files.

Helpful tips:

• Before uploading your files, check them by opening them in Google Earth. This will validate that your KML is correct. If there’s a problem, it will frequently give you a more accurate assessment of what is wrong than Hypercities.
• If you only want your sub-collections to appear as collections of the collection that contains them, be sure that the containing collection is the only collection checked in the “Add To …” tab. Otherwise, they will show up under any collections that have been checked.

The first video is a basic introduction to adding media in HyperCities:

The second video will teach you the basics of creating a map using Google My Maps.

The third video tells you how to add your Google My Map into HyperCities.

If you would you like to give out a link directly to an object or a collection, you can use its permalink URL. These URLs direct Hypercities straight to one object or one collection.

To find an object’s permalink, look in its information bubble. Click on it once it’s on the map, then click on “More info…” and copy the URL from “Link to this object” field.

To find a link to a collection, go to the collection’s Narrative Viewby clicking on the double arrow (>>) next to its name, and click on “Link to this collection.” Also, once you open Narrative View, the URL in your browser’s location bar will contain the URL that will link you back to this collection.

A Note on Permalinks

You’ll notice that all the links folow this basic format:

http://hypercities.ats.ucla.edu/#item_type=collection&item_id=8835

However, if you are one of the lucky people who was using Hypercities before July 2009, you may have a URL with a question mark (?) rather than a hash symbol (#):

http://hypercities.ats.ucla.edu/?item_type=collection&item_id=8835

These will still work, but it’s better if you swap out the question mark for a hash symbol. Putting in a question mark causes Hypercities to reset itself every time you change the link. Using the hash symbol doesn’t.