Silverfin Development Toolkit

This extension aims to support the creation of Liquid templates with the Silverfin Templating Language and the development of Liquid testing YAML files.

Setup & Basic Usage

Authorisation

Before installing the Silverfin Extension, you should first authenticate your device. Your device must be authenticated with the Silverfin API so the Silverfin extension can interact with the Silverfin Platform. For this you will need to contact Silverfin to receive a Client ID and Client Secret, and then add these credentials as environment variables on your local machine.

If you already have the Silverfin CLI installed, your device should already possess the relevant credentials, in which case no further action is required. Otherwise, please refer to the installation instructions for the Silverfin CLI. While installing the Silverfin CLI itself is optional, the instructions also include detailed step-by-step instructions on how to authenticate your device. Please follow these instuctions to complete authentication.

Install Silverfin Extension

Once your device has been authenticated, the next stage is to download the extension itself. The Silverfin Development Toolkit extension can be found in the VS Code Marketplace (you will need to have the version 1.0.0 or higher)

Liquid testing

Prevalidation of YAML files

Tests for liquid templates are written in YAML, and to support the process of writting those tests, this extension includes a JSON Schema which is going to be validated against your YAML files. This will help you out to detect possible errors while defining those tests (e.g: missing required arguments or duplicated keys) without having to wait to run those tests. This SCHEMA is going to be applied to files which name ends with _liquid_test.yml.

Running a test

You can run your Liquid Tests directly from VS Code using the button at the bottom of the application.

First, navigate to the relevant test .yml file, then press the "Silverfin: run liquid test" button.

---

NOTE: You will need to set the firm ID before you can run any tests. Please refer to "Using the Command Palette" section below_

---

On pressing the button, a dropdown will appear of all available tests, including the option to run all tests.

Choose the test you wish to run. The test(s) will either pass, or any issues will be detailed in the problems panel at the bottom of VS Code. As well as highlighting problems, the extension will also suggest potential fixes to issues if the fault lies within the YAML code. You can view and apply these suggestions by hovering over the yellow lightbulb () that will appear when placing your cursor on the line with the error .

Running a specific test will visualize the test results alongside the YAML file itself, rendering how the template will appear with the inputted dummy data.

Using the Command Palette

You can access additional commands using the VS Code Command Palette.

As before, first navigate to the relevant test .yml file.

Then access the Command Palette either by using the shortcut Shift + Control + p (Shift + Command + p for Mac) or via the Application Menu by clicking View > Command Palette.

From there if you type in 'Silverfin' you will be given a choice of commands. The most relevant commands are likely to be:

Command	Description
Silverfin: run specific liquid test (with HTML output from Input view)	Same as pressing the test button
Silverfin: run all liquid tests	Shortcut to run all liquid tests
Silverfin: erase stored details of previous test runs (current)	Clears problems panel
Silverfin: set active firm ID*	Set up which firm will be used as a test environment (your tests will be run as if you're working in this firm)

---

NOTE: You will need to set the Firm ID *before* you can run any tests.

---

Features

Silverfin Siderbar

After installing the extension you will have access to the new Silverfin Sidebar:

The sidebar will display the following information concerning the currently selected liquid template:

• Parts: A list of the associated parts and shared parts, including links to the listed (shared) parts enabling easy navigation.
• Template Information: Meta information such as it appears on the Platform e.g. handle, name, reconciliation type, etc.
• Firms: A list of firms which utilise the selected template and a list of firms for which you have authorised the API to work with.

This extension will also check if you are trying to include a shared part in your liquid that does not exist (in general / in your current set default firm) or if you are using a shared part that hasn't been added to the template yet. In the last case, it will give you a warning and will suggest to add it with the click of a button.

Syntax Highlighting

This extension provides you with a default set of rules for Silverfin Liquid syntax highlighting and you can further customize the colors to your heart's desire.

Auto Linting

Tests for liquid templates are written in YAML, and to support the process of writing those tests, this extension includes a JSON Schema which is going to be validated against your YAML files. This will help you out to detect possible errors while defining those tests (e.g: missing required arguments or duplicated keys) without having to wait to run those tests.

This SCHEMA is going to be applied to files that end with _liquid_test.yml.

You can run your Liquid Tests directly from VS Code with the click of a button and visualize the test results on top of the YAML file itself (You must have a registered API with Silverfin to have access to these features). If you are running individual tests, you can also see the results of the test in the output panel (an HTML version of your template).

In addition, this extension will enable code snippets for .liquid & liquid testing .yml files. Please refer to Snippets section below for a full list of snippets.

Snippets

This extension adds snippets to make your writing of liquid templates for Silverfin blazingly fast!

Any formatting choices that are made within the Snippets are made according to the Liquid guidelines.

Snippets are available for the following categories:

• Tags
• Filters
• Drops
• Tables

Drops

When selecting a drop snippet, you will have two options to choose from:

• [some_drop]
• [some_drop].

The first option will close the drop

The second option, with the period, will continue the drop. On selecting this snippet, you will be given a list of available sub-drops for that drop. First navigate to the relevant sub-drop. If you wish to close off the drop, select the sub-drop you require using the mouse or by pressing enter. However, if you wish to continue the drop, instead start to type in the name of the required sub-drop, and then select the relevant snippet as before.

Some drops contain identical sub-drops e.g. first exists for both the accounts and the people drop. In such cases, you will be provided multiple snippets to choose from, so please pick the one with the relevant description.

Ctrl + Space

If you position your cursor at the end of a drop e.g. [period.accounts] and press Ctrl + Space, you will also be provided a list of the available snippets, which you can select to access the list of sub-drops

Silverfin Snippets Reference

Style Snippets

Shortcut	Description
Styling
stripnewlines	Add opening and closing stripnewlines
endstripnewlines	Only add closing endstripnewlines tag
newline	Add a newline tag
indent	Add an indent tag with the possible indentation levels listed
fontsize	Add a font tag with the possible options for font-size listed
fontcolor	Add a font tag with the hex-colour attribute included
infotextinline	Add inline infotext inside ic tags
infotextblock	Add full-width infotext inside ic tags
infotexthover	Add infotext with the as="hover" attribute
warningtextinline	Add inline warningtext inside ic tags
warningtextblock	Add full-width warningtext inside ic tags
warningtexthover	Add warningtext tag with the as="hover" attribute
HTML styling
<p>	Add opening and closing <p> tags for paragraph text formatting in HTML
br	Add an HTML line-break tag
hr	Add horizontal rule tag in HTML
b	Add opening and closing <b> tags for bold text formatting in HTML
i	Add opening and closing <i> tags for italic text formatting in HTML
u	Add opening and closing <u> tags for underlined text formatting in HTML
em	Add opening and closing <em> tags for emphasized (italic) text formatting in HTML
strong	Add opening and closing <strong> tags for strong (bold) text formatting in HTML
sub	Add opening and closing <sub> tags for subscript text formatting in HTML
sup	Add opening and closing <sup> tags for superscript text formatting in HTML
h1, h2, h3, h4, h5, h6	Add opening and closing tags for section heading text formatting in HTML. <h1> is the largest heading and <h6> is the smallest. Cannot be used inside HTML tables within a Liquid template
a, anchor	Add opening and closing <a> tags for hyperlink text formatting in HTML

Tag Snippets

Shortcut	Description
Comments
comment	Add opening and closing comment tags
endcomment	Only add the closing comment tag
ic	Add opening and closing ic tags (input only)
endic	Only add the closing ic tag (input only)
nic	Add opening and closing nic tags (export only)
endnic	Only add the closing nic tag (export only)
Variables
assign	Add an assign tag for variables
assign [dynamic]	Add an assign tag for dynamic variables
capture	Add opening and closing capture tags
endcapture	Only add the closing capture tag
Translations
t=	Set a translation with a default (different languages to be set depending on market)
t	Call a defined translation
Input
input	Add a standard text-input
as:text	Add the attribute for a textarea input
as:currency	Add the attribute for a currency input
as:currency,invert:true	Add the attribute for a currency input with inverted value stored in database
precision:	Add the sub-attribute to define the precision on a currency input
as:integer	Add the attribute for an integer input
as:percentage	Add the attribute for a percentage input
precision:	Add the sub-attribute to define the precision on a percentage input
strip_insignificant_zeros	Add the sub-attribute to strip the final decimal zeros from a percentage value on an input
as:boolean	Add the attribute for a boolean input
autoreload:	Add the sub-attribute to a boolean input to auto-reload
as:date	Add the attribute for a date input
format:	Add the sub-attribute to define the date format display inside an input
as:file	Add the attribute for a file input
show_label:	Add the sub-attribute to add a label to file input field
max_size:	Add the sub-attribute to limit size (in MB) of files users can attach
document	Add the attribute to show name of the (first) attached documents of a relevant custom value
documents	Add the attribute to show names of all attached documents of a relevant custom value
[some documents].size	Count number of files attached of a relevant custom value
[some document].file_name	Render name of relevant document
[some document].link	Render link to preview of relevant document
as:select	Add the attribute for a select input
options:	Add the options sub-attribute to a select input
option_values:	Add the option_values sub-attribute to a select input
as:account_collection	Add the attribute for an account collection input
range:	Add the range sub-attribute to an account collection input
placeholder:	Add the placeholder attribute to an input
required:	Add the required attribute to an input
default:	Add the default attribute or filter to an input or variable
import_title:	Add import_title attribute to _both_ fori loops and inputs within fori loop when importing reconciliation data to distinguish between different collections
assign:	Add the assign attribute to assign input value to a variable
Radio Group
radiogroup	Add a radio button input group
radioinput	Add individual buttons within a radio button group
autoreload:	Add the attribute to a radiogroup tag to auto-reload
Control Flow
if	Add opening and closing if tags
if else	Add opening and closing if tags with else statement
endif	Only add closing if tag
else	Only add else tag
elsif	Only add elsif tag
ifi	Add opening and closing ifi tags
endifi	Only add closing ifi tag
unless	Add opening and closing unless tags
endunless	Only add closing unless tag
case	Add opening and closing case tags with a when and else statement
endcase	Only add closing case tag
when	Add a when tag that is used within case tags
Iterations
for	Add opening and closing for loop tags
endfor	Only add a closing for loop tag
limit	Add the limit attribute to a for loop
offset	Add the offset attribute to a for loop
reversed	Add the reversed attribute to a for loop
fori	Add opening and closing fori loop tags
endfori	Only add a closing fori loop tag
import_title	Add import_title attribute to _both_ fori loops and inputs within fori loop when importing reconciliation data to distinguish between different collections
forloop.index	Add the forloop.index variable inside a for loop
forloop.index0	Add the forloop.index0 variable inside a for loop
forloop.first	Add the forloop.first variable inside a for loop
forloop.last	Add the forloop.last variable inside a for loop
break	Add the break tag inside a for loop
continue	Add the continue inside a for loop
Unreconciled
unreconciled	Add the unreconciled tag as an indicator with unreconciled text
unreconciled-withoutindicator	Add the unreconciled tag as an indicator with unreconciled text
Result
result	Add a result tag
Rollforward
rollforward	Add a rollforward tag
as:file	Add as:file attribute to a rollforward tag
rollforward.period	Add the rollforward.period variable
Locale
locale	Add opening and closing locale tags
endlocale	Only add closing locale tag
Include
include	Add a tag to include a local or shared part
Linkto
linkto	Add opening and closing linkto tags
endlinkto	Only add closing linkto tag
target:	Add a target attribute to a linkto tag
new_tab:	Add a new_tab attribute to a linkto tag
as:button	Add the attribute for a button to a linkto tag
target	Add a target tag with an id
Adjustment Button
adjustmentbutton	Add opening and closing adjustmentbutton tags
adjustmentbuttonwithpurpose	Add an adjustmentbutton tag with a purpose attribute
endadjustmentbutton	Only add closing adjustmentbutton tag
adjustmenttransaction	Add adjustmenttransaction tag
Group
group	Add a closing and opening group tag inside nic tags
Add New Inputs
addnewinputs	Add opening and closing addnewinputs tags
endaddnewinputs	Only add closing addnewinputs tag
Signmarker
signmarker	Add a signmarker tag
Push & Pop
push	Add a push tag
pop	Add a pop tag
Change Orientation
changeorientation	Add a changeorientation tag
Currency Configuration
currencyconfiguration	Add opening and closing currencyconfiguration tags with the possible attributes
endcurrencyconfiguration	Only add closing currencyconfiguration tag
zero_format	Add attribute to set format of zeroes to "0" or "-"
negative_format	Add attribute to set format of negative numbers to "-xxx" or "(xxx)"
precision	Add attribute to set number of decimal places
delimiter	Add attribute to set style of delimiters to "x,xxx", "x.xxx", "xxxx", or "x xxx"
separator	Add attribute to set style of decimal separator to either "x,xx" or "x.xx"
New Page
newpage	Add a newpage tag to signify the start of a new page in the PDF export with optional orientation attribute
section_break	Add the attribute to create section breaks within input mode

Drops Snippets

Shortcut	Description
Accounts Drops
accounts.starred accounts.assets accounts.liabilities accounts.revenues accounts.expenses accounts.income accounts.equity	Return an accounts drop with only specified accounts type
accounts.count	Return number of account drops in the accounts drop
accounts.credit_value	Return sum of credit value of all accounts in the accounts drop
accounts.debit_value	Return sum of debit value of all accounts in rhe accounts drop
accounts.first	Return the first account drop of the accounts drop
accounts.include_zeros	Return an accounts drop that includes all accounts, including those with a zero balance
accounts.name	Return the name of the first account in this drop
accounts.p_and_l_rounding_difference, accounts.bs_rounding_difference	Display the exact Profit & Loss/ Balance Sheet rounding difference when using the core rounding functionality
accounts.p_and_l_rounding_account, accounts.bs_rounding_account	Return the account drop where the Profit & Loss/ Balance Sheet rounding difference is stored
accounts.return_values_in_millions	Display the value of the individual account drops in the created accounts drop in millions
accounts.return_values_in_thousands	Display the value of the individual account drops in the created accounts drop in thousands
accounts.value	Return the sum of all values for all accounts in this accounts drop for this period
Company Drops
company.analytical_type_(0..x)_codes	Returns drop with information about dimensions/companies in an analytical/consolidation file
company.city	Return the city from the company settings
company.company_form	Return the company form from the company settings
company.company_type	Return the company type from company settings
company.country	Return the country from the company settings
company.country_code	Return the country code based upon the country from the company settings
company.currency	Return the currency code from the company settings
company.custom	Attach custom information to a company, independant of the period
company.file_code	Return the file number from the company settings
company.locales	Return the available languages for the company
company.name	Return the company name from the company settings
company.periods_per_year	Returns 1,4,12 depending on the reporting frequency (yearly, quarterly or monthly)
company.postalcode	Return the post code from the company settings
company.street	Return the street from the company settings
company.vat_identifier	Return the vat identifier from the company settings
people.count	Return of count of number of person drops within the people drop (can also use with directors and shareholders drops)
people.first	Return first the person drop in the people drop (can also use with directors and shareholders drops)
directors.active_as_director	Add the filter for directors which returns those directors active during the book year
directors.active_as_director_on	Add the filter for directors which returns those directors active in a specific date
Period Drops
period.accounts	Return an accounts drop of all accounts with bookings on this period
period.account_mapping_list.name	Return the name of the mapping list used for this period
period.account_mapping_list.id	Return the id of the mapping list on firm level
period.account_mapping_list.marketplace_template_id	Return the id of the mapping list on the marketplace
period.adjustments	Return adjustments drop of all adjustments for the period
period.bookyear_index	Return the index number of the current book year as an integer. The first book year equals 1
period.calendar_years	Add the method to add an array of all calendar years in the fiscal year. The information for each calendar year is: start_date, end_date, amount_of_days for the number of days the bookyear has in the calendar year, and amount_of_days_in_full_year for the total number of days in the calendar year
period.custom	Attach custom information to a period. This is done automatically in reconciliations
period.directors	Return a people drop of all individuals who are directors
period.end_date	Return the date this period ends
period.exists	Return true when the period exists in the Silverfin database
period.fiscal_year	Return the fiscal year of this period
period.is_first_year	Return true if the period is in the first book year of this client file
period.month_end_dates	Return an array of all the end dates of the calendar months in this fiscal year
period.name	Return the name of the period
period.people	Return the people drop of all people attached to the period (typically copied from general company level)
period.reconciliations	Return a reconciliations drop of all reconciliations for this period. You can ask for a specific reconciliation by adding the handle. I.e. period.reconciliations.the_handle.
period.reports	Return a reports drop of all reports for this period. You can ask for a specific report by adding the handle. I.e. period.reports.the_handle
period.shareholders	Return a people drop of all individuals who are shareholders
period.start_date	Return the date this period starts
period.year_end	Return the period at the end of the fiscal year this period is in
period.year_end_date	Return the date of the end of the fiscal year of this period
period.year_start_date	Return the date of the start of the fiscal year of this period
period.minus__xp/y	Return the period drop of the current period minus the amount of periods or years defined
period.plus__xp/y	Return the period drop of the current period plus the amount of periods or years defined
Reconciliations Drops
reconciliations.count	Returns the number of active reconciliations
reconciliations.[reconciliation_handle] *	Return the specific reconcilaition with matching handle * Don't actually use the word handle but use that handle of the specific reconciliation instead
reconciliations.star	Return reconciliations drop of all starred reconciliations
User Drops
user.name	Return name of the current Silverfin user
user.email	Return email address of the current Silverfin user

Filter Snippets

Shortcut	Description
Allow False
allow_false	Add the filter to allow falsy values not to be overwritten by defaults
Array
concat	Add filter to combine two arrays
split	Add filter to split a String into an array
first	Add filter to return the first value of an array
last	Add filter to return the last value of an array
join	Add filter to transform an array into a String
sort	Add filter to sort an array alphabetically
uniq	Add filter to remove duplicate values from an array
reverse	Add filter to reverse order of items in an array
Collection
concat	Add filter to combine two collections
map	Add filter to create array from collection
range	Add filter to accounts collection to return accounts in a given range
group_by	Add filter to group items of collection by a specified field
index_by	Add filter to reference item by an alternate index
where	Add filter to create array from collection, only including items which meet specified condition
analytical_code	Add filter to accounts collection to return accounts for specified dimension/company code
add_rounding_difference	Add filter to accounts collection to remove (and reallocate) decimal values
Date and Time
date:"%d/%m/%Y"	Add filter for standard BE date formatting (DD/MM/YYYY)
date:"%F"	Add filter for ISO date formatting (YYYY-MM-DD)
"now"	Display today's date
localized_date	Display a date according to the time-zone from where template is being executed
advance_years	Add filter to advance date by specified number of years
advance_months	Add filter to advance date by specified number of months
advance_weeks	Add filter to advance date by specified number of weeks
advance_days	Add filter to advance date by specified number of days
advance_hours	Add filter to advance date by specified number of hours
advance_minutes	Add filter to advance date by specified number of minutes
advance_seconds	Add filter to advance date by specified number of seconds
retract_years	Add filter to retract date by specified number of years
retract_months	Add filter to retract date by specified number of months
retract_weeks	Add filter to retract date by specified number of weeks
retract_days	Add filter to retract date by specified number of days
retract_hours	Add filter to retract date by specified number of hours
retract_minutes	Add filter to retract date by specified number of minutes
retract_seconds	Add filter to retract date by specified number of seconds
Localized
localized	Add filter on custom input drop with localized attribute, to retrieve value in local language
localized:	Add functionality to a text input only, to store text in local language
Number
abs	Add filter to return the absolute value of a number
ABS (function)	Add function to return absolute value from wrapped input
ceil	Add filter to return value rounded-up
floor	Add filter to return value rounded-down
currency	Add filter to return a value in the currency format
invert	Add filter to invert value of inputed accounts - only works with currency filter
integer	Add filter to convert value to the nearest whole number
INT (function)	Add function to convert wrapped input to nearest whole number
percentage	Add filter to return value as percentage
number_to_human	Add filter to convert inputted accounts into combination of integers + English words e.g. "287 Thousand"
number_to_currency	Add filter to convert a string value to the currency format
round	Add filter to return s rounded value (with default of two decimal places)
modulo	Add filter to divide value by a number and return the remainder
MAX (function)	Add the MAX function to return the largest value of an array of numbers
MIN (function)	Add the MIN function to return the smallest value in an array of numbers
at_least	Add filter to limit input to a minimum value
at_most	Add filter to limit input to a maximum value
String
remove	Add filter to removes substring from a given string
replace	Add filter to replace substring A with substring B within a given string
upcase	Add filter to transform all letters of a given string into uppercase
downcase	Add filter to transform all letters of a given string into lowercase
capitalize	Add filter to capitalise each word in a given string
append	Add filter to attach String B to the end of String A
prepend	Add filter to attach String B at the start of String B
size	Add filter to return the number of characters within a given String
strip	Add filter to string any whitespaces at the start and end of a given string
default	Add attribute to a string variable to return a default value if no value stored in the variable
slice	Add filter to return a substring of a given String, beginning from a certain index for a certain length
newline_to_br / multiline_table	Add filter to replace every newline character ("\n") with an HTML line break ("<br>")
string_value	Add filter to return a value from a variable or drop as a String rather than the inferred data type
url_encode	Add filter to replace any URL-unsafe character with three characters: a percent sign and the corresponding Hex value of the character replaced
url_decode	Add filter to decode a String encoded by the above url_encode filter
strip_html	Add filter to remove any HTML tags from a String
md5	Converts a string into an MD5 hash
transliterate	Transliterates strings based on the Unicoder library

Table Snippets

Shortcut	Description
HTML Elements
Table Elements
table	Add snippet for a minimal HTML table with a header, body, and width classes defined
thead	Add opening and closing <thead> tags for an HTML table
tbody	Add opening and closing <tbody> tags for an HTML table
tr	Add opening and closing <tr> tags for an HTML table with nested <td> elements
th	Add opening and closing <th> tags for an HTML table
td	Add opening and closing <td> tags for an HTML table
Text Formatting Elements
br	Add an HTML line-break tag
b	Add opening and closing <b> tags for bold text formatting in HTML
i	Add opening and closing <i> tags for italic text formatting in HTML
u	Add opening and closing <u> tags for underlined text formatting in HTML
em	Add opening and closing <em> tags for emphasized (italic) text formatting in HTML
sub	Add opening and closing <sub> tags for subscript text formatting in HTML
sup	Add opening and closing <sup> tags for superscript text formatting in HTML
HTML Attributes
class	Add class attribute to HTML elements
colspan	Add colspan attribute to HTML <td> or <th> element
CSS Classes
Alignment Classes
usr-width-	Add usr-width-* class to set element width
usr-align-left	Add usr-align-left class to align text left
usr-align-center	Add usr-align-center class to align text center
usr-align-right	Add usr-align-right class to align text right
usr-align-justify	Add usr-align-justify class to justify text
usr-valign-top	Add usr-valign-top class to vertically align content to top
usr-valign-center	Add usr-valign-center class to vertically align content to center
usr-valign-bottom	Add usr-valign-bottom class to vertically align content to bottom
Border Classes
usr-line-top	Add usr-line-top class to add a top border
usr-line-bottom	Add usr-line-bottom class to add a bottom border
usr-line-left	Add usr-line-left class to add a left border
usr-line-right	Add usr-line-right class to add a right border
usr-double-line-top	Add usr-double-line-top class to add a double top border
usr-double-line-bottom	Add usr-double-line-bottom class to add a double bottom border
usr-double-line-left	Add usr-double-line-left class to add a double left border
usr-double-line-right	Add usr-double-line-right class to add a double right border
Color and Styling Classes
usr-border-color-*	Add class to set table cell border color in Hex
usr-background-color-*	Add class to set table cell background color in Hex
usr-indent-*	Add usr-indent-* class to indent content
usr-repeated-header	Add usr-repeated-header class to repeat table header on new pages in PDF export
usr-no-left-padding	Add usr-no-left-padding class to remove default left padding
usr-grayed-out-background-input	Add class to set table cell background to gray
usr-grayed-out-line-bottom-input	Add class to set faint table cell bottom lines
usr-hide-samepage-header	Add usr-hide-samepage-header class to hide header when content continues on same page

Third party extensions

• YAML extension: To apply our Schema to YAML files, we need to have Red Hat's YAML extension activated (this extension should be added automatically since it is set as a dependency).
• Auto Close Tag: To enable VS Code to automatically close HTML tags in Liquid files, we need to have Jun Han's Auto Close Tag activated (this extension should be added automatically since it is set as a dependency).