custom contract( ) reference BETA

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.

JSON

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:

  1. Comma's act like new lines and must be placed after every variable, object, and array, except for the last thing. That is because the computer also expects something to come after a comma, so if there is nothing there... 'error'. Notice the use of comma's up here: after defining every class, variable, or array, there is a comma - but also not in between!
  2. For every opening character, there must be a closing character. These opening characters are: ' " [ {
  3. Text always goes inside single or double apostrophes. That's how a computer knows it's text. Numbers don't get wrapped in apostrophes.
  4. No returns inside variables, and to use single or double apostrophes, add a forward slash (\) in front of it. Like this: "The company\'s property."
  5. Keep the file formatting clean! Use indents (using Tab) for objects and arrays inside variables and objects. See the tabbed structure above? It keeps the whole thing 'readable'.

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...

JSON validation

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.

Sections

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": 
			{
			
			}
		}
	]
}

Template 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:

Labels

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.

Checkboxes

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.

Example of section combining labels and checkboxes

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": 
			{
				"fullOrFirstName" : { 
					"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"}
			}
		}
	]
}

Lists

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.

Template HTML text

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.

Simple paragraphs: <p>text</p>

"<p>This is a paragraph.</p>"

Bold and slanted text: <strong>text</strong> and <em>text</em>

"<p>These words are <strong>bold</strong> and <em>slanted</em>.</p>"

Multiple paragraphs

"<p>The first paragraph.</p><p>The second paragraph.</p>"

Lists: <ul> and <ol>

"<ul><li>First list item.</li><li>Second list item.</li></ul>"
  1. Numbered lists:
"<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>"

Headers: <h2>Header</h2> (or h3 or h4)

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>"

Numbering outside lists: [#] and [#.#]

(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>"

Example of a section with ALL THE HTML

"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": 
			{
				
			}
		}
	]
}

Converting your own agreement into a contract( ) template

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:

  1. Divide your agreement into chapters.
  2. Download essentials.json and copy/paste the section example from this reference (the example with header but without selector) enough times inside your JSON file to make sure you have a section for each chapter.
  3. Now copy/paste the contents of your JSON file into a JSON validator to fix any copy/pasting problems and avoid a giant mess later on.
  4. Add each chapter from your original agreement to the text variable of the corresponding section.
  5. Put all paragraphs of each chapter in their own HTML paragraphs. Remember: no returns, and add forward slashes before any apostrophes in your text.
  6. Validate your JSON file again.
  7. Replace every name, amount, or any other changeable item in your agreement with a tag, e.g. replace MyCompany with [companyName].
  8. For every tag, make a corresponding variable and fill in the settings.
  9. Validate your JSON file.
  10. Throw it in contract( ) and see what happens.

Things you can do to optimise your template:

Help!?

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.

Suggestions?

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.