This module allows you to create arbitrary many-to-many relationships (connectors) between content items (sockets). This is very much a core feature of the entire Science Project and the key to unlocking the true potential of Orchard!

Sockets and Connectors

This is the underlying paradigm of the Mechanics system. Your content items have Sockets, and you use Connectors to plug one item into another. If you've used Orchard's built-in system of lists, this is not the same comparison. Whereas Container->Containable is a parent-child relationship, in Mechanics we have a distributed (i.e. non-directional) network of relationships. Regular content items are considered Sockets, and you additionally have to define an intermediary Connector item. The relationship goes Socket->Connector->Socket (and optionally the inverse Socket<-Connector<-Socket). Instead of parent/child we use the terms left/right to describe the two items on each end of the relationship.
There are two parts of significance in building relationships: SocketsPart and ConnectorPart.


This is the part you will add to all your normal content items. It allows an item to participate in relationships. In fact, an item can be connected without a SocketsPart; the part is simply used to allow us to render the connections and UI when displaying or editing a particular item.


This is the part you will add to your intermediary connector item. This is really important to grasp. The Socket items are never connecting directly to each other, there is always a third content item that represents the connector itself. This is the item that will have the ConnectorPart. This is best demonstrated by the following example.


Let us say we have our content type "Product" and a content type "Category". Product contains title, description, price and other details of a product. Category is simply a title and a description.
We want a product to have the ability to appear in any number of categories. When we display a category we want it to list all products that it contains. Conversely, when we display a product we want to see a list of all the categories it appears in.
  1. First, we attach the SocketsPart to both Product and Category. This allows them to both display and edit their connected content. But at this stage, there is no way for them to connect because we haven't created a connector.
  2. Second, we create two entirely new content types. These are called "CategoryToProduct" and "ProductToCategory". So we have separate items describing the two different directions of our relationship. It's possible to do this without creating both connectors; in fact there are a number of ways to create any given scenario. But this is the most recommended way as it gives you maximum flexibility.
  3. Third, we attach the ConnectorPart on both CategoryToProduct and ProductToCategory. ConnectorPart has a number of settings, so we can limit the left and right ends of the connectors to Category and Product content types. You will also want to set "Inverse Connector" so the types of connections know they are the inverse of each other (i.e. CategoryToProduct is the inverse of ProductToCategory, and vice versa). There is also an Allow Many option - you could untick this for ProductToCategory if you only want products to appear in a single category.
  4. Fourth, create a Category. Then create a Product. You will now see an option to select your Category. Additionally when you create a Category you will get a list of products to add to it. Because you've created both directions of the relationship, you can edit the relationship from both ends. When you view a category, you'll get a list of products (in Summary view).
This example is incomplete in a number of ways for a full production products/categories website, but the Economics Theory sample project will demonstrate a more complete picture of this scenario.

Also see

Jump to overview

Last edited May 26, 2011 at 1:34 PM by randompete, version 10


rpter Jun 26, 2013 at 12:11 PM 
Doesn't seem to play nice with Orchard 1.6.1 - is the Science Project still running or has development ceased?

PlanetTelexInc Jan 6, 2012 at 6:09 PM 
This is exactly what Orchard needs to unlock the true potential of custom data types. The ability to build those through the UI is one of the key features that make Orchard one of our new favorites. But that ability is totally limited until you can arbitrarily relate content items. This module totally fixes this problem- and it worked perfectly right out of the box too. Thanks a bunch for writing this guys!

justSteve Jul 10, 2011 at 6:26 PM 
just the sort of capability I need. Is this in the wild yet?