API_SetFieldProperties

Overview

Use API_SetFieldProperties to set one or more properties of a field. You invoke this on a table-level dbid.

Typically, you use this call after you create a new field using API_AddField, to set up its default behavior. You can also use this call at any time if you want to change properties, even if the affected field has data.

The properties available for a field vary slightly for the different field types. To get all of the available properties for a field, and to get the field id (fid) needed, use the API_GetSchema call.

top

Request Parameters

Parameter Value Required?

<property name>property value</property name>

For example:

<default_value>Hello</default_value>

Name/value pairs for the properties to be set.

yes

fid

Field ID of the field to be changed

yes

ticket

A valid authentication ticket.

The authentication ticket is returned via the API_Authenticate call.

yes

apptoken

A valid application token.

yes, if the application requires application tokens

udata

A string value that you want returned. It will not be handled by QuickBase but it will be returned in the response.

no

 

top

Properties for all field types

Property tag Description Valid for these field types

appears_by_default

Specifies whether this field column automatically appears in all reports (views) for this table or whether this field must be explicitly added to each view.

Acceptable values are:

  • 1 - all views have this field by default.

  • 0 - no views have this field by default

All

bold

Specifies whether the value should display in bold font.

Acceptable values are:

  • 1 - turn on bolding

  • 0 - turn off bolding (default)

All

 

default_value

The text or value to be displayed in the field by default.

Specify the desired value.

All

fieldhelp

 

Lets you specify help text for the field. This results in a help icon (?) being displayed for the field in the Add record form. The content of fieldhelp is shown as a tooltip for that icon and displays if you double-click the icon.

Enter the desired help text.

All

find_enabled

Specifies whether QuickBase should search on this field.

For more information on how this property works, see the QuickBase online help.

  • 1 - QuickBase can search on this field. (default)

  • 0 - QuickBase will not search on this field.

All

 

label

The text that shows up as the column header in the table.

Any text value, limited by the maxlength and num_lines properties.

All

no_wrap

Allows/disallows wrapping of the displayed value. Acceptable values are:

  • 1 - disallows wrap (default)

  • 0 - allows wrap

All

required

Specifies whether a valid field value must be supplied or is optional. Acceptable values are:

  • 1 - value is required

  • 0 - value is optional (default)

All

 

unique

Specifies whether the field value must be unique within the table. Acceptable values are:

  • 1 - must be unique

  • 0 - duplicate values are allowed (default)

All

width

Specifies the width in characters of the column in views.

Specify the desired number of characters.

All

doesdatacopy

In the QuickBase UI, after you add a new record, the resulting display form shows a button called Add Similar. If the user clicks Add Similar to add another record, all fields with doesdatacopy set to 1 will be prefilled with values taken from that previously added record, overriding the default_value property.

All field types that accept user input

append-only

Allows you to keep a record of all entries for a field in a running log.

Append fields are regular text fields which record each entry and stamp the text with the name of the user who made the change and the date on which they did it. All entries display when the field is viewed or edited

The running log includes one line for the entry and the username of the person who originated the entry. New entries are appended at the end.

You can turn this on or off after you make appended entries: the entries already made will be retained even if the feature is turned off.

If you want an expanded style to be used, or time of day stamp, or the new entries to be prepended, you will have to change these settings in the QuickBase UI. Acceptable values are:

  • 1 - is an append field

  • 0 - is NOT an append field (default)

All text field types:

  • Text

  • Text - Multi-line

  • Text - Multiple-choice

maxlength

Specifies the maximum number of characters allowed in this field. Acceptable values are:

  • 0 - no limit

  • Any number other than 0.

All text field types:

  • Text

  • Text - Multi-line

  • Text - Multiple-choice

allowHTML

Enables HTML code within this text field. If this property is turned on users can enter HTML tags to format text, create custom links while in edit mode. When the record displays, QuickBase renders the code just like any browser would. The HTML option does not work with multiple-choice text fields.

  • Text

  • Text - Multi-line

choices

Aggregates default choices in a multiple-choice field, in this way:

<choices>
   <choice>1</choice>
   <choice>2</choice>
   <choice>N</choice>
</choices>

Specify the aggregate and choices.

All Text and Numeric field types

 

sort_as_given

Specifies how the sorting is to be done on the multiple choices in this field: alphabetically or following the order in which the choices were created.

Acceptable values are:

  • 1 - sort in the order of creation

  • 0 - sort alphabetically (default)

All Text and Numeric field types

allow_new_choices

Specifies whether users can supply their own choice in the multiple choice field or whether they are limited to accepting one of the displayed values.

  • 1 - allow new choices

  • 0 - disallow new choices (default)

  • All Text and Numeric field types

  • User

blank_is_zero

Specifies whether blank entries in this field will be treated as though the value "0" was entered.

Acceptable values are:

  • 1 - treat blank entries as zero (default)

  • 0 - do not treat blank entries as zero

  • Duration

  • All Numeric field types

 

numberfmt

Specifies the current number format (digit grouping, thousands separator, and decimal separator).

Acceptable values are:

  • 0 - 12345678.00

  • 3 - 12,345,678.00

  • 6 - 12.345.678,00

  • 7 - 12345678,00

  • 8 - 1,23,45,678.00

  • 10 - 1.23.45.678,00

All Numeric field types

comma_start

Specifies whether and how commas are to be used in numeric displays. Acceptable values are:

  • 3 - commas should be used in numbers larger than 999

  • 4 - commas should be used in numbers larger than 9999

All Numeric field types

does_average

Specifies whether QuickBase computes the average of all the values in this field and displays the result at the bottom of the view (AVG row). Acceptable values are:

  • 1 - display average

  • 0 - do not display average

  • Duration

  • All Numeric field types

does_total

Specifies whether QuickBase should compute the sum of all the values in this field and display the result at the bottom of the view (TOT row). Acceptable values are:

  • 1 - calculate totals

  • 0 - do not calculate totals

  • Duration

  • Checkbox

  • All Numeric field types

currency_format

Specifies the placement of the currency symbol. Acceptable values are:

  • 0 - before the number ($-1.00)

  • 1 - between the "-" and the number (-$1.00, default)

  • 2 - after the number (-1.00$)

Numeric - Currency

currency_symbol

Specifies the currency symbols to be displayed in this field. The default currency symbol is the dollar sign ($).

You can enter a different currency symbol if you'd like.

You can enter the currency symbol as either an HTML character entity or as a Unicode character code. For example, to display a pound sign (£), you would enter one of the following in the Symbol box:

  • &pound; (HTML character entity)

  • 0163 while holding down the ALT key (Unicode character code)

Numeric - Currency

decimal_places

Specifies the number of digits you want to display after the decimal point. For example, you might enter "2" if the field is a price field.

If a user enters more digits after the decimal point than you've entered here, QuickBase rounds the number and extends it only to the number of decimal places you specified. The fraction .5 rounds the number away from 0.  For example, 3.5 rounds to 4, and -3.5 rounds to -4.  If you would rather .5 always round up, meaning that -3.5 would round to -3, use the Round formula instead of the decimal places option for rounding.

Enter the number of digits you want to display after the decimal point. Leave blank for floating point.

  • All numeric field types

  • Duration

  • Time of Day

  • Formula -Numeric

  • Formula -Duration

  • Formula -Time of Day

default_today

Specifies whether the default date is today’s date. Acceptable values are:

  • 0 - no default date (default)

  • 1 - make the default date today’s date

  • Date

  • Date/Time

  • Formula fields of those types

display_dow

Turns the day of the week display on or off.

For example, if you turn this feature now, July 10, 2010 displays as follows:

Saturday, JUL 10

(with display_month set to name and display_relative set to 1)

Acceptable values are:

  • 0 - do not show day of week (default)

  • 1 - show day of week

  • Date

  • Date/Time

  • Formula fields of those types

 

display_month

Specifies whether the month is displayed as a name or a number. For example, July as a number is displayed as 07. As a name it is displayed as JUL. Acceptable values are:

  • number - display month as a number from 1 to 12

  • name - display the common three-character abbreviated name for the month

 

  • Date

  • Date/Time

  • Formula fields of those types

display_relative

Turns the QuickBase smart date feature on or off. This feature changes the display based on relative date/times. For example, a date that is today is displayed simply as “Today”. A date that falls within the current year omits the year, and so forth. See the QuickBase online help for full description of this feature.

Acceptable values are:

  • 0 - turn smart date off (default)

  • 1 - turn smart date on

  • Date

  • Date/Time

  • Formula fields of those types

 

display_time

Specifies whether the field shows date only in QuickBase UI or both date and time. This option turns a date field into a date-time field.

If you want both date and time displayed, you must supply both a date and a time or a default time will be supplied.

You can turn off the time display whenever you want. However any times already supplied will be saved and will reappear if you turn time display back on. Acceptable values are:

  • 0 - date-only display (default)

  • 1 - display date and time

  • Date

  • Date/Time

  • Formula -Date/Time

  • Formula - Date

display_zone

Turns on the display of time zone in certain hidden fields, such as time created and time last modified. Acceptable values are:

  • 0 - turn off time zone display (default)

  • 1 - turn on time zone display

Date/Time

Formula - Date/Time

has_extension

Used in phone field to specify whether an extension box will be displayed to the right of the telephone number. Acceptable values are:

  • 1 - show the extension box (default)

  • 0 - hide the extension box

Phone Number

display_as_button

Specifies whether a URL should display as a link or a button. Acceptable values are:

  • 0 - as a link (default)

  • 1 - as a button (instead of as a link)

URL and Formula - URL

formula

Specifies a valid formula for a formula field.

All Formula fields

top

Response values

Element Name Value

action

The originating request, for example, API_SetFieldProperties.

errcode

Identifies the error code, if any. (See the Error Codes appendix for a list of possible error codes.)

0 indicates that no error was encountered.

errtext

Text that explains the error code.

"No error" indicates that no error was encountered.

udata

Optional. Contains any udata value supplied in the request.

fid

The id of the field whose properties were successfully set.

fname

The label of the field whose properties were set.

top

Sample XML Request

POST https://target_domain/db/target_dbid HTTP/1.0
Content-Type: application/xml
Content-Length:
QUICKBASE-ACTION: API_SetFieldProperties

<qdbapi>
   <ticket>auth_ticket</ticket>
   <apptoken>app_token</apptoken>
   <udata>mydata</udata>
   <fid>6</fid>
   <label>Business Phone Number</label>
   <nowrap>0</nowrap>
   <bold>0</bold>
   <required>1</required>
   <display_as_button>0</display_as_button>
   <appears_by_default>1</appears_by_default>
   <find_enabled>1</find_enabled>
   <allow_new_choices>0</allow_new_choices>
   <sort_as_given>0</sort_as_given>
   <carrychoices>0</carrychoices>
   <foreignkey>0</foreignkey>
   <unique>1</unique>
   <doesdatacopy>0</doesdatacopy>
   <fieldhelp>Contact phone number</fieldhelp>
   <num_lines>1</num_lines>
   <append_only>0</append_only>
   <allowHTML>1</allowHTML>
   <has_extension>1</has_extension>
</qdbapi>

top

URL alternative

https://target_domain/db/target_dbid?a=API_SetFieldProperties&fid=7
&default_value=GoodBye&ticket=auth_ticket&apptoken=app_token

where target_domain is the domain against which you are invoking this call, for example, intuit.quickbase.com. Read about this notation.

top

Sample response

<?xml version="1.0" ?>
<qdbapi>
<action>API_SetFieldProperties</action>
   <errcode>0</errcode>
   <errtext>No error</errtext>
   <udata>mydata</udata>
   <fid>6</fid>
   <fname>Business Phone Number</fname>
</qdbapi>

top   

© 1999-2014 Intuit Inc. All rights reserved. Legal Notices.