How to create your own custom jackfield tools

What the jackfield and term panel tools do are to place a symbol instance on the drawing and convert it to a group in the class Sys-Devices thus making it a connectCAD device. Then the tool updates the naming of the jackfield device and it’s sockets according to the data entered in the dialog.

It’s exactly the same code for all jackfields and term panels the only differences are in the parameters and these are all customisable. That’s how we do audio, video, optical and data jacks without writing a different plug-in for each one. So here’s the in-depth guide to how these tools are set up.

Open the Vectorworks Plug-in Manager

Open_the_Vectorworks_Plug-in_Manager.png

and now we’ll take a behind-the-scenes look at how these plug-ins work…
Avoid experimenting on the standard connectCAD tools – it’s better to duplicate one of ours, rename it, add it to your workspace and do your tests on that.

Let’s look at the Data Jack tool

Let_s_look_at_the_Data_Jack_tool.png

First select Data Jack in the Plug-in Manager list, then click Edit Definition to view the various settings

Now choose the Parameters tab

Now_choose_the_Parameters_tab.png

These are the default values for the tool parameters that you can access from the “spanner” icon top-left of the drawing area when the tool is selected. Tool settings are stored in the document and in templates so you can easily pick up where you left off when you re-open a document.

Jackfield tools have 5 parameters that control things like the number of patch points on a jackfield, the labelling style to use and the structure of the labels e.g. the range of characters used for IDs and the delimiter character (if any) that separates them. This is all explained in the user guide pages.

Moving on to the Strings tab

Moving_on_to_the_Strings_tab.png

These text strings control various aspects of the jack device to be created that aren’t in the dialog. e.g.

5000 device name prefix i.e. data jackfields names begin with DJF
5001 input socket symbol name
5002 output socket symbol name
5003 device label symbol name
5004 default signal type (normally left blank since jackfields are passive devices)
5005 connector type

 

 

Where are the device symbols specified?

Where_are_the_device_symbols_specified.png

The “jack symbols” string group tell the tool which symbol to place on the drawing depending on the labelling style. So in this case –

label style symbol name

‘AB,CD…’ DataJack
‘A,B,C…’ DataJack2
’01[delim]01′ DataJack

and where are these symbols stored?

Further on down the rabbit-hole !!!

Further_on_down_the_rabbit-hole____.png

Enter the Vectorworks Resource Manager, select your current connectCAD document and located the system_symbols symbol folder.

On the surface connectCAD hides a lot of complexity from you but we always make sure that as much as possible is accessible to you should you need it. You have the keys to the castle but it’s a got a lot of winding corridors… so let’s go find these symbols.

the DataJack symbol itself

the_DataJack_symbol_itself.png

now right-click and choose Edit 3D Component. Why 3D? because all connectCAD graphics uses 2D planar graphics so you can rotate your drawing in 3D space if you want a funky look.

the DataJack symbol

the_DataJack_symbol.png

a normal device symbol like the ones you save using Make Device. And completely customisable.

How to use this know-how

remember Duplicate – Rename – Modify

We always suggest experimenting on renamed duplicates of our standard symbols. It makes the way back much easier if things go wrong 😉

 

Connect tool – new version

In connectCAD 2017 version 2 we’ve introduced our new Connect tool – a faster, smoother, more intuitive alternative to our current tool. A small taste of connectCAD 2018. Here we’ll explain how to add this to your workspace and how to use it.

Add the tool to your workspace

Add_the_tool_to_your_workspace.png

Open your workspace in the Workspace Editor ( go to the Tools > Workspaces > Edit Current Workspace menu ).

  1. Select the Tools tab in the dialog.
  2. Locate and open the connectCAD_SDK category.
  3. drag the Connect tool into your tool palette

We suggest not to remove the old Connect tool just yet. It is still useful when you need to connect to a Link.

Using Connect

Using_Connect.png

Connect follows Vectorworks rules:

  1. Select the tool
  2. Select the mode
  3. Click on a socket to begin
  4. Click to add corners
  5. Click on a socket to complete

Backspace undoes the last click, Escape exits the tool. You can pan during tool operation by pressing the Space Bar, and zoom in and out using Cmd-1 and Cmd-2 (Ctrl on Windows). All standard Vectorworks shortcuts.

Modes

Modes.png

Connect supports all 3 circuit styles:

  • Corner
  • Rounded
  • Arrow

Just click on the mode bar icon to choose the style you want. Vectorworks assigns the key u as a keyboard shortcut to cycle through modes but you can change this if you want In the Workspace Editor. It’s no problem to change modes while you’re creating a circuit.

Connection hints

Connection_hints.png

As you hover over a socket the Device and Socket names are displayed in the mode bar. This saves you zooming in and out all the time to see where you are going.

Layer-to-Layer connections

Layer-to-Layer_connections.png

In arrow mode you can connect to other layers. The process is simple. Just begin your connection on one layer and use the Cmd-Up/Down arrows to cycle through the layers. Click on your destination socket and you are done!

Links?

The answer here is “not yet”. If you need to connect to another document please use the old Connect tool.
We will be reviewing the entire way in which Links work for connectCAD 2018 and we would like your input.

We hope you find our new Connect tool useful and we’d be happy to hear from you.

Online Device Sharing

Nobody likes filling in forms, particularly a humungous one like Device Builder with all its mind-boggling details. But we designers have to spend a part of our lives reading spec sheets and doing data entry – no getting away from that. However, what we can do is share the work between us. And that’s what we’re doing in connectCAD 2017. As you create devices in Device Builder the spec of the device gets uploaded to our online repository. So if that device is already in the database you can retrieve the details ready to go. Let’s see how that works.

Find your device online

Find_your_device_online.png

Just two quick steps:

  1. Enter the Make and Model
  2. Click Find Online

And by magic…

And_by_magic.png

All the device details are retrieved from the database.

So all you have to do now is review the form to make sure it’s accurate and give the device a name. Press OK and you’re done.

So who looks after this database?

So_who_looks_after_this_database.png

You do!

If the device is not in our online database the check box next to the Find Online button will read “Upload this device”. It’s checked by default so please leave it checked unless this is some temporary device you’re making. That way each time you create a new device the database will get bigger and better.

We want to stress that this is a community-run database. The accuracy of it depends on you. So before you upload please make sure that the information is correct the way you would like to receive it. ConnectCAD Limited does guarantee that device specs are always correct and does not take responsibility for this ( necessary note from our lawyer – sorry! ). But we are sure that as designers we’ll all do the right thing and upload good stuff.

What if a spec is incorrect?

What_if_a_spec_is_incorrect.png

If you find an error, just check the box “Update online device” and when you click OK your changes will be uploaded.

It’s great but…

Yes we know! This is just the beginning.

You’d like to be able to:

  • browse the online database,
  • have Make and Model auto-complete,
  • rate the accuracy of specs,
  • leave comments
  • have more than 10 groups of sockets
  • upload existing device specs

connectCAD 2017 is different from previous years. We’ll be bringing out lot’s of new features as the year goes on. The cool thing about Device Sharing is the backend. We’ve implemented what’s called a REST API for the database and that means we can easily integrate it into the support website and also provide extra facilities in Device Builder and other parts of connectCAD.

So please contribute your devices as you make them. Uploading only takes a few seconds and if we all do it we’ll save hours of form-filling.

Understanding database worksheets

connectCAD makes a lot of use of Vectorworks worksheets for reporting so it’s useful to review some the concepts. Here we’ll use the Rack Equipment Report from the standard template.

Locate the worksheet in the Resource Browser

Locate_the_worksheet_in_the_Resource_Browser.png

Right-click on it and select Open so we can edit the worksheet.

Show Database Headers

Show_Database_Headers.png

That in the worksheet’s View menu.

Inspect the database row criteria

Inspect_the_database_row_criteria.png

Right-click the row number and pick Edit Criteria from the pop-up menu

media_1461890226254.png

So this database row will list all EquipItem objects. i.e. a dtabase sub-row will be created for each object that has an EquipItem record attached. Now let’s see how we display their characterisitics.

Listing equipment names

Listing_equipment_names.png

If we click on cell A2 we can see its contents ” =(‘EquipItem’.’name’) “. What that means is that the sub-rows show the values of the ‘name’ field in the ‘EquipItem’ record attached to each listed object.

So now armed with this knowledge you can go and add extra columns to show other parameter values. Give it a try.

The next level

The_next_level.png

If you are looking to display values that come from other objects referenced by the object in the list, then you will need to use Python script. For database experts that’s called a JOIN and unfortunately the VW database can’t do that (yet). But we have an example for you in the All Layers Cable Report.

in the Length column we enter a value calculated by a Python script ‘WScCADGetCableLength.py’. It’s a file located in the Plug-ins/connectCAD folder. You’ll find some useful functions in there for intereacting with connectCAD objects. Try stuff and by all means contact us if you have questions.

Changing the User Folder

Vectorworks allows you to change the User Folder which can be useful. Here’s what you need to do to get connectCAD running again.

Setting the User Folder

Setting_the_User_Folder.png

This is the default User Data and Preferences Folder on Mac OS. If you want to change this just click Choose and select the new folder location. Vectorworks will ask you if you want to copy your data across to the new folder. This is a good idea since it gives you a starting point.

Now re-activate connectCAD

Now_re-activate_connectCAD.png

If you do move your User Folder then you also need to re-activate connectCAD online. So before you move your User Folder make sure you have internet access and have your connectCAD serial number handy.

How to customise Device labels

connectCAD 2015 and onwards: we’ve made some changes to the way Device labels are implemented in 2015 so the way you customise these has also changed. Here’s the low-down on how the new Device object draws what you see on the screen.

The Device object

The_Device_object.png

In connectCAD 2015 device labels are parametric objects. What that means is you can select them and all their data is displayed in the Object Info Palette ready for you to inspect and update. The object draws what you enter in the OIP on the screen by placing a symbol and inserting the data from the Device parameters. That gives you full control of the look of the object while keeping the convenience of editing thru the OIP.

The key parameter is Symbol: this tells Device which symbol to use for its graphics. Let’s see that in more detail.

The Symbol choice list and how to change it

The_Symbol_choice_list_and_how_to_change_it.png

The symbol choice list is accessed thru the Vectorworks Plug-in Manager;

  1. Go to the Tools / Scripts / Plug-in Manager command.
  2. Select the Device plug-in
  3. Click Edit Definition
  4. Choose the Parameters tab
  5. select the ‘symbol’ parameter
  6. Click Edit…
  7. Click the Choices button in the Edit Parameter dialog
  8. Add extra lines to the choice list. e.g. ‘my_dev_symbol’

 

And here’s that extra symbol choice

And_here_s_that_extra_symbol_choice.png

Where are these symbols located

Where_are_these_symbols_located.png

All the symbols connectCAD uses internally can be located in the Vectorworks Resource Browser in the ‘system_symbols’ folder of the current document. Here is dev_label_generic.

Duplicate and rename the symbol to ‘my_dev_symbol’

Duplicate_and_rename_the_symbol_to__my_dev_symbol_.png

Right-click on the ‘dev_label_generic’ symbol and select Duplicate. Enter the new name you created in the choice list.

Now edit the symbol to customise the look

Now_edit_the_symbol_to_customise_the_look.png

Here I’ve added a rectangle fill graphic behind the Device tag text. You can do almost anything here, but for now let’s just see the result.

Click Exit Symbol to commit the change.

New look Devices

New_look_Devices.png

Now with the Symbol set to ‘my_dev_symbol’ we get a new look for our devices.

If you want to add extra fields to your devices and display them check out our how-to article called ‘Cuctom Device fields’

Custom Device fields

Many people need to add extra fields to device records either to store metadata or to integrate with their existing business systems. Here’s how to do that and how to display this information on the drawing if you need to.

Open the Vectorworks Plug-in Manager

Open_the_Vectorworks_Plug-in_Manager.png

Select Device and click Edit Definition

Select_Device_and_click_Edit_Definition.png

In your case you will find Device under the Third-party Plug-ins tab. Here it’s in Custom Plug-ins because I’m the developer 🙂

Go to the parameters tab and click the New… button

Go_to_the_parameters_tab_and_click_the_New..._button.png

Set up your new parameter

Set_up_your_new_parameter.png
  1. Give it a name. I recommend keeping this to a single word without spaces or special characters.
  2. You can also optionally set a more friendly display name that will be shown in the Object Info Palette
  3. Choose the parameter type. We support Text, Radio Buttons, and Pop-up. Pop-up is particularly useful where you have a specific chioce of valid input.
  4. Set the default value – can be empty if you like.

Exit all dialogs with OK and close the Plug-in Manager.

Now let’s see what we’ve done.

Enter a device group and select the tag

Enter_a_device_group_and_select_the_tag.png

Now every device will have a field called ‘IPaddress’. This gets displayed is all related dialogs, So if you click on a device with the Edit tool you’ll see the new field in the dialog. If you do Make Device List, ‘IPaddress’ appears as one of your choices.

So far so good, but how do we see this on the drawing?

Visualising user device fields

What we would like to see is this. But how do we get there?

Locate the ‘dev_rec’ record format in the Resource Browser

Locate_the__dev_rec__record_format_in_the_Resource_Browse.png

Right-click and select Edit…

Add a new field called ‘IPaddress’ to dev_rec

Add_a_new_field_called__IPaddress__to_dev_rec.png

Click the New… button to open the Field dialog.

Give the field exactly the same name as your Device parameter – in this case IPaddress

The fields type should be Text – we don’t support numeric fields. If you need numbers type them in as text.

Exit dialogs with OK.

Locate the symbol ‘dev_label_generic’ in the Resource Browser

Locate_the_symbol__dev_label_generic__in_the_Resource_Bro.png

This is the symbol used to create device label graphics and text. It’s located in the ‘system_symbols’ folder of your document.

Right click on it and select Edit 2D Component.

Select All to see what’s there

Select_All_to_see_what_s_there.png

The reason for this is that some items don’t have default text so you can’t see them if they aren’t selected. In the next step you’ll add your own text item for the IP address and you don’t want it to be over the rack location for example.

Create a text item in the symbol

Create_a_text_item_in_the_symbol.png

Change fonts, size, colours etc. to match your particular style.

Go to the Modify / Link Text to Record menu command

Go_to_the_Modify__Link_Text_to_Record_menu_command.png

With the text item you just created selected – do the Modify / Link Text to Record menu command. In the dialog select the Format ‘dev_rec’ and the Field ‘IPaddress’.

Click OK.

Text is now linked to the value of ‘IPaddress’

Text_is_now_linked_to_the_value_of__IPaddress_.png

It disappears because the default value of this for the symbol definition is empty. Not to worry 🙂

Click Exit Symbol to commit the changes.

Now use the Edit tool to modify one of our devices

Now_use_the_Edit_tool_to_modify_one_of_our_devices.png

The IPaddress field is displayed and I’ve just changed the value. Click OK and…

Ta-dah !!!

Ta-dah____.png

There it is.

One last cool thing

One_last_cool_thing.png

I said that user fields appear in the dialogs. Check this out…

Make a device list.

Update Device data direct from the list

Update_Device_data_direct_from_the_list.png

Type you data into the spreadsheet – it updates the drawing right away.

Now that’s useful 🙂

How to make any device insertable into circuits

One of the unique features of connectCAD is the way you can insert any jackfield or connector panel or DA device directly into a circuit. But what a lot of people don’t know is that you can also use Insert Device to place any device in a circuit. But you have to set up the device symbol in the right way so that Insert Device “knows” which sockets to use as the input and output for insertion. Here’s how to do that.

What makes a device insertable?

What_makes_a_device_insertable.png

We always insert into horizontal portions of circuits running left-to-right. So an insertable device needs to have a primary input and a primary output horizontally to the right of it. That way Insert Device can break the circuit and connect the “cut ends” to the correct sockets.

It doesn’t matter if there are other sockets in the device provided the primary sockets are correctly aligned.

How does Insert Device identify the primary sockets

How_does_Insert_Device_identify_the_primary_sockets.png

Let’s take a look inside the device symbol definition ( locate the symbol in the Resource Browser, right-click and select Edit 3D Component ). Two important things to note here:

  1. the primary input is always located at the symbol origin
  2. the primary output is always horizontally to the right of the input.

 

Making an existing device symbol insertable

Making_an_existing_device_symbol_insertable.png

When you first create a device symbol using Make Device or Edit, the symbol insertion point (symbol origin) will be put at a location set by connectCAD. This is designed to make the device non-insertable by default. Now having structured your device with the primary sockets opposite each other, you need to identify the primary input. We do this by moving the device so that the primary input is located at the symbol origin.

Let’s try that

Let_s_try_that.png

Using the Insert Device tool, we click on the circuit, then pick our TEST_SWITCH device from the symbol dropdown. Click OK and…

There it is

There_it_is.png

You first custom insertable device !!!

Now what could you do with that …. ?

Cable numbers on arrows overwrite socket text

If you use long cable numbers you can sometimes see a problem with arrow-style circuits where the cable number overwrites the socket text. Here’s how to deal with that.

The problem

The_problem.png

Well that doesn’t look very nice…

Select the arrow circuit and drag it out a bit

Select_the_arrow_circuit_and_drag_it_out_a_bit1.png

You can move the arrow end by dragging the blue handle shown. The number follows to the end of the arrow. Do the same for the reverse arrow too.

That’s better!

That_s_better_.png

The reason cable numbers work this way with arrow circuits is to avoid cable number clashes when you have one output feeding two different inputs i.e. a split. Or where a cable loops in and out of an IO socket e.g ring intercom systems.

How to download connectCAD

Just in case you are re-installing on a new computer, here’s how to download connectCAD from our site.

Visit connectcad.com

Visit_connectcad.png

Click the Log in button

Enter your username and password

Enter_your_username_and_password.png

Your username is usually your email (unless you changed it). Your password is something you should remember. If you need a password reset click Forgot Password and a new one will be mailed to you.

Click the My Account dropdown and select My Orders

Click_the_My_Account_dropdown_and_select_My_Orders.png

Your entire order history is displayed

Your_entire_order_history_is_displayed.png

Click on the order you want to open – usually the most recent confirmed order.

Here is the download link and the serial number

Here_is_the_download_link_and_the_serial_number.png
  1. download link for connectCAD
  2. your serial number
  3. download link for User Guide

For installation instructions see section 3.1 of the User Guide.