Building Your Story

Raintale stories consist of two main features: a title and a list of memento URLs (URI-Ms). Raintale accepts this information in two formats:

  • a simple text file containing a list of URI-Ms to be used in concert with the --title argument
  • a JSON file containing complex information like the list of URI-Ms, the title, surrounding text, and other values for use with a given template

Simple Text File

Raintale accepts a simple text file containing URI-Ms, like so:

Raintale will generate a surrogate based on each URI-M in this text file and publish them in the order that they exist in this text file. As noted in Raintale Options, when using a text file you must also supply a value for the title of the story using the --title argument.

Complex Story With JSON

Raintale also accepts more complex input in the form of a JSON file. This more complex format allows the story author to supply additional metadata and insert text elements into the story. Below is an example complex story using JSON.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
    "title": "My Story Title",
    "collection_url": "https://archive.example.com/mycollection",
    "generated_by": "My Curator",
    "metadata": {
        "myKey1": "value1",
        "my-Key2": "value2",
        "my key 3": "value 3"
    },
    "elements": [
        {
            "type": "text",
            "value": "Livestream from Oakland which remains hot, gas canisters used, arrests, warnings now about more arrests.  \"Chemical agents will be used.\""
        },
        {
            "type": "link",
            "value": "http://wayback.archive-it.org/2950/20120510205501/http://www.thenation.com/blog/167643/may-day-special-occupyusa-blog-may-1-frequent-updates/"
        },
        {
            "type": "text",
            "value": "For Shame: Hundreds Of Arrests Across the Country Today"
        },
        {
            "type": "link",
            "value": "http://wayback.archive-it.org/2950/20120814042704/http://occupyarrests.wordpress.com/"
        }
    ]
}

Using JSON, the story author can specify the title of the story with the title key, shown above on line 2. As mentioned in Raintale Options, if the title key is specified here, the --title parameter does not need to be specified to tellstory on the command line. The value of the --title parameter overrules the value of the title key in the JSON file.

Lines 3 and 4 show how a story author can supply values for collection_url and generated_by. As noted in Raintale Options, if the --collection_url or --generated_by arguments are specified to tellstory, then the values supplied with those arguments will override the values in this JSON file.

Lines 5 through 9 demonstrate how the story author can provide additional metadata in the form of a JSON object of keys and values. You can utilize keys from metadata to fill specific values in your template. See the section Creating Your Own Templates for more information on how templates work.

Lines 10 through 27 contain the elements of your story. Each element consists of a JSON object with two keys: type and value. Raintale will process each element’s value differently based on its type.

The following values are available for type:

  • text
    • a raw string to be inserted into your story as is
    • if this text contains markup, then that markup will be inserted as well
    • if including markup in the corresponding value, consider how it will be displayed (e.g., HTML markup with a Twitter storyteller will write HTML tags to your Tweets, which Twitter will not render)
  • link
    • a URI-M that will be converted into a surrogate based on the chosen template
    • as mentioned before, only URI-Ms are supported

Note

Additional values for type may be available in the future based on user needs. Please submit an issue if the existing types do not suit your needs.