Integrating Treaty

Treaty was designed to be quick and easy to integrate, while providing you ample opportunities to customize it according to your specific needs. Here you'll find answers to the most common integration questions, basic installation instructions, full API documentation, and links to tutorials. We hope you find the information you need, but if you still have questions, just open a support request and we'll get back to you within 24 hours.

Basic Treaty Installation

  1. Sign up for a Treaty account, selecting any of the available plans.
  2. Once you have logged in, you will see your API key. This is what you'll need to communicate between your application and Treaty.
  3. Install tinyMCE and jQuery in the appropriate folder.
  4. Copy and paste the required Treaty libraries into the head of your website: <script type="text/javascript" src="https://treatytime.com:4900/socket.io/socket.io.js"></script> <script type="text/javascript" src="https://treatytime.com:4900/treaty/treaty.js"></script> <script type="text/javascript" src="https://treatytime.com:4900/treaty/tinymceEditor.js"></script>
  5. Add a text area into the body of your document:
  6. Add the Treaty code to the head of your document. The simplest example is below, but can be customized to fit your needs: <script type="text/javascript"> //when the document is loaded $(document).ready(function() { //Setup the session Session = new Treaty.Session({ sessionID : "MySessionID", apiKey : "MY-API-KEY" }); //connect the session to the server Session.connect(); //set up tinyMCE tinyMCE.init({ mode: "textareas", setup : function(ed) { //when tinymce is set up, create the Treaty editor instance Session.addEditor( new Treaty.TinymceEditor({ editorID : "MyEditorID", textarea : "myTextArea", tinymce : ed }) ); }.cc(this) }); }); </script>
  7. Login to treatytime.com to retrieve your API Key. Replace "MY-API-KEY" with your unique API Key.
  8. Start collaborating!

Customizing Your Treaty Implementation

We built Treaty specifically with customizability in mind. Almost every aspect of the application can be tweaked to your specific needs. You may want to consider customizing:

  • The look of the text editor
  • The elements displayed in the text editor toolbar
  • The file browser display
  • Whether users can see who else is present
  • Document import and export options
  • Change history display

These are simply some of the ways we customized Treaty as we implemented it on this site. There are many other ways to change the way it looks and functions to fit your situation. For more extensive examples, see the Examples and Tutorials section of this document.

API Documentation

Treaty.Session

Treaty.Session(settings)
This defines and handles the connection to the Treaty server and contains (among other things) the list of the people and a list of the editors used during the session. Sessions will typically have multiple users and may have multiple editors.

Settings

sessionID (default: random string)
Optional. A unique ID used to identify the session. This will typically be generated by the implementing application (recommended). For two users to connect to the same session, the sessionID for the users must be identical. While optional, if the default random string is used, it will be random for each session instance and therefore will not allow multiple users to collaborate.
me (default: new Treaty.Person)
Optional. A Treaty.Person instance representing the user/client connected to this session. This user can be created manually by the implementing application (recommended) or can be randomly generated by Treaty.
apiKey (default: false)
Required. The API Key attached to your account. This is required to ensure the validity of your account.
serverURL(default: https://treatytime.com)
Optional. The url that the Treaty server is located at. If hosting your own Treaty server, you can set this to point to your own server.
cometPort(default: 4900)
Optional. As with serverURL, this can be changed if you host your own version of the Treaty server.

Methods

connect()
connect to the Treaty server.
isLeader()
Find out of this client is the session’s leader. The leader is set by the server to indicate which client should handle some events.
send(eventName, params [, sendSequence])
Send an event to the server. eventName is a string defining the name of the event. params is an object/associative array defining any parameters required to handle the event. sendSequence is an optional, Boolean that lets the server know if the order of this event is important.
pushPerson(person)
adds a person to the session. Person may either be a predefined Treaty.Person or an object with settings for a Treaty.Person. If person is an object of settings, it will generate a Treaty.Person using those settings and then add that to the session. Otherwise, it will simply add person to the session. Does not notify the server. Triggers the personPushed event.
addPerson(person)
calls pushPerson to add a person to the session, then broadcasts and event to let the server know that a person was added to the session. Triggers the personAdded event.
popPerson(person)
removes a person from the session. The parameter may either be a Treaty.Person or a personID string. Does not notify the server. Triggers the personPopped event.
removePerson(person)
Similar to addPerson, this first calls popPerson to remove the person from the session, then notifies the server. Triggers the personRemoved event.
pushEditor(editor)
adds an editor to the session. The required editor parameter must be an object of type Treaty.Editor or a type inherited from Treaty.Editor (i.e. Treaty.TinymceEditor). Will call the editor’s bindEvents method. Returns false if the editor has already been added to the session.
addEditor([editor])
Recommended over pushEditor. Adds an editor to the session after confirming its type. If optional parameter editor is left undefined, it will generate an object of type Treaty.Editor. If editor is an object of settings, it will generate a Treaty.Editor using those settings. If the editor’s type is given, it will create an editor of that type (i.e. editor.type = "TinymceEditor" will generate a Treaty.TinymceEditor). If the editor is already a Treaty.Editor, it will simply pass that off to pushEditor.
popEditor(editor)
removes an editor from the session. Parameter editor can be either an editor object or a string. If the parameter is a string, it must be the editor’s editorID.
removeEditor(editor)
calls popEditor and notifies the server that an editor has been removed.
getEditorByTextareaID(textareaID)
returns the Treaty.Editor object from the session by the text area’s id attribute. Will return false if not found.
saveHistory(history)
will save a chunk of editor history to the server. Will send the post request to the url session.serverURL + "/ajax/savehistory". By default, this will be http://treatytime.com/ajax/savehistory, but if you host your own and use a different serverURL, it will be different. Will send the apiKey, the sessionID, the history provided in the parameter, and the array of people that are currently in the session.
bind(eventName, callback)
Will bind a function to the session. eventName is the name of the event. callback is the function to be called when the event is triggered.
trigger(eventName, parameters)
Triggers an event that has been attached to the session. eventName is the name of the event. parameters are any additional parameters that will be sent to the bound callback function. The callback function will always be sent the event as the first parameter, followed by all others defined in parameters.

Treaty.Person

Treaty.Person(settings)
a person is any user connected to a session. A person can be randomly generated resulting in, essentially, an anonymous connection, but more than likely, a person’s information will come from a user database belonging to the implementing application.

Settings

personID(default: random string)
Optional. A unique identifier for each person. If one is not provided, a random ID is generated. Often, this will correspond with a user ID from an application’s user database.
info(default: empty object)
Optional. Additional user info can be added her as an associative array. For example, info.nickname or info.emailAddress.

Methods

toArray()
Returns an associative array/object that contains no functions so that the Treaty.Person can more easily be sent through AJAX or stored in a database.

Treaty.TinymceEditor

Treaty.Editor(settings)
Treaty.Editor is a generic class created as an interface between an editor and the session. It allows us to programmatically manipulate the editor and synchronize it with other clients.

Settings

editorID(default: random string)
a unique identifier for each editor. This can be generated randomly or can be set manually. In order for two clients to collaborate on an editor, each client’s editor must have the same editorID.
type(default: "Editor")
If the editor is of a different, but inherited type (i.e. Treaty.TinymceEditor), this will indicate that type (TinymceEditor).
content(default: "")
the content being held by the editor. Not necessarily the content that is displayed in the editor.
session(default: empty object)
a reference to the Treaty.Session to which this editor is attached.
textarea(default: empty textarea element)
The textarea that the editor is attached to. This may be string indicating the id of an element, an HTML element, or left empty. If an ID is provided, Treaty will use jQuery to access the element. If left empty, Treaty will create an empty textarea but leave it unattached.
tinymce(default: false)
the tinymce instance that this editor is attached to.

Other Attributes

currentHash
an MD5 hash based on the content of the editor. Allows easy checking of content equality.
history
an object holding the history of this editor. Only populated after a history request is made.

Methods

toArray([noContent])
Returns an array of the attributes with no methods so that the editor may be passed around easier. If the optional parameter noContent is set to true, the content attribute will be set to false, thus reducing the size of the returned object.
attach(parent)
Will attach the editor’s text area to the parent element. parent may be either an ID string or a jquery object of the element to which the textarea needs to be attached. Can be used if you don’t actually have a texteditor on the page and it was dynamically generated.
requestHistory(callback)
Requests the history from the server. callback is a function to be called when the server returns the history. History will only be the portion of history being held in memory by the Treaty server.
getHistory(callback)
Makes an AJAX request to the server in order to get the full history saved in the database. Will call Treaty.Session.serverURL + "/ajax/gethistory" (by default: https://treatytime.com/ajax/gethistory). callback is a function to be called when the ajax request is completed successfully.
patch(payload, person[, theirSequenceNumber, mySequenceNumber])
patches the editor’s content with whatever payload was sent to it. This function is typically called when the session receives a broadcast that someone else has changed the editor. Payload will contain the actual content to be patched. Person will be the person who sent the patch. TheirSequenceNumber is the sequence position that the server thinks this patch is supposed to be in. mySequenceNumber is the sequence position that this client’s Treaty.Session thinks that this patch is supposed to be in.
startPatchingFromQueue()
By default, patches are typically queued in order to ensure that they are applied in the proper order. This will start applying the patches that are in the queue.
read()
gets the raw content from the textarea and sets the Content attribute to that content. Returns the content.
getRawContent()
gets the content from the text area without changing the Content attribute.
overwriteContent(newContent)
overwrites the content in the editor with the value of newContent.
updateHash([newHash])
if the newHash parameter is set, it will simple replace the value of currentHash with that of newHash. If no newHash is given, it will calculate a new hash based on the content of the text area and update currentHash.
calcHash(string)
calculate an md5 hash from the given string.
setCursorPosition(pos)
Sets the cursor position in the editor to the index in pos.
getCursorPosition()
gets the position of the cursor in relation to the editor’s content
bindEvents()
Initializes the events required to synchronize the editors across clients.
bind(eventName, callback)
bind the callback function to the eventName event.
unbind(eventName)
remove the event binding from the editor
trigger(eventName, parameters)
trigger the given event and send parameters with it.
onChangeFunction()
creates a payload based on current contents of and triggers the contentChanged event. Will typically send a broadcast with the payload to all other clients connected to the session.
setTinymce(tinymceeditor)
if the tinymce instance is not set when the editor is created , it can be set manually using this function.

Helper Functions

In addition to the libraries, Treaty comes with a number of helper functions that are used in the libraries and may be used freely.

guid(prefix)
Returns a unique ID. If the prefix parameter is not empty, the prefix will be added to the beginning of the id.
Function.prototype.cc(that)
.cc can be used to change the context of a function. By adding this onto the end of a function, you can modify the contents of the 'this' keyword inside of a function. The parameter 'that' is the object that 'this' will become inside the function.
addslashes(string)
Returns the given string with slashes added before quotation marks. Replicates the PHP function of the same name.
stripslashes(string)
Returns a the given string with the slashes stripped from the quotation marks. The opposite of addslashes.

Documentation is a work in progress. Full API documentation is coming very shortly! We apologize for the delay.

Examples and Tutorials

You can find a number of examples and tutorials at our knowledge base: https://treaty.tenderapp.com/kb

Code Together on LinkedIn Follow Treaty on Twitter