Given a file with the right data structure, contract( ) can parse your own templates to be used with contract( )'s interface. If you are confident about making or editing JSON files, you can start immediately with converting your own agreement into something contract( ) can parse, or download one of the examples and loading them in contract( ):
Not so confident with JSON? I recommend to start with the chapter called 'JSON' below.
If you're just here for the reference, quickly jump to sections, template variables, or template HTML.
Don't let the 'code stuff' scare you. JSON is pretty easy and the examples explanatory! JSON is a data structure built for javascript. It's basically a bunch of 'objects', 'variables' and 'arrays' that can contain objects, variables, and arrays. An example of a JSON file could be:
{
"variable" : "value",
"object" :
{
"variable" : "value",
"array":
[
"array 0 value",
"array 1 value",
"array 2 value"
],
"numberVariable" : 45.000
},
"array" : [ "item 1", "item 2" ]
}I could tell you more on how JSON works, but most of it isn't too important. However, when editing, these are the main rules:
I recommend using a simple code editor like TextMate 2 on OS X or Notepad++ on Windows to edit your JSON files. These editors will often show you if you've made a mistake in your file. Which brings me to...
Making mistakes in JSON files is very easy and super common. contract( ) isn't able to give you feedback other than 'error' when your file has errors, but you can use online JSON validators like this one to see what went wrong where. Often it's a missing or misplaced comma that causes the error, but the error messages there can explain you more about the problem.
Contract( ) files have multiple sections of which the first two are required to be named contractInfo and agreement. The section named contractInfo is meant for metadata, and the example below shows which variables are parsed by contract( ). The section named agreement is basically a regular section, with the exception that some data, like the company's, collaborator's, or projects name, can be used throughout the agreement - more on that later. The rest of the sections can be named as you like.
{
"contractInfo" : {
"language" : "en",
"version" : 1.10,
"basedOnEnglishVersion" : 1.10,
"lastModification" : "8 Oct. 2015"
},
"agreement" : {…},
"yourOwnSection" : {…},
"superDescriptiveName" : {…},
"signatures" : {…}
}For contract( ) to work with your template, every section (other than the metadata section 'contractInfo') is required to have at least the template array. An example of a minimal section would then look as follows:
"minimal section name" : {
"template" :
[
{
"text" : "<p>a section without header, selector, or variables!</p>",
"variables":
{
}
}
]
}Want a header? Add the header variable to your section, preceded by a numbering tag [#] to automagically number the header. If you don't want to number your headers, just don't include [#].
"section name" : {
"header": "[#] section title",
"template" :
[
{
"text" : "<p>this section has a header.</p>",
"variables":
{
}
}
]
}If you want to be able to select different templates within a section of your agreement, you need to do two additional things: add a select object to your section (example below), and make sure that there are as many templates as there are selectable options.
"sectionName" : {
"header": "[#] section title",
"select" :
{
"label" : "label of selector",
"description" : "description of selector",
"options":
[
"option 1 name",
"option 2 name"
]
},
"template" :
[
{
"text" : "<p>Text for the first option...</p>",
"variables":
{
}
},
{
"text" : "<p>Text in the second option...</p>",
"variables":
{
}
}
]
}
The coolest thing about contract( ) is its template variables. There are three types of template variables: labels (simple text fields), checkboxes, and lists (text fields that get added and removed dynamically based on their size).
Variables are placed in the variables object of a template, and are placed in your template's text with the name or tag of the variable encapsulated with square brackets. I call these [things in brackets] tags. As an example, notice how the tag [nameTag] inside the text variable has the same name as the variable inside variables:
"template" :
[
{
"text" : "<p>My name is [nameTag].</p>",
"variables":
{
"nameTag" : {
"label" : "What is your name?",
"placeholder" : "John Doe",
"description" : "Your full name.",
"examples" : ["John Doe", "Adriaan de Jongh"]}
}
}
]All three template variables have a bunch of settings:
A label tag in the template text is simply replaced by the text entered by you through the contract( ) interface.
"labelTag" : {
"label" : "this text appears above the input field",
"placeholder" : "this text appears inside the input field",
"description" : "this text appears when hovering over the question mark",
"examples" : ["this text shows below the input field as example", "this example too!"]}If you want a label only to show up when a checkbox is ticked, you can add a variable called onlyDisplayIfChecked containing the tag of the checkbox that it depends on. To make a label show up when a checkbox is unticked, use onlyDisplayIfUnchecked instead.
"labelTag" : {
"label" : "label text",
"placeholder" : "placeholder text",
"description" : "description text",
"examples" : ["example text", "example text"],
"onlyDisplayIfChecked" : "checkboxTag"}The variables examples and description are not required.
A checkbox tag in the template text is replaced by the text set in the checked or unchecked settings of a checkbox:
"checkboxTag" : {
"type" : "checkbox",
"label" : "text next to checkbox",
"isChecked" : false,
"checked" : "text put in template text when this checkbox is checked",
"unchecked" : "text put in template text when this checkbox is unchecked",
"description" : "checkbox description text"}The isChecked setting sets the default state of the checkbox. If you don't want text in the checked or unchecked state of the checkbox, you can replace the text (including the double apostrophes at the start and end) with the word null. And just like a label, you can add onlyDisplayIfChecked or onlyDisplayIfUnchecked with the name of the dependent tag to only make it show up when that checkbox is checked or unchecked.
"checkboxTag" : {
"type" : "checkbox",
"label" : "text next to checkbox",
"isChecked" : false,
"checked" : "checkbox checked text",
"unchecked" : null,
"description" : "checkbox description text",
"onlyDisplayIfChecked" : "differentCheckboxTag"}The variable description is not required.
It's possible to put label tags in checkbox checked or unchecked text. These often work in combination with the onlyDisplayIfChecked or onlyDisplayIfUnchecked settings:
"section example" : {
"template" :
[
{
"text" : "<p>My name is [fullOrFirstName].</p>",
"variables":
{
"fullOrFirstNameCheckbox" : {
"type" : "checkbox",
"label" : "Use full name?",
"isChecked" : false,
"checked" : "(f+l name) [firstName] [lastName]",
"unchecked" : "(f name only) [firstName]",
"description" : "Display first AND last name?"},
"firstName" : {
"label" : "What is your first name?",
"placeholder" : "John",
"description" : "Your first name.",
"examples" : ["John", "Adriaan"]},
"lastName" : {
"label" : "What is your last name?",
"placeholder" : "Doe",
"description" : "Your last name.",
"examples" : ["Doe", "de Jongh"],
"onlyDisplayIfChecked" : "fullOrFirstNameCheckbox"}
}
}
]
}List tags are replaced by bullet points lists in your template text:
"listTag" : {
"type" : "list",
"list" : [],
"label" : "text above list",
"placeholderItem" : "placeholder for item",
"placeholderAdd" : "placeholder for add",
"description" : "description of list",
"examples" : ["list example 1", "list example 2"]}You may add a prefix and separator settings to a list so that the start of all list items are the same. In that case, a number will be placed in between the prefix and separator. The code for that looks like this:
"listTag" : {
"type" : "list",
"list" : [],
"label" : "text above list",
"placeholderItem" : "placeholder for item",
"placeholderAdd" : "placeholder for add",
"prefix" : "prefix text ",
"separator" : ", ",
"description" : "description of list",
"examples" : ["list example 1", "list example 2"]}It's also possible to make a list that takes its amount of items from another list: this is especially helpful if you need to make sure that two lists always have the same amount of items (like, for example, a payment per milestone). The list that requires the amount of items then needs an additional four variables:
"listTakingVariables" : {
"type" : "list",
"list" : [],
"takeListLengthSectionID" : "sectionContainingOtherList",
"takeListLengthTemplateID" : 0,
"takeListLengthVariableID" : "exampleListVariable",
"takeListLengthWarning" : "Select the first option somewhere up here and add items!",
"label" : "this list takes its length from the list above",
"placeholderItem" : "label placeholder item",
"placeholderAdd" : "label placeholder add",
"description" : "list description.",
"examples" : ["list example 1", "list example 2"]},The variables examples and description are not required.
As you might have spotted above, almost all of the text in the agreement is located inside the text variable of templates. The text inside this variable is parsed as HTML to allow you to define paragraphs and lists separately. Below are some examples of HTML things you will probably want to use to make your own contract( ) templates.
"<p>This is a paragraph.</p>""<p>These words are <strong>bold</strong> and <em>slanted</em>.</p>""<p>The first paragraph.</p><p>The second paragraph.</p>""<ul><li>First list item.</li><li>Second list item.</li></ul>""<ol><li>First list item.</li><li>First list item.</li></ol>"A note on lists: lists should not be placed inside paragraphs. See the example below how you keep paragraphs and lists separate!
"<p>The first paragraph.</p><ol><li>First list item.</li><li>Second list item.</li></ol><p>The second paragraph.</p>"Although I do not recommend adding subheaders to the text, you can if you need to. The headers tagged with h1 are reserved for the section headers: you can still use them, but you would really be screwing with the system if you did!
"<h2>This is a subheader</h2><p>The first paragraph.</p>"(This isn't strictly speaking HTML, but who cares. Useful anyway!)
"<p>[#.#] ← This tag will be replaced by the contract builder with the appropriate numbers, e.g. '2.4.'.</p><p>[#.#] ← You can put these things anywhere in your text!</p>""minimal section example" : {
"template" :
[
{
"text" : "<p>[#.#] This is a paragraph with a <strong>bold</strong> and a <em>slanted</em> word. The following is a list (outside this paragraph!):</p> <ul><li>List item 1.</li><li>List item 2.</li></ul> <p>[#.#] And this paragraph comes after the list!.</p>",
"variables":
{
}
}
]
}If you already have your own agreement and you are looking at contact( ) to make the filling-it-in part easier, this is how you can do that:
Things you can do to optimise your template:
If you can't figure things out, even after trying the JSON validator, you can ask a friend programmer (he or she will know...), tweet at me, or shoot me an email and I'll try to help you as soon as possible.
Custom contract( ) templates are still in beta, and I'm looking for feedback on the feature itself and this reference / guide. Shoot me an email if you think anything is missing or have suggestions for changes.