# Class Join

Join table class for DataTables Editor.

The Join class can be used with Editor::join to allow Editor to obtain joined information from the database.

For an overview of how Join tables work, please refer to the Editor manual as it is useful to understand how this class represents the links between tables, before fully getting to grips with it's API.

  DataTables\Ext
  DataTables\Editor\Join

#### Direct known subclasses

DataTables\Editor\Mjoin
Namespace: DataTables\Editor
Example:

Join the parent table (the one specified in the Editor::table method) with the table access, with a link table user__access, which allows multiple properties to be found for each row in the parent table.

    Join::inst( 'access', 'array' )
             ->link( 'users.id', 'user_access.user_id' )
             ->link( 'access.id', 'user_access.access_id' )
             ->field(
                 Field::inst( 'id' )->validator( 'Validate::required' ),
                 Field::inst( 'name' )
             )

Example:

Single row join - here we join the parent table with a single row in the child table, without an intermediate link table. In this case the child table is called extra and the two fields give the columns that Editor will read from that table.

    Join::inst( 'extra', 'object' )
               ->link( 'user.id', 'extra.user_id' )
               ->field(
                   Field::inst( 'comments' ),
                   Field::inst( 'review' )
               )

Located at Editor/Join.php

Methods summary
`public` | # `__construct( string $table = null, string $type = 'object' )` Join instance constructor. Join instance constructor. #### Parameters $table Table name to get the joined data from. $type Work with a single result ('object') or an array of results ('array') for the join.
`public string|`DataTables\Editor\Join`` | # `aliasParentTable( string $_ = null )` Get / set parent table alias. Get / set parent table alias. When working with a self referencing table (i.e. a column in the table contains a primary key value from its own table) it can be useful to set an alias on the parent table's name, allowing a self referencing Join. For example: `SELECT p2.publisher FROM publisher as p2 JOIN publisher on (publisher.idPublisher = p2.idPublisher) `Where, in this case, `publisher` is the table that is used by the Editor instance, and you want to use `Join` to link back to the table (resolving a name for example). This method allows that alias to be set. Fields can then use standard SQL notation to select a field, for example `p2.publisher` or `publisher.publisher`.`` #### Parameters $_ Table alias to use #### Returns string|`DataTables\Editor\Join` Table alias set (which is null by default), or self if used as a setter.
`public `DataTables\Editor\Field[]`|`DataTables\Editor\Join`` | # `field( `DataTables\Editor\Field` $_ = null )` Get / set field instances. Get / set field instances. The list of fields designates which columns in the table that will be read from the joined table. #### Parameters $_ $_... Instances of the `DataTables\Editor\Field` class, given as a single instance of `DataTables\Editor\Field`, an array of `DataTables\Editor\Field` instances, or multiple `DataTables\Editor\Field` instance parameters for the function. #### Returns `DataTables\Editor\Field[]`|`DataTables\Editor\Join` Array of fields, or self if used as a setter. #### See `DataTables\Editor\Field` for field documentation.
`public `DataTables\Editor\Field[]`|`DataTables\Editor\Join`` | # `fields( `DataTables\Editor\Field` $_ = null )` Get / set field instances. Get / set field instances. An alias of `DataTables\Editor\Join::field()`, for convenience. #### Parameters $_ $_... Instances of the `DataTables\Editor\Field` class, given as a single instance of `DataTables\Editor\Field`, an array of `DataTables\Editor\Field` instances, or multiple `DataTables\Editor\Field` instance parameters for the function. #### Returns `DataTables\Editor\Field[]`|`DataTables\Editor\Join` Array of fields, or self if used as a setter. #### See `DataTables\Editor\Field` for field documentation.
`public boolean|`DataTables\Editor\Join`` | # `get( boolean $_ = null )` Get / set get attribute. Get / set get attribute. When set to false no read operations will occur on the join tables. #### Parameters $_ Value #### Returns boolean|`DataTables\Editor\Join` Name
`public` | # `join( string|string[] $parent = null, string|string[] $child = null, string $table = null )` Get / set join properties. Get / set join properties. Define how the SQL will be performed, on what columns. There are basically two types of join that are supported by Editor here, a direct foreign key reference in the join table to the parent table's primary key, or a link table that contains just primary keys for the parent and child tables (this approach is usually used with a `DataTables\Editor\Join::type()` of 'array' since you can often have multiple links between the two tables, while a direct foreign key reference will typically use a type of 'object' (i.e. a single entry). #### Deprecated 1.5 Please use the `DataTables\Editor\Join::link()` method rather than this method now. #### Parameters $parent Parent table's primary key names. If used with a link table (i.e. third parameter to this method is given, then an array should be used, with the first element being the pkey's name in the parent table, and the second element being the key's name in the link table. $child Child table's primary key names. If used with a link table (i.e. third parameter to this method is given, then an array should be used, with the first element being the pkey's name in the child table, and the second element being the key's name in the link table. $table Join table name, if using a link table #### Returns Join This for chaining
`public `DataTables\Editor\Join`` | # `link( string $field1, string $field2 )` Create a join link between two tables. The order of the fields does not matter, but each field must contain the table name as well as the field name. Create a join link between two tables. The order of the fields does not matter, but each field must contain the table name as well as the field name. This method can be called a maximum of two times for an Mjoin instance: First time, creates a link between the Editor host table and a join table Second time creates the links required for a link table. Please refer to the Editor Mjoin documentation for further details: https://editor.datatables.net/manual/php #### Parameters $field1 Table and field name $field2 Table and field name #### Returns `DataTables\Editor\Join` Self for chaining #### Throws Exception Link limitations
`public `DataTables\Editor\Join`` | # `order( string $_ = null )` Specify the property that the data will be sorted by. Specify the property that the data will be sorted by. #### Parameters $_ $order SQL column name to order the data by #### Returns `DataTables\Editor\Join` Self for chaining
`public String|`DataTables\Editor\Join`` | # `name( string $_ = null )` Get / set name. Get / set name. The `name` of the Join is the JSON property key that is used when 'getting' the data, and the HTTP property key (in a JSON style) when 'setting' data. Typically the name of the db table will be used here, but this method allows that to be overridden. #### Parameters $_ Field name #### Returns String|`DataTables\Editor\Join` Name
`public boolean|`DataTables\Editor\Join`` | # `set( boolean $_ = null )` Get / set set attribute. Get / set set attribute. When set to false no write operations will occur on the join tables. This can be useful when you want to display information which is joined, but want to only perform write operations on the parent table. #### Parameters $_ Value #### Returns boolean|`DataTables\Editor\Join` Name
`public String|`DataTables\Editor\Join`` | # `table( string $_ = null )` Get / set join table name. Get / set join table name. Please note that this will also set the `DataTables\Editor\Join::name()` used by the Join as well. This is for convenience as the JSON output / HTTP input will typically use the same name as the database name. If you want to set a custom name, the `DataTables\Editor\Join::name()` method must be called after this one. #### Parameters $_ Name of the table to read the join data from #### Returns String|`DataTables\Editor\Join` Name of the join table, or self if used as a setter.
`public String|`DataTables\Editor\Join`` | # `type( string $_ = null )` Get / set the join type. Get / set the join type. The join type allows the data that is returned from the join to be given as an array (i.e. working with multiple possibly results for each record from the parent table), or as an object (i.e. working which one and only one result for each record form the parent table). #### Parameters $_ Join type ('object') or an array of results ('array') for the join. #### Returns String|`DataTables\Editor\Join` Join type, or self if used as a setter.
`public `DataTables\Editor\Join`` | # `validator( string $fieldName, callable $fn )` Set a validator for the array of data (not on a field basis) Set a validator for the array of data (not on a field basis) #### Parameters $fieldName Name of the field that any error should be shown against on the client-side $fn Callback function for validation #### Returns `DataTables\Editor\Join` Chainable
`public string[]|`DataTables\Editor\Join`` | # `where( string|callable $key = null, string|string[] $value = null, string $op = '=' )` Where condition to add to the query used to get data from the database. Note that this is applied to the child table. Where condition to add to the query used to get data from the database. Note that this is applied to the child table. Can be used in two different ways: Simple case: `where( field, value, operator )` Complex: `where( fn )` #### Parameters $key Single field name or a closure function $value Single field value, or an array of values. $op Condition operator: <, >, = etc #### Returns string[]|`DataTables\Editor\Join` Where condition array, or self if used as a setter.
`public boolean` | # `whereSet( boolean $_ = null )` Get / set if the WHERE conditions should be included in the create and edit actions. Get / set if the WHERE conditions should be included in the create and edit actions. This means that the fields which have been used as part of the 'get' WHERE condition (using the `where()` method) will be set as the values given. This is default false (i.e. they are not included). #### Parameters $_ Include (`true`), or not (`false`) #### Returns boolean Current value

Methods inherited from DataTables\Ext
`_getSet(), _propExists(), _readProp(), _writeProp(), inst(), instantiate()`