Getting started

Enabling the BHoM

^{NOTE: loading time has been cut from the above animation}

Using BHoM Methods

Using the BHoM Ribbon Interface

Using Global search

Like the plugins for Grasshopper and Dynamo, the Excel BHoM supports searching for methods with Ctrl+Shift+b. This will translate to the Excel Function that corresponds to the selected method. Methods with no parameters are automatically created and run, methods with parameters are started for you and drop you in edit mode after the opening parenthesis.

Optional parameters

Optional parameters can be left empty and will take on their default value. An optional parameter is signified by its name appearing in [square brackets]. Their default value is indicated in the description, also in square brackets (see below)

If all optional parameters you wish to leave as the default are at the end of the function, you can simply close the function's parentheses after the last parameter you are giving a value for.

If you wish to leave an optional parameter but define a successive one you must include a comma, but shouldn't place anything between that and the following comma.

Object references

Since only numbers and strings can be stored in an excel cell, we cannot store complex objects to pass around. As such the objects are kept by Excel_UI and a reference to them (as a string) is placed in the cell in their place. When a string matching the form of one of these references is found, the ID portion is looked up in the internal dictionary and the resulting object is passed to the method being called.

The form of this reference is <text> [<id>] the <text> portion is ignored by the plugin and serves as an indicator for the user, when the reference is generated the text is the type of object that it refers to, such as Node [QrA2P+kU], the user can modify this string at will so long as the ID portion is left in tact and appears at the end of the text.

Dealing with lists

Lists as input

Methods that expect a list for a parameter can be passed a cell reference or a range reference. If a cell reference is passed it is treated in the following ways: if the cell reference contains a List object then the List object referred to is passed to the method, converting its storage type if necessary; if the cell is not a List then it is added to one and becomes a List with a single element. If a range is passed then each cell in the range is treated as a list element and conversion is attempted to the list's storage type.

Lists as output

Working with a list outputs in Excel is little more difficult than in Grasshopper and Dynamo since they are not automatically expanded in the UI. A useful method to expand a list into its elements is to use a formula that uses Query.Reflection.ICount?by_ListOfObject(<list>) and Query.Reflection.Item?by_ListOfObject_Int32(<list>, <index>) to determine the length of the list and retrieve items from it.

e.g.

=IF(ROW()-ROW($A$1)<Query.Reflection.ICount?by_ListOfObject($B$1),
    Query.Reflection.Item?by_ListOfObject_Int32($B$1,ROW()-ROW($A$1)),
    ""
)

Where the first cell that contains the formula is $A$1 and the list is in cell $B$1. The formula can then be dragged down for a lot of rows such that it will be able to contain all elements in the list even if the list grows. Use your judgement on the likely size range of this list to decide how far to drag this formula.

Couple this with GetProperty in order to tabulate information about a list of objects.

Create Custom

CreateCustom works like CreateDictionary in that takes a list of keys and a list of values to assign to those keys but is based on the BHoM type that is being used. Properties that exist in the object are set, properties that don't are added to the object's CustomData dictionary.