API Template Functions

Every step in a Clear API has pre- and post-processing rules that take advantage of the Django template processing engine to perform data transformations. These transformations prepare parameters for backend systems (in the case of pre-processing) and transform the outputs (in the case of post-processing) from these system calls into something more useful for the API consumer. Within these pre- and post-processing rules, all of the built in Django template tags and filters are available as well as some custom tags we have created for our specific workloads.

Tags

add_payload_error

There may be errors that occur at different stages during the run of a Clear API. When the API author wishes to notify the user of an error in the system, they can use the add_payload_error to notify the user. These manifest in the ClearWork UI as red error message pop-ups. These errors will also be present in the payload that is returned in the API.

Parameters

  • messagestring – The message to display

Example

{% add_payload_error "User is not authorized to approve this purchase order." %}

add_payload_message

Informational, warning, and error messages can be set with add_payload_message. These messages will display in ClearWork UI as pop-ups. The color and behavior of these messages is controlled by several parameters:

Parameters

  • dictionaryobject – Will always be response.
  • messagestring – The message to display
  • stylestring(Defaults to success) Specific styling, options:
    • success – ClearUI Green
    • warning – ClearUI orange
    • info – Bootstrap blue
  • auto_closestring/int(Defaults to 5000ms) Determines how long before the message automatically closes.
  • colorstring – Can override the style color to the named color of your choice (see list below).
  • hiddenboolean – (Defaults to false) Don’t display the message to the user. This is typically used for debugging. The message can still be found in Redux tools.

Examples

Default Success Message

{% add_payload_message response message="Success! A message has been made!" %}

Info Message

{% add_payload_message response message="Here is some info." style="info" %}

Warning Message

{% add_payload_message response message="WARNING: Easily excitable dogs ahead." style="warning" %}

Message Closes After 10 Seconds

{% add_payload_message response message="This will close after 10 seconds" auto_close="10000" %}

Hidden Message

{% add_payload_message response message="You won't see this message" hidden=True %}

Purple Message

{% add_payload_message response message="This message will be purple" color="purple" %}

Color Options

aqua (comes with black text)
black
blue
darkcyan
darkgray
darkgrey
darkslateblue
darkslategray
darkslategrey
firebrick
fuchsia
goldrenrod
gray
green
grey
indigo
lightgray
lightgrey
lime (comes with black text)
maroon
navy
olive
orange
plum
purple
red
rosybrown
royalblue
saddlebrown
salmon
sandybrown
seagreen
sienna
silver
teal
yellow (comes with black text)

as_date

Formats a date string in formatted in ISO_8601 according to a format string. Format strings use strptime/strftime formatting

Parameters

  • iso_stringstring – A date string formatted in ISO 8601
  • formatstring – A format string specifying the desired output

Example

{% as_date value "%m/%d/%Y" %}  # "2019-08-27T18:17:52+00:00" => "08/27/2019"

csv_to_list

Converts a CSV to a list of dictionaries. The dictionaries keys are read from the header of the CSV.

Example

{% csv_to_list mycsv %}

Input

Year,Make,Model,Mileage
2007,Toyota,Corolloa,128635
2015,Honda,Odyssey,42331
2018,Tesla,S,12011

Output

[{'Make': 'Toyota', 'Mileage': '128635', 'Model': 'Corolloa', 'Year': '2007'},
 {'Make': 'Honda', 'Mileage': '42331', 'Model': 'Odyssey', 'Year': '2015'},
 {'Make': 'Tesla', 'Mileage': '12011', 'Model': 'S', 'Year': '2018'}]

dayssince

Returns the number of days since a given date to the present. Or, if the argument “ is supplied, calculate the days between two dates.

Parameters

  • datedate – The date to use for calculations (as a date type. see: string_to_date)
  • since_datedate – The date to use for calculations

Example

{% string_to_date '2019-10-03' as created_date %}
{% dayssince created_date %}

dictionary_add_dictionary

Adds an empty dictionary in an existing dictionary at key. Note that this will overwrite any existing value at that key.

Parameters

  • dictionarydictionary – The dictionary to manipulate
  • keystring – The key at which to add an empty dictionary

Example

{% dictionary_add_dictionary mydict "new" %}  # {'a': 1} => {'a': 1, 'new': {}}

dictionary_add_key_value

Adds a new value to the dictionary at the given key with the given value. Note that this will overwrite any existing value at this key. This tag does not return the set value.

Parameters

  • dictionarydictionary – The dictionary to manipulate
  • keystring – The key to set
  • valueany – The value to set in the dictionary at the given key

Example

{% dictionary_add_key_value user_parameters "newvalue" 42 %}

dictionary_add_list

Adds an empty list in an existing dictionary at key. Note that this will overwrite any existing value at that key.

Parameters

  • dictionarydictionary – The dictionary to manipulate
  • keystring – The key at which to add an empty list

Example

{% dictionary_add_list mydict "new" %}  # {'a': 1} => {'a': 1, 'new': []}

dictionary_capitalize

Uppercase all strings in a dictionary.

Parameters

  • dictionarydictionary – The dictionary to uppercase

Example

{% dictionary_capitalize value %}  # {'name': 'Dustin', 'age': 32} => {'name': 'DUSTIN', 'age': 32}

dictionary_value_replace

Iterate over the values of a dictionary and perform string replacements on any strings.

Parameters

  • dictionarydictionary – The dictionary to do string replacements in
  • oldvaluestring – The substring to replace
  • newvaluestring – The substring to replace oldvalue with

Example

{% dictionary_value_replace value "Dustin" "Jon" %}  # {'name': 'Dustin', 'age': 32} => {'name': 'Jon', 'age': 32}

evalJson

Creates a Python-native data structure from the given JSON string. (equivalent to json.loads())

Parameters

  • json_stringstring – The JSON string to load

Example

{% evalJson myjson %}  # "{\"a\": 1}" => {'a': 1} 

get_dictionary_value

Get a value from a dictionary based on a key. This is generally used with the Django as keyword to put this value into another variable for further manipulation.

Parameters

  • dictionarydictionary – The source dictionary
  • keystring – The key to retrieve from the source dictionary

Example

{% get_dictionary_value my_dictionary "b" %}  # {'a': 1, 'b': 2} => 2

list_add_value

Appends a value to a list.

Parameters

  • listlist – The list to append
  • valueany – The value to append to the list

Example

{% list_add_value mylist 42 %}  # [1,2,3] => [1,2,3,42]

list_remove_value

Removes the first value in a list that is equal to the given value. This will raise an error if the value does not exist in the list.

Parameters

  • valueany – The value to remove

Example

{% list_remove_value mylist 5 %}  # [4,5,6,5] => [4,6,5]

merge_dicts

Frequently, several calls are made into backend systems. It can be convenient to combine the results of those calls into a single dictionary for processing.

first: The first dictionary to merge.

second: The second dictionary to merge. Note that this dictionary takes precedence over the first when keys exist in both.

Parameters

  • firstdictionary – The first dictionary to merge.
  • seconddictionary – The second dictionary to merge. Note that this dictionary takes precedence over the first when keys exist in both.

Example

{% merge_dicts dict1 dict2 %}  # {'a': 1, 'b': 2}, {'b': 3, 'c': 4} => {'a': 1, 'b': 3, 'c': 4}

remove_empty_values

Removes any empty values from a dictionary. Optionally, sets the values in the returned dictionary to uppercase.

Parameters

  • dictionarydictionary – The dictionary to operate on
  • uppercaseboolean(Defaults to False) Uppercase values in the dictionary.

Example

{% remove_empty_values value %} #  {'a': '', 'b': 1, 'c': []} => {'b': 1}

replace

Perform a string replacement, by replacing oldvalue with newvalue in text.

Parameters

  • textstring – The string to operate on
  • oldvaluestring – The substring to replace
  • newvaluestring – The substring to replace oldvalue with

Example

{% replace mystring "v" "ph" %}  # "Steven" => "Stephen"

return_as_list

Preserve a list as a list, or make a single dictionary into a one-item list. This is used when subsequent code will expect a list. e.g. for loops

Parameters

  • datadictionary or list – The data to return as a list

Example

{% return_as_list mydict as definitely_a_list %}  # {'a': 1} => [{'a': 1}]

set_payload_status

Set an HTTP status for a payload. Some backend systems provide inconsistent status codes, e.g. returning both 200 and 404 for Not Found. This tag allows these codes to be normalized.

Parameters

  • payloadpayload – This should be set to the payload variable that is always present in templates
  • statusinteger – The numeric HTTP status code to return

Example

{% set_payload_status payload 400 %}

sleep_use_at_your_own_peril

Occasionally, we have to wait on a backend system to perform some work before moving on with a task. Sleep functions should be used as a last resort, since they consume server resources without accomplishing any work. However, there are instances where there is no reasonable alternative.

Parameters

  • durationinteger – Sleep duration in seconds

Example

{% sleep_use_at_your_own_peril 5 %}

split_string_into_chunks

Chunks a string into a list of chunk_size length strings. This is useful for some backend systems that use line-based storage for large strings. The last string may be smaller than chunk_size; no padding is added.

string: The string to chunk

chunk_size: The chunk size for output strings #### Parameters – stringstring – The string to chunk – chunk_sizeinteger – The chunk size for output strings

Example

{% split_string_into_chunks value 10 %}  # 'This is my long string' => ['This is my',' long stri','ng']

string_to_date

Converts a string to a date type based on a format string. Format strings use strptime/strftime formatting

format: strptime/strftime format string #### Parameters – formatstring – strptime/strftime format string

Example

{% string_to_date value "%Y-%b-%d" %}  # Correctly converts "1999-Dec-25" to a date type

string_to_dictionary

Attempts to parse a Python dictionary represented as a string into an actual dictionary type.

Parameters

  • stringstring – The dictionary represented as a string

Example

{% string_to_dictionary str %}  # "{'a': 1}" => {'a': 1}

timedelta

Add or subtract time from a date. (Subtraction is done using negative values.) The date should be provided as a string with a strptime format string. It will be returned in the same format.

Parameters

  • datestring – The date represented as a string
  • formatstring – The strptime format of the date string
  • weeksinteger(Defaults to 0) The number of weeks to add
  • daysinteger(Defaults to 0) The number of days to add
  • hoursinteger(Defaults to 0) The number of hours to add
  • minutesinteger(Defaults to 0) The number of minutes to add
  • millisecondsinteger(Defaults to 0) The number of milliseconds to add

Example

{% timedelta value days=10 %}

toJson

Creates a JSON string from the given data. (equivalent to json.dumps())

Parameters

  • dataany – The data to return as a JSON string

Example

{% toJson mydata %}  # {'a': 1} => "{\"a\": 1}"

Filters

add_float

Adds a floating point number to the value. Note that both the argument and value are cast to floating point numbers before performing the addition. This is the primary difference between this filter and the built-in add in Django. add will concatenate two strings representing floating points, rather than add them together. For example, consider the following code:

{{ price|add:salestax }}

If price and salestax are the strings “1.00” and “0.07” respectively, with the built-in add, the result is “1.000.07”. The result of add_float is 1.07

Parameters

  • valuefloat – The value to add

Example

{{ price|add_float:salestax }}

add_newline

In some scenarios, it can be tricky to add an actual newline to a string. Some systems depend upon having newline characters between rows in a table, for instance. This filter appends a newline character (\n) to the given value.

Parameters

  • prefixboolean – If the prefix argument is supplied, the newline will be added to the beginning of the value instead of the end.

Example

{% for line in items %}
    {{ line|add_newline }}
{% endfor %}

ascii

Converts a string to ASCII representation by using unicode.normalize(‘NFKD’) before encoding as ASCII, ignoring characters that don’t exist in ASCII.

Official documentaiton on unicode.normalize

Example

{{ value|ascii }}  # 'abc®' => 'abc'

concatenate

Functions similarly to Django’s add when used with strings, but first uses smart_text which will correctly convert any source encoding to unicode.

Parameters

  • valueany – The value to concanate to the base string. Values will first be converted to strings.

Example

{{ value|concatenate:ascii_value }}

decode

Decodes base64 data to the original format.

Example

{{ value|decode }}

divide

Divide two values. Both values will be cast to floating point numbers before dividing. Note that there is a potential for divide-by-zero errors when using this filter.

Parameters

  • divisornumber – The number to divide by

Example

{{ value|divide:42 }}

encode

Encodes data as base64. Some backend systems consume data in base64.

Example

{{ value|encode }}

index

Return the value at a given index in a list (or any subscriptable type, e.g.  strings)

Example

{{ my_list|1 }}  # ['abc', 'def', 'ghi'] => 'def'

keyvalue

Return the value for a given key in a dictionary. Raises an error for non-existent keys

Parameters

  • keystring – The key to retrieve

Example

{{ keyvalue|"name" }}  # {"name": "Jon", "title": "CEO"} => "Jon"

multiply

Multiply two values. Both values will be cast to floating point numbers before multiplying. Note that all math functions accept floats as well as strings that can be parsed into floats.

Parameters

  • factorfloat – The factor to multiply by

Example

{{ value|multiply:42 }}

split

Splits a string into a list of strings, split by the specified separator.

Parameters

  • separatorstring – String or character to use to split string. e.g. “,”, “/”, etc

Example

{{ value|split:',' }}  # "Bryan,Robinson,Derick" => ["Bryan", "Robinson", "Derick"] 

string_add_float

Adds argument to value, after casting to floating-point. The resulting number is then formatted to the second decimal place. This function also handles negative signs presented as suffixes (i.e. “42-” will become “-42” before the add operation takes place)

Parameters

  • valuenumber – The number to add

Example

{{ value|string_add_float:"42-" }} # 47 => 5

strip

Removes leading and trailing whitespace from a string, and returns a unicode value which has been passed through smart_text

Example

{{ value| strip }}  # '  abc def ' => 'abc def'

subtract

Subtract two values. Both values will be cast to floating point numbers before subtracting. Note that all math functions accept floats as well as strings that can be parsed into floats.

Parameters

  • valuenumber – The number to subtract

Example

{{ value|subtract:42 }}

times

Intended for use with for loops, this filter returns a range that can be used to iterate the given number of times.

Example

{% for i in 5|times %}{{ i }}{% endfor %}  # Output: 01234