<commit_before># Connections

Any software system or application consists of components that must collaborate to do the really useful stuff.  Once you've [created some components](#components.md), you'll want to connect them together in various ways so that they can collaborate.

Similarly to [[factories]] used to [[create things]], wire uses plugin [[facets]] to apply new behavior to components after they have been created.  There are several facets that are used to make connections between components.  For example, you can connect a Javascript controller to DOM events on an HTML view.

Wire itself, plus its bundled plugins support 4 types of connections:

1. Dependency Injection - The simplest type of "connection".  Inject a reference to one component into another so you can call methods on it directly
1. DOM events - As you'd expect, when a DOM event happens, invoke a component's method(s) to handle it
1. Javascript to Javascript "events" - When a method is called on one component, automatically invoke a method on another component
1. Aspect Oriented Programming (AOP) advice - A more advanced form of Javascript to Javascript connection.  When a method is called on a component, invoke a method on another component before or after it.

Each of these type of connections can be useful in various situations, and picking what type of connection to use should be a part of designing your application architecture.

## Injection

**Plugins:** None needed

You may tend not to think of method calls as a type of connection between components, but it's probably the you use the most.  With wire you can inject properties into Javascript components so that they can invoke methods directly on one another:

```js
define({
	// Create a component for my application, perhaps a datastore
	datastore: {
		create: //...
	},

	// Create another component, say, a controller
	controller: {
		create: 'my/app/Controller'
		// Give the controller a reference to the datastore, by
		// simply setting a property on it.
		properties: {
			// this controller instance will be able to reference
			// the datastore via this._myDatastore, and can call
			// methods on it directly
			_myDatastore: { $ref: 'datastore' }
		}
	}
});
```

Rather than setting properties, you may need to pass dependent components to a constructor when creating a component instance.  You can supply constructor parameters using the longer form of the [[create factory|factories]] and providing an array of arguments.

For example, if the controller in the example above accepted a datastore via its constructor:

```js
define({
	// Create a component for my application, perhaps a datastore
	datastore: {
		create: //...
	},

	// Create another component, say, a controller
	controller: {
		create: {
			module: 'my/app/Controller',
			// Give the controller a reference to the datastore, by passing
			// it to the controller's constructor.
			args: [
				{ $ref: 'datastore' }
			]
		}
	}
});
```

## DOM events

**Plugins:** wire/on, wire/dojo/on (uses dojo/on), wire/jquery/on (uses jQuery.on)

*Coming Soon*

## Javascript to Javascript

**Plugin:** wire/connect, wire/dojo/events (uses dojo.connect)

These plugins allow you to make simple Javascript to Javascript connections.  You can specify that when a method on one component is called, a method on another component will also be called.  This allows any method to act as an event emitter without having to mixin an event emitter object.

```js
define({
	plugins: [
		{ module: 'wire/connect'},
	    // other plugins ...
	],

	component1: {
		create: // ...
	},

	component2: {
		create: // ...
		connect: {
			// Whenever component2's doSomething method is
			// called, component1.doSomethingAlso will also
			// be invoked, with the same parameters.
			'doSomething': 'component1.doSomethingAlso'
		}
	}
});
```

Connections can be made in either direction.  For example, the following example is equivalent to the previous:

```js
define({
	plugins: [
		{ module: 'wire/connect'},
	    // other plugins ...
	],

	component1: {
		create: // ...
		connect: {
			// Whenever component2.doSomething is called,
			// component1.doSomethingAlso will also
			// be invoked, with the same parameters.
			'component2.doSomething': 'doSomethingAlso'
		}
	},

	component2: {
		create: // ...
	}
});
```


*Coming Soon*

## Aspect Oriented Programming (AOP)

**Plugin:** wire/aop

The wire/aop plugin lets you make Javascript to Javascript connections similar to wire/connect, but provides more connection types.  For example, you can have one method called before another, after another method returns, or after another method throws an exception.

```js
define({
	// Include the wire/aop plugin
	plugins: [
	    { module: 'wire/aop' },
	    // other plugins ...<commit_msg>Make header levels match doc style<commit_after># Connections

Any software system or application consists of components that must collaborate to do the really useful stuff.  Once you've [created some components](#components.md), you'll want to connect them together in various ways so that they can collaborate.

Similarly to [[factories]] used to [[create things]], wire uses plugin [[facets]] to apply new behavior to components after they have been created.  There are several facets that are used to make connections between components.  For example, you can connect a Javascript controller to DOM events on an HTML view.

Wire itself, plus its bundled plugins support 4 types of connections:

1. Dependency Injection - The simplest type of "connection".  Inject a reference to one component into another so you can call methods on it directly
1. DOM events - As you'd expect, when a DOM event happens, invoke a component's method(s) to handle it
1. Javascript to Javascript "events" - When a method is called on one component, automatically invoke a method on another component
1. Aspect Oriented Programming (AOP) advice - A more advanced form of Javascript to Javascript connection.  When a method is called on a component, invoke a method on another component before or after it.

Each of these type of connections can be useful in various situations, and picking what type of connection to use should be a part of designing your application architecture.

# Injection

**Plugins:** None needed

You may tend not to think of method calls as a type of connection between components, but it's probably the you use the most.  With wire you can inject properties into Javascript components so that they can invoke methods directly on one another:

```js
define({
	// Create a component for my application, perhaps a datastore
	datastore: {
		create: //...
	},

	// Create another component, say, a controller
	controller: {
		create: 'my/app/Controller'
		// Give the controller a reference to the datastore, by
		// simply setting a property on it.
		properties: {
			// this controller instance will be able to reference
			// the datastore via this._myDatastore, and can call
			// methods on it directly
			_myDatastore: { $ref: 'datastore' }
		}
	}
});
```

Rather than setting properties, you may need to pass dependent components to a constructor when creating a component instance.  You can supply constructor parameters using the longer form of the [[create factory|factories]] and providing an array of arguments.

For example, if the controller in the example above accepted a datastore via its constructor:

```js
define({
	// Create a component for my application, perhaps a datastore
	datastore: {
		create: //...
	},

	// Create another component, say, a controller
	controller: {
		create: {
			module: 'my/app/Controller',
			// Give the controller a reference to the datastore, by passing
			// it to the controller's constructor.
			args: [
				{ $ref: 'datastore' }
			]
		}
	}
});
```

# DOM events

**Plugins:** wire/on, wire/dojo/on (uses dojo/on), wire/jquery/on (uses jQuery.on)

*Coming Soon*

# Javascript to Javascript

**Plugin:** wire/connect, wire/dojo/events (uses dojo.connect)

These plugins allow you to make simple Javascript to Javascript connections.  You can specify that when a method on one component is called, a method on another component will also be called.  This allows any method to act as an event emitter without having to mixin an event emitter object.

```js
define({
	plugins: [
		{ module: 'wire/connect'},
	    // other plugins ...
	],

	component1: {
		create: // ...
	},

	component2: {
		create: // ...
		connect: {
			// Whenever component2's doSomething method is
			// called, component1.doSomethingAlso will also
			// be invoked, with the same parameters.
			'doSomething': 'component1.doSomethingAlso'
		}
	}
});
```

Connections can be made in either direction.  For example, the following example is equivalent to the previous:

```js
define({
	plugins: [
		{ module: 'wire/connect'},
	    // other plugins ...
	],

	component1: {
		create: // ...
		connect: {
			// Whenever component2.doSomething is called,
			// component1.doSomethingAlso will also
			// be invoked, with the same parameters.
			'component2.doSomething': 'doSomethingAlso'
		}
	},

	component2: {
		create: // ...
	}
});
```


*Coming Soon*

# Aspect Oriented Programming (AOP)

**Plugin:** wire/aop

The wire/aop plugin lets you make Javascript to Javascript connections similar to wire/connect, but provides more connection types.  For example, you can have one method called before another, after another method returns, or after another method throws an exception.

```js
define({
	// Include the wire/aop plugin
	plugins: [
	    { module: 'wire/aop' },
	    // other plugins ...
{'fraction_non_alphanumeric': 0.08574691165784283, 'fraction_numerical': 0.003114294612270321, 'mean_word_length': 3.640655105973025, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6569533', 'n_tokens_mistral': 2750, 'n_tokens_neox': 2491, 'n_words': 1253}