Skip to content

A VS Code extension for Silverfin templating language and Liquid testing

License

Notifications You must be signed in to change notification settings

silverfin/silverfin-vscode

Repository files navigation

Silverfin Development Toolkit

Maintained License Issues

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)

image

image

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.

image

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 (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:

image

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.

image

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

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

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

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

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

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).

About

A VS Code extension for Silverfin templating language and Liquid testing

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published