Before working with the PlanSwift API, a good understanding of PlanSwift's internal structure is recommended. To review PlanSwift's structure, the under-the-hood (U-T-H) tab needs to be enabled.
Warning: By modifying or changing anything in the back end, you may adversely affect the operation of PlanSwift. Modifications should be done in a read-only mode. If any modifications are done to the back end of PlanSwift, those modifications will be lost when PlanSwift is re-installed.
Follow these steps to enable PlanSwift's under-the-hood tab.
...
Property Object Structure Overview
***Review this later. Understanding the structure of Items and Types will also be important to developers. Type is a very specific word that PlanSwift uses. A folder (in the Under-The-Hood window) is a physical Item of the Type "Folder." Everything in a Folder is considered to be an Item. Items are the "building blocks" of PlanSwift. There are two types of Items in a Folder: one is "Types" and the other is "_Types." These are the two identifiers for what that Item is. The "_Types" are the base class (a master template containing the default properties) of all Items in PlanSwift. The Type allows the user to inherit an "_Type" and customize it into a new custom Type. As an example, several different styles of masonry bricks might be utilized in constructing a building, but if one style of brick isn't available in PlanSwift, then a developer could use one of the existing bricks (_Type) as a base to create a new brick (Type) and assign it different properties. It would then be saved as a new, user-developed "Type." See Figure 1.2-0. Brick A would be a standard brick (_Type). Dimensions would be added to the standard Brick A. And Brick B is the resulting customized brick (Type).
_Types
...
If you do not have PlanSwift open, follow steps 1-6 in the previous section (1.1 PlanSwift Structure and PlanSwift Item Structure Overview) to open PlanSwift and display the U-T-H tab; then click on the U-T-H tab to open the U-T-H window (see Figure 1.2-1 below). The two red arrows point at _Types and Types. Any new Types that you create will be viewable here. Click on the Settings tab on the top ribbon menu.
...
The _Assembly Item (see Figure 1.2-20) doesn't have any child items, because _Assembly basically is a container of parts. It only inherits from _Item in the same way as _Part inherits from _Item.
In summary, PlanSwift uses the _Types Items to configure the default setup configuration of all Items within PlanSwift.
Types (Non-Underscore "Custom" Types)
...
Object Property Model
- If you are not still on the Advanced Joist Tool Properties window, then follow the Steps 1-5 of paragraph 1.2.2 to open this window (as a reminder: click Templates tab, Click Types tab, open Scripted Tools folder, open Items folder, double-click Joist Tool, then click on Advanced). This window is divided into ten different groups: Item, Estimating, Fill, Takeoff Data, Work Breakdown Structure, Other, Audit Trail, Joist Properties, Videos, and Events.
- Double-click on the Cost Total field under Estimating. This opens the Edit Property window (Figure 1.3-2) for the Joist Tool's Cost Total property, which is grouped under Estimating. Developers can use this window to modify the physical property settings (or attributes) of the property model. Everything that is in the Edit Property window is available through API. This is where a developer will spend a lot of time setting up attributes to properties of Items, so it's very important to understand what the functions of these properties do. Note that the descriptions that follow are modeled for COM rather than for scripting. Click on Cancel to close the Edit Property window, then click on any item in the first column of the Estimating group.
- Now click on the Add Property icon as shown in Figure 1.3-3.
- This opens a new Edit Property window. Notice that the Name: field is blank in this window, allowing you to give it a name of your choosing. The Type: field's down-arrow opens a drop-down menu that allows you to specify the type of value assigned to the field: Number, Color, Text, Memo, CheckBox, Path, Image, Large Image, Type, Script, File, Large File, File Name, Folder, Font Name, Connection String, Slider, and Dimension. The Type: field's default is Number. The attributes a developer would most commonly use are Text, Memo, or Number. A few others, including CheckBox and Slider could also be useful. Selecting CheckBox would display a checkbox, which represents a boolean value (true of false): if it is checked, it is true; if not checked, then it is false. Enter the name Test Property in the Name: field; click on the Type: field's down-arrow and select CheckBox from the menu, and then click on OK.
- You will now see "Test Property" at the bottom of the first column in the Estimating group. The next column to the right is the check box. Since the check box is not checked, its value is False, as seen in the 5th column (Result) to the right. Once checked, its value shows as True.
- Double-click on Test Property to open its Edit Property window again (Figure 1.3-6). This time select the Slider tool from the Type: drop-down menu. This opens the Slider Options (see red arrow). The Slider function is very useful and has its own properties, which is the minimum value and the maximum value. Enter "1" in as the minimum value and "100" in as the maximum value; set the Tick Frequency: field to 10 so that the ticks will show up every tenth time; and check the box Show Ticks. Now click on OK.
- The Test Property property will now show a slider bar with eleven tick marks. Click and hold on the slider on the bar, and drag it to anywhere on the bar; as you drag it, the value will displayed in the 5th column (Result). The Slider function can be valuable in cases where you might have an image transparency function, or you need a finite number based off a value, or you need any type of minimal adjustment. Click on Type: again and select Number.
- The other Type: field values may be useful but will not be covered at this time.
- The Group: field shows that Test Property is assigned to the Estimating group. Clicking on the down-arrow allows you to assign it to one of the ten available groups in the Joist Tools Properties window: Item, Estimating, Fill, Takeoff Data, Work Breakdown Structure, Other, Audit Trail, Joist Properties, Videos, or Events.
- The Tool Hint: field allows you to enter a short description of the tool, which will be visible in the Form window when the cursor is hovered over the property. Such a hint can be helpful to explain the functionality of a property to a user. To see this in action, type "Joist Tool Hint" in the Hint: field; then click on OK to close the Edit Property window.
- At the Joist Tool Properties window, click on the box for the Test Property property you created (see arrow in Figure 1.3-7) so that it can be displayed in the Input and Form windows.
- Scroll to the bottom of the Joist Tool Properties window and click on Form, then hover over the Test Property text until the "Joist Tool Hint" appears with a yellow background as shown in Figure 1.3-8.
- Click on Advanced again to return to the Joist Tools Properties window, double-click on the Test Property property you created previously, and delete the Tool Hint: text. The Edit Property window for the Joist Tool should look similar to Figure 1.3-9.
- The Remember Value: checkbox has no functionality at this time.
- The Parse Formula: checkbox, when checked, causes anything within brackets to be read as a variable. If this box is not checked, then the text inside the brackets is read as a text string, not as a variable. By default in COM, this box is checked automatically.
- In the Input Options area of the Edit Properties window, there is an Input checkbox and a Condition: field. When the Input checkbox is checked and the condition in the Condition: field is satisfied, then the property will be displayed in the Form window. If the Condition: field is not satisfied, then the property will not be displayed in the Form window. If the Input box is checked but the Condition: field is blank, then the property will show up in the Form window. If the Input box is not checked, then the property will not be displayed in the Form window. As an example, enter [New Length] = 10 into the Condition: field. Also, make sure the Input box is checked. Click on OK to close the Edit Property window. Now click on Form at the bottom of the Joist Tools Properties window. You'll see in Figure 1.3-10 that there is no Test Property field. You will also notice that the New Length field is blank. Now put the value of 10 into the New Length field and press your keyboard's Tab key to invoke the changed value.
- The Test Property field now appears. If you change and invoke the value to anything but 10, then the Test Property field will disappear.
- Click on Advanced to return to the Joist Tool Properties window, and double-click on Test Property. The Compiled Options are TBD.
- The Input Units and Units (Output Units) area allow you to specify the Input Units and Output Units columns in the Joist Tool Properties window (see Figure 1.3-13). You may specify whether they are to be hidden or locked by clicking the check boxes for Hidden or Locked. You may also specify the decimal places by entering a decimal value in the Decimal Places: field.
- The When creating new items of this type: area can be set to Normal, Inherit, or Ignore. The Normal setting is TBD???. The Inherit setting is TBD. The Ignore means that "anytime I inherit a property, I specifically do not want this property to be on that inheritance or that derived item.
- Checking the Formula checkbox allows the formula and the result to be inherited. Checking the Result checkbox allows only the result to be inherited. The Pull From: field is not commonly used. It allows you to inherit the actual result from a completely different item from either the same estimate or somewhere else by providing the relative path of that item and the property. The List Type: field allows the developer to provide a list that act as a drop-down list to the property (see Figure 1.3-15) but will not be discussed at this time.
- This completes the coverage of what you need to know to get started using the API.