Copy of Structure Overview 2

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.

1. Open PlanSwift.
   
   
2. Click on Settings along the top ribbon bar (see  #1 on Figure 1 below).
   
   
3. Select Interface from the options on the left (see #2 on Figure 1 below).
   
   
4. Click on Show Under the Hood Screen. (see #3 on Figure 1 below). 
   
   
   
   
   
5. For the password, please contact your PlanSwift representative–discuss with Mike Ramsey. Enter "mayhem" (see number #4 of Figure 1) and click on Ok.
   
   
6. A U-T-H (for "Under the Hood") now appears on the top ribbon bar (see number #1 of Figure 2). Click on U-T-H to display the the screen resembling Figure 2.
   
   
   
   
   
7. ***Review.: Part of Job Topic sectionThis window shows the complete back end of the PlanSwift structure, which shows everything from your jobs, your storages, your plug-ins, and your types. These are the most commonly utilized items when you're developing against anything within PlanSwift. The structure always starts at PlanSwift, which is the parent, or the root object, for everything that you want to access (see 1 of Figure 3). Each of the folders beneath PlanSwift is a child of PlanSwift. Click on the + to the left of Job folder (number #2 of Figure 3) to open the Job folder, which will display the Pages, Takeoff, and Bookmarks (see number #3 of Figure 3). This Job folder contains the current active Job that is loaded into PlanSwift at the time. When programming, in order to access job information in the Job folder, you would use the relative path of \Job to access the Job folder. Under the \Job folder you will see Pages, Takeoff, and Bookmarks. If there is no job loaded, then the job's value will be Null. Pages items will reside in the \Job\Pages; Bookmarks items will reside in the U-T-H \Job\Bookmarks folder. The PlanSwift Pages information will reside in the U-T-H \Job\Pages folder. The PlanSwift Estimating tab information will reside in the U-T-H\Job\Takeoff folder.
   
   
   
   
   
8. ***Review.: Part of Job Topic section. Figure 4 shows an example of the Estimating screen. 
   
   
   
   
   
9. ***Review.: Part of Job Topic section. Note the similarities in the red rectangular areas in Figure 5 (U-T-H screen) and Figure 1.1-6 (Estimating screen). When you are developing, you will not be writing to an estimating screen; you will be writing into the the U-T-H \Job\Takeoff folder, which is the backend structure. As you update this backend structure, it updates the rest of the PlanSwift screens.
   
   
   
   
   
10. ***Review.: Part of Job Topic section The Pages tab works similarly (see figure 7). If a page is added on the backend, then it will reflect in the PlanSwift screens.
    
    
    
    
    
11. Review: Part of Storage Topic. If you need to access templates, those can be accessed via the Storages (\Job\Storages). The example in Figure 8 shows only Local storage being set up. If you have a LAN, that would show up as well. Templates can be tricky because they can live anywhere within your network. Right click on the Local to open the Properties box for Local.
    
    
    
    
    
12. Review: Part of Properties Topic. Figure 9 shows the properties box for Local: Click on Advanced.
    
    
    
    
13. Review: Part of Properties Topic. Clicking on Advanced opens the AdvancedProperties window (Figure 10), which will tell you exactly where your storage is located physically on the computer. If you have a network set up, then a property??? will be set up called network.path ???. Use the item.fullpathproperty within the API. Use the full path here if you need to copy files to that network location. ??? Need network example if possible.
    
    
    
    
    
14. This completes the overview coverage of the COM and Scripting capabilities of PlanSwift and how data is stored in PlanSwift.
    
    
    

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

1. 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.

   

2. Right clickonthe Open Job Dialog folder in Figure 1.2-2:
   
   
   
   
3. Select Properties from the drop down menu in Figure 1.2-3:
   
   
   
   
4. Click on Advanced in Figure 1.2-4:
   
   
   
   
5. This opens the advanced Properties screen in Figure 1.2-5. Note that the Type of the Open Job Dialog is "Folder" (See #1 in Figure 1.2-5). Note that the "Inheritance path is shown by arrow #2. Click in the Folder field to diplay a down arrow, then click on the down arrow.
   
   
   
   
6. This displays a dropdownmenuthat allows you to select the Type (see Figure 1.2-6). Select Item from the dropdown menu. 
   
   
   
   
   
7. This opens the screen shown in Figure 1.2-7. Selecting Item changed the Folder Item type to a generic PlanSwift Item type. Note that the properties of a generic Item are significantly different than the properties of a Folder Type. Note also that the Inheritance path at the bottom of the screen now displays as "_All\_Item". The Type controls the functionality of an Item and what that Item does. Click on Cancel at the bottom of the screen, and select No from the warning window that asks if you want to save any changes. 
   
   
   
   
   
8. If you aren't at the U-T-H window, click on the U-T-H tab on the top ribbon menu. Now click on the + box next to _Types, then open the _All box the same way, and then click on _Item. You should see the same information as displayed in Figure 1.2-8.Types, then, are the generalistic types of Items that we have. When we specify a Type with an underscore (_), we are specifying a base class of an Item or Item _Type. At the arrow 1 in Figure 1.2-8 you will see that _Item is broken down into three different _Items: _Takeoff Item, _Part, and _Assembly. Each one of these has a different configuration. A _Takeoff Item is a specific digitizer Item, meaning you're going to have an area, a line object (linear or segment), or a count object. Their primary function is to perform very specific actions to record data onto images. They are completely separate from any other Item type in PlanSwift and are the only items that can be used to record digitizing information. Click on the + next to _Takeoff Item.
   
   
   
   
9. Now click on the +'s next to _Line and _Part so that your screen resembles Figure 1.2-9. Here you can see the _Linear and _Segment configurations for the _Line  takeoff item. The _Linear and _Segment items are inheriting the parent's Item properties. The same applies, for instance, to the the _Material, _Labor, _Equipment, _Subcontract, and _Other configurations for the _Part item. Right click on the _Line type in Figure 1.2-9.
   
   
   
   
   
10. Click on Properties (Advanced) in Figure 1.2-10.
    
    
    
    
    
11. Click on Advanced in Figure 1.2-11.
    
    
    
    
    
12. The Properties for the _Line are shown in Figure 1.2-12. The properties's rows may be shaded in blue, green, white, orange, yellow, and gray (not all shading colors are shown in this particular figure). 
    
    Blue Fill: The blue fill on the row indicates that the property on that row was inherited from the system (somewhere along the inheritance path)–as both a result and a formula (every value is available). 
    
    Green Fill: The green fill on the row indicates that the property on that row was inherited--as a result only--from the system. 
    
    White Fill: The white fill on the row indicates that the property on that row was created by the user or was green (no longer inherited) and was modified and turned white. 
    
    Orange Fill: The orange fill on the row indicates that you modified an inherited property but that you want to maintain the inheritance. 
    
    Yellow Fill: If you see yellow fill, it means that you have locked the property. 
    
    Gray Fill: If you see gray fill, then that indicates that the property is hidden. 
    
    To unhide any rows that are grayed, click on the Show:Normal selection indicated by the red arrow in Figure 1.2-12.
    
    
    
    
    
13. Note that the Show mode you are currently in is "Normal." Click on the All selection from the Show: dropdown menu. 
    
    
    
    
    
14. Scroll down to the bottom of the window. A grayed row is now visible (see the red arrow in Figure 1.2-14); this row is gray because the item is hidden. (why are there other hidden properties that are green???)
    
    Padlocks: The column of padlock icons on the right allows you to lock or unlock whether the property Name, Formula, Input Units, Adjust, Result, and Output Units values (listed in the column headers) can be edited. Click on the padlock to toggle between locked and unlocked. 
    
    Lightbulbs: The row of lightbulbs to the right of the padlocks allows you to select whether the property for each row is visible in the Show: Normal mode. Clicking on a yellow bulb when in Show: Normal view causes the property on that row to disappear and be hidden. Clicking on a yellow bulb when in Show: All turns the bulb blue; a property row with a blue bulb will not be visible in the Show: Normal mode. Clicking on a blue bulb when in Show: All mode, turns the bulb yellow and allows the property to be shown again when in Show: Normal mode. 
    
    
    
    
15. Click on Show: All and select Show: Normal for the mode (see step 13, but select Normal from the dropdown menu).
    
    
    
    
    
16. Click on Cancel to cancel out of the Properties - [_Line] window so that you do not save any changes. Now double-click _Area under _Item in Figure 1.2-16.
    
    
    
    
    
17. This opens the Properties - [ _Area ] window. The _Area item is derived from the _Takeoff Item and has had additional properties added for that Item. All of the blue shaded rows of properties have been inherited from _Takeoff Item. Click on Cancel.
    
    
    
    
    
18. Double-click on the _Part Item, then click on Advanced.
    
    
    
    
    
19. The _Part Item is the base class of _Material, _Labor, _Equipment, _Subcontract, and _Other. All of these inherit from _Part. Now double-click on the _Assembly Item.
    
    
    
    
    

20. 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)

1. The next steps will cover the Types (without the underscore) Items. These Types are custom types that are added to PlanSwift by customers or developers or anybody who needs to add additional functionality to the default class Items without having the need to go in and change the default properties. When working with Types, developers would not use the Under-the-Hood (U-T-H) tab, but would instead go into the Templates tab, then the Types tab. Types may not be visible from the Templates tab ribbon menu (Figure 1.2-21); if it is not, then first click on Settings on the Main Menu ribbon bar.
   
   
   
   

2. After clicking on Settings (#1 arrow of Figure 1.2-21), click on Interface (#2 arrow), then click the check box for Show Types Tab in Templates Screen (#3 arrow).
   
   
   
   
   
3. Now click on Templates tab (Figure 1.2-22) and you will see the yellow Types tab, which is orange in color and has a cog to the left of it. Click on Types: yours will look similar to the one below, except that the window shown below has most of the + boxes clicked on to display the sub-Items. When PlanSwift ships, it comes with several custom Items. These items are categorized according to the base digitizer class type. Open Scripted Tools, then Items, then double-click Joist Tool to see its properties.
   
   
   
   
   
4. The Joist Tool properties are shown in Figure 1.2-24. The Joist Tool template has been configured to completely handle a joist tool layout of various sizes. Click on Advanced to see the advanced Joist Tool Properties.
   
   
   
   
   
5. When in PlanSwift, every Item has a Property Structure, which remains the same for all Items throughout PlanSwift, because all Items inherit from their parent-class Item. Based off the Type you have selected, various properties may be added. Each property for an Item has columns (see Figure 1.2-25) specifying the property's Name, Formula, Input Units, Adjust, Result, and Output Units.
   
   
   
   Name: The Name column identifies the name of the property. When coding, a developer will access this property either via the name or via an index.
   
   Formula: The next column, Formula, allows the developer to input a formula and/or a numerical value. Variables are placed in brackets; operators, such as +, -, /, and * (and others, such as sin, cos, tan, etc.) may be used to operate on any variables or numerical values. The operators that are available for use in formulas are the same ones that would be available in a calculator or in the scripting language being used.
   
   Input Units: The Input Units column allows the developer to select the input units. This can be inches (IN), feet (FT), yards (YD), miles (MI), millimeters (MM), centimeters (CM), meters (M), and kilometers (KM), each (EA), square inches (SQ IN), square feet (SQ FT), square yards (SQ YD), square miles (SQ MI), square millimeters (SQ MM), square centimeters (SQ CM), square meters (SQ M), square kilometers (SQ KM), cubic inches (CU IN) through cubic miles (CU MI), cubic millimeters (CU MM) through cubic kilometers (CU KM), and dollars represented with the dollar sign ($). The Input Units calculation operates on the value developed by the Formula column.
   
   Adjust: The Adjust column allows the developer to enter an adjustment, such as waste percentage or a numerical value, to the number developed in the Formula column. If the number is a percentage, follow the value by a % sign.
   
   Result: The Result column takes the adjusted value and displays it as the Result in the units that are specified in the Output Units column.
   
   Output Units: The Output Units specifies the units that the Results column displays in the same units listed in the Input Units column. Changing this to a different unit, such as inches, will convert the result to the selected unit. Of course, if you attempt to convert yards into cubic yards, you will get a conversion error since it is not an "apples to apples" conversion.
   
   
6. To see this in action, enter 10 in as the value of the New Length in the Formula column (red arrow #1 in Figure 1.2-26. 
   
   
7. Enter [New Length]/2 in as the value of Min Length in the Formula column (red arrow #2 in Figure 1.2-26).
   
   
8. Click on the down arrow next to the parenthesis pointed to by arrow #3 in Figure 1.2-26), and select RoundUp() (arrow #4).
   
   
   
   
   
9. The equation Min Length/Formula equation will now be displayed as RoundUp([New Length]/2). The result will appear as 5.00 in the Result column. Click on the Min Length value in the Input Units column and select FT for feet (Figure 1.2-27). Note that the OutPut Units columns in the Min Length row changes to FT as well. If you wanted to have your Output Units displayed in yards, then click in the field where Min Length and Output Units meet, and select YD. For this exercise, however, we'll keep the output set to FT. 
   
   
   
   
10. Now enter 10% in the field intersecting the Min Length row and the Adjust column to add a waste factor of 10% (Figure 1.2-28). Note that the Result now reads 5.50 since the 10% waste factor has been added. If you want a non-percentage value added, simply enter the numerical value without the percent sign.
    
    
    
    
    
11. Selecting the padlock allows you to either lock or unlock the property.
    
    
12. Clicking on the lightbulb either hides (blue) or unhides (yellow) the property.
    
    
13. Selecting the box to put a check in it will cause the property to be shown on the Form when the application is started. Note that Name, Min Length, and New Length have checks in the checkboxes. Click on Form at the bottom of the Joist Tool window.
    
    
    
    
    
14. Now note that the Name, Min Length, and New Length fields, along with their values, are displayed in this form, because the boxes for the same fields in the Advanced properties window are checked. 
    
    
15. All of these properties in PlanSwift are also available in the COM object. If you do not understand the organization and structure of these properties, then, as a developer, you'll spend more time trying to figure out what it does than if you simply know.

Object Property Model

1. 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.
   
   
   
   
   
2. 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. 
   
   
   
   
   
3. Now click on the Add Property icon as shown in Figure 1.3-3.
   
   
   
   
   
4. 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.
   
   
   
   
   
5. 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.
   
   
   
   
   
6. 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. 
   
   
   
   
   
7. 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. 
   
   
8. The other Type: field values may be useful but will not be covered at this time.
   
   
9. 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. 
   
   
10. 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.
    
    
11. 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.
    
    
    
    
    
12. 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. 
    
    
    
    
    
13. 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.
    
    
    
    
    
14. The Remember Value: checkbox has no functionality at this time.
    
    
15. 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.
    
    
16. 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.
    
    
    
    
17.  The Test Property field now appears. If you change and invoke the value to anything but 10, then the Test Property field will disappear.
    
    
    
    
    
18. Click on Advanced to return to the Joist Tool Properties window, and double-click on Test Property.  The Compiled Options are TBD.
    
    
    
    
    
19. 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.
    
    
    
    
    
20. 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.
    
    
    
    
    
21. 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.
    
    
    
    
22. This completes the coverage of what you need to know to get started using the API.