Blocks

Blocks give you more power over your documents, and can help you to automate boring tasks.

What is a block?

Really, it's best to answer this question with examples of different things blocks can do.

In short though, blocks are mini-apps that generate content inside a document, typically as a calculation module, and they can be connected to the rest of the document using formulas.

You can create these mini-apps with normal Blockpad equations, or with programming for more complex tasks.

Block example

Let's walk through a simple example.

Insert an example block

1. In a report, click the Insert Block icon in the top left of the toolbar.
2. In the window that appears, click Examples in the list of libraries to the left (it may take a moment to load).
3. Click the Rectangle icon in the group that appears.
4. Click Continue.
5. Click Insert Block.

Congratulations on using your first block!

All of the calculations you see are automatically done using the length and width inputs and the block definition stored in the Examples library.

Note that you used the examples library to access this block.

Use the block results

You can access the results of these calculations in a formula, and continue any calculations.

If the block inputs change, these output references are updated accordingly.

Reference a block output

1. Start a dynamic equation.
2. Click on the block.
3. When the block name appears, type a period (.).
4. Select the output from the dropdown list that appears.
5. Use this like any other value in an equation.

Note that this is similar to accessing a value in a sub-frame.

You can change the name of a block instance, so that the outputs have more sensible reference names.

Change a block name

1. Select the block.
2. Open the properties window.
3. Type in a new name next to the Name property.

Block inputs

To edit the inputs, double click the block, change the inputs, and click update block.

Use formulas for inputs

The inputs to a block can be a formula (like a formula in a spreadsheet cell), so you can reference values that are defined in the document.

In the example below, length_1 and width_1 are calculated in the document, and then referenced in the block as inputs.

View block as table

You can view a block as a table of inputs and outputs, instead of the full view with equations, drawings, and intermediate steps.

The table view is better for compact information, when seeing the steps isn't necessary.

Show block as table

1. Select the block.
2. Open the properties window.
3. Change Result from Full to Vertical table or Horizontal table.

Block instances and block definitions

You can insert that example rectangle block multiple times in the document, and each one can have different inputs (even inputs from other rectangle blocks). Just follow the steps outlined above.

This really shows the power of blocks. Blocks allow you to seperate the how of a calculation from the implementation of that calculation.

The how, or the block definition, is stored in the library, just once. The implementations, or the block instances, are used in multiple places and multiple files. All of these block implementations have different inputs, but all have the same definition for how the inputs are used.

What's more, if you change the how for the calculations in the block definition, all of the instances can be updated to show that change. You don't have to anxiously copy-paste the change throughout your documents.

More examples

Composite rectangle shape builder

The rectangle block above was made using regular Blockpad equations and drawing. More complex blocks are possible using scripts, like the RectangleBuilder block in the Examples library.

Follow the steps to insert the rectangle block above, but choose RectangleBuilder.

For this block, you can build a composite shape that consists of rectangles by adding rectangles of various sizes. The properties of the final shape are calculated, and you can use them in calculations, just like above.

Buckling

You don't need to know scripts to create complex blocks though. The buckling example block was made using only Blockpad calculations.

It makes use of conditionally hidden sections to make different drawings show up and the value definition property on a field to create a dropdown list.

Charts

Blockpad charts are actually blocks written using Blockpad scripting.

When you insert a chart, you're really just inserting a special kind of block.

Table of Contents

The table of contents tool is also actually a script block that reads the header information from a frame and creates a table of contents.

Create a block

So how do you make your own block to use? Moreover, how do you know when to make your own block?

When to make a block

Blocks are all about making repeated work easier, so the answer to "when to make a block?" is when you or your team is doing something over and over again.

Below are some concrete situations where you might want to make a block

• You're retyping or copy-pasting the same calculations

  • This is exactly the tedious, mistake filled work blocks are made to replace!

• You have a calculation template

  • Turn that file template into a block.

• You're copying inputs and outputs between multiple files

  • This is where the real magic happens.
  • Turn each of those files into a block, and then insert those blocks all into one document, connecting the inputs and outputs with formulas.

• You have a calculation to share

  • If you have a calculation to share with your team, blocks in the library are perfect for that.

• You want to protect that shared calculation

  • Unlike sharing a file, when you share a library block only the inputs can be changed, so there's no risk of anyone messing up the calculations you worked hard on.
  • Plus, if there's intellectual property you want to protect, you can hide parts of your calculation.
  • The end user can change the inputs and see the results, but can't steal your calculations.

• You want more control over calculation changes

  • Block definitions are stored in a central place, unlike spreadsheet files that proliferate and change.
  • If a change needs to happen, you can change it in that central place.
  • Now any block that uses that definition can be updated (version control is also possible).

Make a block with Blockpad calculations

Once you've decided to make a block, the first step is to create the calculation itself in Blockpad.

You want a complete section of calculations where you can specify inputs and get outputs, without any human help along the way.

For the sake of this walk-through, we'll use the calculations shown below, essentially a simple version of the example rectangle block.

Create a block using the rectangle example

1. In an empty report, type the rectangle equations in the image above.
2. While still in that report, select Blocks>Create a Block in the toolbar.
3. Select the equation for length, then click the Add inputs button.
4. Do the same for width.
5. Select the equation for area, then click the Add outputs button.
6. Do the same for perimeter.
7. Click Continue.
8. In the next window, you should see a library in the left column that is based on your username. Click it.
• Note: You can save a block to any library you have write permissions for.
9. Then, type RectangleBlock in the name box at the bottom of the window.
10. Click Save to Library.

When you finish the steps above, you should be taken to a web page where you can see your block online. You can edit the inputs on this page and see how it affects the block displayed on the right.

You can always come back to this web calculator using the url, or navigate to it from the online Library interface. You can also share the url with others, and they can use it if you set the permissions.

The block you just made is saved in your personal online library. You (and anyone you give permission to) can now access it from any of your documents.

Note that accessing a block requires internet access. However, once a block is used in a file, the file continues to work with or without internet access.

To insert the block, follow the steps above for inserting a block, using the library you stored the block in.

Create a block from equations

Below are the generalized steps for creating a block from equations.

1. Have your equations alone in a report or other frame.
2. Navigate to that frame in the document (the mouse cursor should be there).
3. In the toolbar, select Block>Create a Block.
4. Specify the inputs and outputs.
   1. To specify an input, select an equation and click the Add inputs button.
      • Hold ctrl and click to select multiple equations.
   2. To specify an output, select an equation and click the Add outputs button.
5. Click Continue.
6. Select a library you have write access to (or create a new library or sublibrary).
7. Type in the name for the block.
8. Click Save to Library.

Update a block definition

Block definitions can be changed, and when they are, all blocks using that definition can be updated to reflect it.

To do so, you overwrite the existing block with a new one. Follow the same steps as creating a block, but instead of a new name and library assignment, use the name and library of the block you wish to update.

Create a block using scripts

We are still working on the documentation for this feature.

If you are interested, please contact us or send an email to ej at blockpad dot net, and we will be happy to work with you.

Overwrite an existing block:

1. Have your equations alone in a report or other frame.
• Note: it is best practice for the new input and output names to match the existing ones. Otherwise, when the block instance updates in a file, the inputs must be reassigned.
2. Navigate to that frame in the document (the mouse cursor should be there).
3. In the toolbar, select Block>Create a Block.
4. Specify the inputs and outputs.
5. Click Continue.
6. Select the library that the existing block is located in.
7. Select the block you wish to update (the name will appear in the name bar at the bottom).
8. Click Save to Library.

Note: if a file that uses the block is open, select Formulas>Update All in the toolbar to update the block instances in the file.

Block tables

Block tables are many different instances of a block all in one table. The block instance is the row, and the inputs and outputs are the columns.

With block tables, you can easily turn a regular Blockpad calculation into a table of different scenarios without ever re-doing the calculations.

When to use block tables

Block tables probably sound useful, but when are good times to actually use them?

Use block tables when you want to see many instances of a calculation all in one place, in a table format. Compared to multiple blocks in a file, this is much more compact, but you lose the clarity of seeing the equations.

Some times you might consider block tables:

• Exploring multiple design cases

  • Make a block for one case, and then edit inputs in a block table to explore multiple scenarios.

• Exploring possible design solutions and their affects

  • Make a single block for the design calculations, then explore different possibilities all in a table.

• Viewing how a calculation changes over time (or any other variable)

  • You can make the calculation once, then make a block table where the time input is changed over the many rows.

Use block tables

Block tables are pretty straightforward to create once you have a block.

Note: to use block tables, the Blockpad add-in must be installed for Excel.

For blockpad calculations that aren't a block, first make a block following the instructions above.

Create a block table

1. In the toolbar, select Blocks>Create Block Table.
2. Navigate to the block you wish to use (e.g. Examples -> Rectangle).
3. Click Create block table
4. Wait for a new Excel file to open with the block table.

In the Excel file that opens, you can change the inputs, and the outputs will change according to the block definition.

You can use regular Excel formulas to define the different rows of inputs, and you can extend the rows like you would normally in Excel.

 

• Next - Using libraries