Skip to main content

ALToolbox functions and components

The functions and classes listed on this page can be used without the Assembly Line framework. Follow the instructions to include each component in your interview, which may involve including a single YAML file or a module, CSS, and JavaScript file.

Live demos​

To get a hands-on experience on any of these functions, you can go to ALToolbox's overview page to run the demo interview you are interested in.

The overview page also provides instructions for those who want to contribute to ALToolbox.

Collapsible help text​

Use collapse_template() to display an accordion-style information box that starts out hidden but expands when the user clicks on it. The contents of the information box come from a Docassemble template block. The subject will display with an arrow, and the content of the template will be shown when the subject is clicked on.

We recommend using this for help text in your interviews.

It works a lot like this details element:

Like this

Context-specific help goes here.

To include this in your interview:

---
modules:
  - docassemble.ALToolbox.misc
---
features:
  css: docassemble.ALToolbox:collapse_template.css

Example usage:

---
id: example question
question: |
  What is your favorite fruit?
subquestion: |
  ${ collapse_template(fruit_explanation) }
---
template: fruit_explanation
subject: |
  Like this
content: |
  Context-specific help goes here.

Code for collapse_template

Display markdown template with a scroll bar​

display_template() displays a Docassemble template with a scroll bar to save screen space if the content is long.

It also displays the subject line along with the content, and allows you to add styles to the display. You can turn the scroll bar on and off.

Example: display_template(my_template, scrollable=True, class_name="my_color").

Include this in your interview:

---
include:
  - docassemble.ALToolbox.display_template.yml

Display a series of tabs​

tabbed_templates_html() displays a series of Docassemble templates with Bootstrap tabs.

Example: tabbed_templates_html('unique_name_of_tab_group', tab_template1, tab_template2).

Include this in your interview:

---
modules:
  - docassemble.ALToolbox.misc

This tel function just makes a string representing a telephone number clickable, which opens the dialer on mobile.

For example: tel('617-555-5555')

Include this in your interview:

---
modules:
  - docassemble.ALToolbox.misc

Shorten a URL​

The shorten_url function lets you use your Docassemble server as a URL shortener.

The function has one parameter: original_url and can be called like this: shorten_url('https://www.example.com').

Links expire in 7 days, and can be to either internal or external content. The URL will still display your server's domain name, and will look like this:

https://my.docassemble-server.com/goto?c=aRjzWcNZyJGWnMQghHamcndEnVKfhNwo

Include this in your interview:

---
modules:
  - docassemble.ALToolbox.misc

Format numbers with a thousands separator​

Use the thousands() function to format a currency value without adding a currency symbol but with , separating the thousands positions. The decimal portion is also rounded down. For example, for a PDF form that already includes a $ symbol.

Example: thousands(1870.22) will display as 1,870.

To use, include this in your interview:

---
modules:
  - docassemble.ALToolbox.misc

Display a fontawesome icon inline​

Docassemble allows you to display an icon from fontawesome, but it does not provide control over the size or color of the icon. Use fa_icon() to gain more control over the icon that is inserted.

Parameters:

  • icon: a string representing a fontawesome icon. The icon needs to be in the free library.
  • color can be any Bootstrap color variable. For example: primary, secondary, warning
  • color_css allows you to use a CSS hex code to represent the color, e.g., #fff for black.
  • size is used to control the fontawesome size (without the fa- prefix). Valid values include 2xs, the default of sm all the way to 2xl.

Total a list of values that may not be defined​

sum_if_defined() returns the total of a list of values that may or may not be defined. Each variable's name should be passed as a string as a separate parameter.

Use it like this:

sum_if_defined('value1', 'value2', 'value3'). Using sum_if_defined() will not error if any of the values are undefined. If no value is defined, sum_if_defined() will return 0.

It is usually a better pattern to put the values into a list and use the built-in Python function sum, but this provides an alternative that may require less effort depending on how your form is labeled.

Provide a button that allows a user to copy text to the clipboard​

Use copy_button_html() to display an HTML input with a button that allows the user to copy the text to their device's clipboard.

Parameters:

  • text_to_copy: text you want the user to be able to copy.
  • text_before: the prompt that will appear to the left of the HTML input
  • label: defaults to "Copy"
  • tooltip_inert_text: defaults to "Copy to clipboard" when hovered over
  • tooltip_copied_text: defaults to "Copied!" when the text is placed on the clipboard
include:
  - docassemble.ALToolbox:copy_button.yml

Escape button​

The escape_button.yml file adds a red "Escape" button in the top navigation area that takes you to https://google.com when you click on it.

You may choose to use this if you have vulnerable clients, such as those living with a domestic abuser.

To include in your interview:

---
include:
  - docassemble.ALToolbox:escape_button.yml

International phone number input validation​

Use a custom datatype phone field to define the phone number input, and it will validate the country code for you. Run the demo interview to see how it works and detailed implementation instruction.

To include in your interview:

---
include:
  - docassemble.ALToolbox:phone-number-validation.yml

BirthDate and ThreePartsDate custom datatypes​

Use the custom datatype BirthDate or ThreePartsDate to ask the user to enter a date that might be very far in the past or in the future, where the standard calendar picker can slow the user down. This input will display a separate month, day, and year input. The Month input will be a dropdown menu with a list of months.

Example:

Preview of BirthDate selector with 3 separate inputs for month, day and year

BirthDate and ThreePartsDate are exactly the same, except that a BirthDate is limited to a date in the past.

Both BirthDate and ThreePartsDate will be available for you to use in your interview if the docassemble-ALToolbox repository is installed on your server. You do not need to explicitly include any code in your interview YAML file to use them.

Shorthand function to display a checkbox in replace of a True/False boolean value in a DOCX template​

Use the output_checkbox() function to display a checked or unchecked value in a DOCX template. It can reduce the risk of typos and make your templates slightly easier to read.

By default, the "checkbox" will be the literal value [ ] or [X] rather than a Word form control.

Example:

---
question: |
  Do you live in Florida?
yesno: user_lives_in_florida

Then in the DOCX template, you could write {{ output_checkbox(user_lives_in_florida) }} instead of the messier {% if user_lives_in_florida %}[X]{% else %}[ ]{% endif %}.

output_checkbox() has two optional keyword paramters:

  • checked_value (str): defaults to [X] but can be set to any string or even a DAFile or DAStaticFile with the image of a checkbox
  • unchecked_value (str): opposite meaning of checked_value and defaults to [ ].

output_checkbox() is contained in misc.py which means it is already included if you use the AssemblyLine framework. If you do not use the AssemblyLine framework, you can include it as follows:

modules:
  - docassemble.ALToolbox.misc