Blockpad's scripting language Stemscript can be used to for a lot of useful tasks.
The simplest way to use Blockpad scripts is through the console, and learning the basics here provides a foundation for understanding other applications for scripts.
To open the console, select View>Show Console in the toolbar. You can also press Shift + F2.
The console is a lot like a command line editor for Blockpad. You can run equations in it and make changes to the file you are working in.
The console uses a line-by-line version of Stemscript, but because Stemscript is largely based on Blockpad's formula language, it is very similar to writing regular Blockpad equations.
For example, you can do simple math equations in the console, like in an equation. Just type the equation into the console and press enter.
Units intelligence also works in the console.
You can name variables using an equals sign, then use those variable in console equations.
Note: if the value name exists in the active frame (the report or spreadsheet tab you currently have open), then this would actually overwrite that value (see below).
Note that although the syntax is similar to formulas, the console is more like using a programming language than it is like a spreadsheet.
For example, if you name something twice, the second value over-writes the first.
The console can read cells and values from the file you are working in.
To read a value from the console, just type in the name of the value.
You can do calculations with that value, and you can use it when creating console variables.
You can also read cells in the same way, and you can read ranges of cells that are then treated as arrays/matrices.
If the value or cell isn't in the currently active frame, then you need to specify the value location using dot notation.
So if you are currently working in Report2, but the value is in Report1, you need to type Report1.ValueName to read that value. Similarly, ff Report1 is open, and you want to read cell C4 in Sheet2, then type Sheet2.C4, etc.
You can use the console to assign values to cells and existing values.
When assigning values it is possible to erase or overwrite existing data, so it's important to be careful when using this feature.
To assign a value to a single cell, first type in the cell name, then an equals sign, and then the value you want to use. If the cell already has a value, then the original value will be overwritten with the new one.
This will work only if the spreadsheet you wish to write to is open. Otherwise you have to specify the sheet name infront of the cell using dot notation, e.g. Sheet2.D7 = "Bobby".
You can also write an array to a range of cells by typing the cell range (e.g. A1:A10 or B3:C5) and an equals.
You can overwrite existing values in a report in a similar way.
Type the name of the value, an equals sign, and the new value you want use. (If you use a name that doesn't exist, then the name is stored as a variable in the console, it doesn't create a new equation in the report).
Again, this only works if the report containing the value is open. If not, you need to specify the name of the report where the value is located using dot notation, e.g. Report1.B = 20 ft.
With these tools, you can read existing values in the file, run calculations on them, and then write new values to the file.
These analyses won't recalculate like normal formulas. They are more like a human reading off values, doing calcs with pen and calculator, and then typing new values in.
This can be good for different kinds of tasks, ranging from simple to complex. It's often good for the kinds of things you just need to calculate once, so you don't have a group of formulas that sit there.
The best and simplest example is assigning units to unitless numbers in a range of cells.
Sometime you have a group of cells in Blockpad where the numbers don't have units, but you want them to. Instead of editing each cell and manually typing in the unit, you can use the console to assign the units all at once.
To do this, you read and write to the cells in one console line.
Basically you overwrite the cell range by reading the cells and multiplying by 1, where 1 has the units you want. E.g. A1:A10 = A1:A10 * 1 ft/s^2.
If that's confusing, breaking it into a few lines might make more sense:
> cellRange = A1:A10 > cellRangeWithUnits = A1:A10 * 1 ft/s^2 > A1:A10 = cellRangeWithUnits
You can use the same method to strip units, just divide by 1, where 1 has the units you want the unitless number to be in. E.g. B6:D7 = B6:D7/(5 m^2/s).
Scripts are written with Blockpad's scripting language, Stemscript.
However, there are some differences from Blockpad equations, and a few of them are important to know before getting started with Stemscript.
- Semicolons are required at the end of a line of code.
- For new variables, the keyword var must be used before the name of the variable.
- Blockpad libraries need to be included to use the functions inside, even basic built-in libraries like the Math library.
- For comments in the code, use two forward slash signs (i.e. //).
Basically, each line that you would be typing in the console needs a semicolon at the end. Note that a "line of code" can go across multiple lines of text in the editor. It's the semicolon that marks the actual end.
The keyword var must be used before each new variable, but only for new variables. If you are writing over an existing variable or a value in the document, then don't use var.
var Height = 5 in; var Width = 2 in; var Area = Height*Width;
Libraries must be included in the script in order to use common functions. To do include libraries, this line of code must be at the top of the script for each library you wish to include: include(Library.LibraryName);.
When using Blockpad scripts for the first time, it makes sense to include all of the standard libraries at the top for any new script frames.
include(Library.Math); include(Library.Scripts); include(Library.Text); include(Library.Logic); include(Library.DateTime); include(Library.Docs); include(Library.Geometry); include(Library.Lookup); include(Library.Statistics);
Finally, use two forward slashes (//) for comments, text that will not be treated as code. When there are two forward slashes in the script, any text coming after the slashes in that line of text is not calculated with the code.
// This is not code var Height = 10 ft //The text before these slashes is code, but this text isn't
Below is a working piece of Stemscript code that illustrates the use of semicolons, var, including libraries, and comments.
// Calculate the hypotenuse of two numbers and write it to a spreadsheet. // This is a comment, and so not treated as code. include(Library.Math); // The math library is included, because the Sqrt() function is used. var A = 3 ft; // var is used to create a new variable, named A. var B = 4 ft; // the same is done for B. var C = 0 ft; // and C. C = Sqrt(A^2 + B^2); // C is overwritten here, so var isn't used
This page focuses specifically on using scripts inside of Blockpad documents and not Stemscript itself, so only the very basics are covered. For a more exhaustive resource on Stemscript, see the Stemscript page.
Macros are a type of script frame that can read values, perform calculations, and overwrite values, just like you can from the console. They are good for long series of manipulations that get tedious when using just the console or for smaller calculations that you want to do many times.
Macros are written with Blockpad's scripting language, Stemscript. There are a few things you need to know about Stemscript to get started with macros, and these are in the section above.
First let's look at how to set up a macro and use some simple pre-written code.
This is the basic outline for setting up a macro:
- Insert a script frame in a document.
- Click the insert button and select Script.
Let's do a simple example
Open a new Blockpad file, and insert a new spreadsheet. (insert button>Spreadsheet). Also insert a new script frame. (insert button>Script) Then change the script frame to a macro using the dropdown, paste in the following code, and click Run.
var Height = 10 ft; var Width = 12 ft; var Area = Height*Area; Sheet1.B4 = "The area:"; Sheet1.C4 = Area;
After clicking Run, you should see this in Sheet1 .
The basic idea behind macros is to read some values in the document, run some calculation on them, and then write an output into the document. The reading and writing is similar to using the console to read and write values, but the name of the top-level frame must always be specified using dot notation (e.g. Report2.Width or Sheet3.C4:C10).
It's best to show this through examples, so below are two.
Macro example 1
Say there is a value named Volume inside a report named Properties. This value corresponds to the volume of water in a bucket, and you want to calculate the weight of the water and then write it to cell C6 in a spreadsheet named Results.
This is an example of what that macro could look like.
var vol_water = Properties.Volume; var density_water = 62.4 lb/ft^3; var weight_water = vol_water * density_water to lb; Results.C6 = weight_water;
Macro example 2
As another example, say you have a range of cells (B2:B220 in Sheet1) that contain unitless numbers that represent mass values in grams. You want to summarize basic statistics of the range in Sheet2 and show the results in kilograms. Below are two different methods for this.
In both methods, the Math and Statistics libraries are included at the top, so that functions like Sum() and Median() are available. Also, a variable named massValues is created, and the range of cells is read, assigned units of grams, converted to kg, and assigned massValues.
In the first method, the output to the cells in Sheet2 is written a single cell at a time. The cells in column B are assigned a text value that labels the results. The cells in Column C show the calculated results of the different statistics functions, with massValues as the input.
include(Library.Math); include(Library.Statistics); var massValues = Sheet1.B2:B220 * 1g to kg; Sheet2.B2 = "Count"; Sheet2.C2 = CountAll(massValues); Sheet2.B3 = "Sum"; Sheet2.C3 = Sum(massValues); Sheet2.B4 = "Average"; Sheet2.C4 = Average(massValues); Sheet2.B5 = "Median"; Sheet2.C5 = Median(massValues); Sheet2.B6 = "Min"; Sheet2.C6 = Min(massValues); Sheet2.B7 = "Max"; Sheet2.C7 = Max(massValues);
In the second method, the outputs are written to a cell range all at once. The labels and calculation restults are all in an array that is assigned to the cell range.
include(Library.Math); include(Library.Statistics); var massValues = Sheet1.B2:B220 * 1g to kg; Sheet2.B2:C7 = [ "Count", CountAll(massValues); "Sum", Sum(massValues); "Mean", Average(massValues); "Median", Median(massValues); "Min", Min(massValues); "Max", Max(massValues) ];
Note that inside the brackets, the semicolons do not signify the end of a line, but the end of a row inside the array. The "line of code" here ends with the semicolon on the outside of the bracket. So, this summaryStatistics is a two dimensional array with 2 columns and 6 rows. It's broken into multiple lines of text to be easier to read.
For both of these methods, the results in Sheet2 will look something like this.
There is a lot more you can do with macros than these simple examples, but they give an idea on how to make things work.
Basically anything you can do with Stemscript can be used in macros, so to get a feel for how to extend the information covered here take a look at the Stemscript page.
Table of Contents
- Start a new document
- Dynamic equations
- Unit tracking
- Value names
- Reference unnamed values
- Text values
- Other value types
- Referencing a value
- Value name rules
- Names used multiple times
- Renaming and auto-updated references
- Built in values
- Visual editor
- Show steps and more
- Value formatting
- Date and time arithmetic
- Logic and Boolean values
- Matrices and arrays
- Enter an array or matrix
- Array names
- Matrix calculations
- Arrays - more than just numbers
- Array formulas in spreadsheets
- Array parentheses lookup
- Advanced array functions
- Complex numbers
- Spreadsheet in a file
- Sort and filter
- Conditional formatting
- Blockpad specific features
- Open a CSV file
- Mini-spreadsheets in a document
- Reports in a file
- Reference values from other reports in a file
- Header and footer
- Misc. document formatting
- Drawing inside a document or file
- Drawing objects
- Lines, points, and shapes
- Text labels
- Linear dimension labels
- Selecting multiple objects
- Ordering objects
- Using the point snapping
- Points you can snap to
- Horizontal and vertical from points
- Parallel or perpendicular lines
- Point snap options
- Transformations - resizing and moving
- Format drawings
- Keyboard input and canvas scales
- Top level frames
- Frames in Frames
- Value containers and location
- Frames and sections are containers
- Containers inside containers
- Dot notation to specify a value in a container
- Capture values
- What is a block?
- Block example
- Use the block results
- Block inputs
- View block as table
- Block instances and block definitions
- More examples
- Create a block
- When to make a block
- Make a block with Blockpad calculations
- Update a block definition
- Create a block using scripts
- Block tables
- Examples library
- Use library items in a document
- Use the long form library item name
- Assign a shortcut name to the library
- Include a library in a file
- Use a library number value
- Use a library function
- Use items in a library frame
- Use a library data table as function
- Use library blocks
- Core, built-in, and subscription libraries
- Create personal libraries
- Save items to your library
- Manage your library online
- Library subscriptions