- Copyright 2017
- Designed in Massachusetts
- Built in Ohio
Understanding Sapwood's fields is crucial to designing your data structure in way that will work for you. It's important in knowing how you will be retrieving data from the API. But it's also important to know what it will be like for your users to edit the data in Sapwood's UI.
This guide is really all about the
type option, nested a couple layers within the
fields option. That guide mentions the options available to you, but here's a bit more detail on each type.
For each type, we'll offer a brief description and then discuss how it works via the UI (on the Sapwood app), how it is returned via the API via a GET request, and what you would need to know if you are creating an element via API via a POST request.
A boolean is a fancy word for representing something that is either true or false.
UI: It is presented as a checkbox. If the box is checked, the field is considered
true, if not, it's
API (GET): It's value is returned as either
API (POST): When being created, it should be sent as either
Today the date provides only a simple way to enter dates through the UI, but the plans are to expand on the information available via the API to add additional methods and flexibility around dates.
UI: A date field looks like a string field, but when you focus upon the field, you are shown a date picker to make it easier to choose a date.
API (GET): Sapwood doesn't mess with dates, so it will be returned as a string just as it appeared on the form. The main function of the date field is to provide an easy way to edit via the UI.
API (POST): Sapwood doesn't mess with dates sent via the API. So it's totally up to you how you want to format it. However, since the UI is configurable, it's important you pay attention to date formats or you may end up with conflicts if sending different formats than you're receiving.
An element field is when you want to associate your current element to another element.
One example would be that you have a Company template, and an Employee template. Your Employee template would probably have an element field type named
company so you could specify the company for a particular employee.
UI: The UI will provide a dropdown list of the available elements and you can select the one that applies. The dropdown menu will use the value of each element's primary field. (This is why using unique values for your primary field is important.)
Note that if you've filtered the available templates to a single document template (see the
templates field option), the UI changes. Sapwood knows the association is going to be a document, so it adds a document chooser and an optional direct uploader.
API (GET): When receiving an element field through the API, you will be returned a JSON object for the association.
API (POST): But, when sending an element field to the API, you should specify the
id of the element with which you want to associate.
Sometimes, you want to associate your element to more than one element, you might work the other way around.
Support, along with your Company and Employee templates, you had a Department template and an employee could be in more than one department. Then your Department template would probably have an elements field type as
employees where you could select all employees within that department.
UI: This also appears as a dropdown menu by default. But as you select an item, that item is placed in a list below the dropdown menu and can be moved or rearranged.
Elements are stored in the order they appear on the form and they may be drag and dropped to be re-ordered.
Here, too, if you specify just one template and that template is a document, then you'll have a documents chooser and an uploader.
API (GET): The response is an array of JSON objects representing all associated elements.
API (POST): When associating many elements, they should be sent using the
id attributes of all items, separated by a comma.
There is a specific geocoding field type. This has caused problems for us and may very well be deprecated in an upcoming release without the proper support.
UI: A geocode field is a textarea, but when the value changes, Sapwood attempts to geocode and places the address below the field.
API (GET): A properly-geocoded address will be returned as an object with several keys to access the various parts of the address. These are subject to change depending on our geocoding service. We recommend you examine an address responses and use the piece that's appropriate. And note that the original address will be under the
API (POST): Simply post a string that represents the raw address (or geo coordinates) and Sapwood will handle the geocoding.
A select field is a simple dropdown, with options managed by you. Therefore, it requires that you also include the
options option in your field config.
UI: A dropdown returning the string of the selected option.
API (GET): A string of the selected option.
API (POST): A string representing the selected option. At this time, there is no validation taking place to ensure the string was correct. That's up to you to validate (for now).
A string is the default and the simplest field type. It's a simple, open text field.
UI: A text field.
API (GET): Plain text.
API (POST): Plain text, up to 255 characters.
A text field is like a string field, but renders a textarea for editing and can be longer than 255 characters.
UI: A textarea.
API (GET): Plain text.
API (POST): Plain text.
A WYSIWYG field is a text editor that adds HTML markup behind the scenes.
UI: A WYSIWYG editor.
API (GET): HTML text created by using the WYSIWYG editor.
API (POST): When creating an object, you can use plain text, and you can include HTML code. It is, at its core, a text field that is edited differently in Sapwood's UI.