Skip to content

Lab 02 - VoltScript Project with VoltScript Library Module

Duration 15 min

What you will learn

You'll learn how to use atlas.json and structure a VoltScript project. You'll also learn how to integrate external library modules with a Use statement.

Prerequisites

  • Lab 01 completed

Steps

atlas.json

Note

The atlas.json is the VoltScript equivalent of Node.js's package.json, Maven's pom.xml or Rust's cargo.toml. It defines metadata about your project (name, version, authors, license), dependencies, structure, and scripts. You will use this more fully in the next exercise.

  1. Select File → Open Folder.
  2. Create a new folder in your user directory called "lab-02".
  3. Right-click in the empty pane and select New File from the context menu.
  4. Name the file atlas.json.
  5. Type an opening curly brace "{" and press enter. VS Code automatically adds the closing curly brace "}".

  6. If the PROBLEMS view isn't visible, select View → Problems. Note the validation errors, identifying required fields.

    atlas.json validation

  7. Set name to "lab02".

  8. Set version to "1.0.0".
  9. Set description to "Lab Number 2".
  10. Add the authors array. Add an array element with your name.
  11. Set sourceDir as "src". Set mainScripts as main.vss.
  12. Use content assist (Ctrl + space) to see other elements that can be added.
  13. Set libsDir as "libs".
  14. Save the atlas.json.

Complete atlas.json

libs directory

Note

In the same way that you can create Script Libraries and use them in Domino Designer with the Use instruction, the same can be done in VoltScript. The terminology used to refer to these is "VoltScript Library Module".

  1. Right-click in the empty pane and select New Folder from the context menu. Name the directory "src".
  2. Right-click in the empty pane and select New Folder from the context menu. Name the directory "libs".
  3. Right-click the "libs" directory and select New File from the context menu. Name the file "Lab2Functions.vss".
  4. In the .vss file, add Option Declare and Option Public.

  5. Type Sub. Snippets will offer you "Sub...". Press Enter to select the snippet. The following code will be inserted.

    Sub ProcedureName(ParameterList)

End Sub

  6. ProcedureName is selected. Rename the sub "PrintMessage" and press tab to move to the next variable.

  7. ParameterList is selected. Overtype it with message as String.
  8. Move down to the body of the sub, and type Print message.
  9. Move out of the sub, type "fun", and select the "Function..." snippet by pressing Enter.
  10. FunctionName is selected. Rename the function "Square". Press tab to move to the next variable.
  11. ParameterList is selected. Overtype it with value as Integer.
  12. ReturnType is selected. Overtype it with Integer. Only the first instance of this will be replaced and a compilation error will remain "Variable not declared RETURNVALUE".

  13. On the first line of the function, type value *= value.

    Tip

    Additional mathematical assignment operators have been added. As well as the obvious ++ and -- options, +=, -=, *= and /= (with its alias \=) have been added.

  14. Amend the last line of the function to Square = value.

  15. Save the file.

Main script

  1. Right-click the "src" directory and select New File from the context menu. Name the file main.vss.
  2. In the .vss file, add Option Declare and Option Public.

  3. Add the statement Use "../libs/Lab2Functions".

    Note

    We can use relative paths in the Use statement. Using forward slashes make the Use statements cross-platform. Paths to Library Modules and downstream Library Modules (modules used in other Library Modules) need to work from any script opened. So all Library Modules should be at the same level of the hierarchy.

  4. Add a Sub Initialize.

  5. Add Call PrintMessage("Hello World").
  6. Add Call PrintMessage("4 x 4 = " & Square(4)).
  7. Press Ctrl+F5. This is a shortcut to save and run the script.
  8. Select VoltScript: Save & Run Script. It's listed first as the most recent command used.

How to check

Print to console:

Hello World
4 x 4 = 16

The completed lab is available on GitHub.

Things to explore

  • Change the last line of Lab6Functions' Square function to Return value. Return can be used to return a value from functions, and exit out of a function or sub.
  • Test downstream VoltScript Library Modules (one module that uses another).
  • Test to understand how relative paths need to work from all levels of the hierarchy.

Next step

Proceed to Lab 03 - Using VoltScript Extensions and Dependency Management.