Datastores

Intro

Datastores are the link between containers, fields and the database. You can read more about the mechanism in the Class structure and logic article, which summarizes how the classes in Ultimate Fields interact with each-other, but the summary is included in this article.

Default datastores

Datastores are objects, which load and save values from and to the database. Each location uses a different datastore:

Datastore	Location
Top-level datastores
Ultimate_Fields\Datastore\Comment_Meta	Comment
Ultimate_Fields\Datastore\Network_Options	Options (network options)
Ultimate_Fields\Datastore\Options	Options (page) and Customizer
Ultimate_Fields\Datastore\Post_Meta	Post Type, Attachment and Menu Item
Ultimate_Fields\Datastore\Shortcode	Shortcode
Ultimate_Fields\Datastore\Term_Meta	Taxonomy
Ultimate_Fields\Datastore\User_Meta	User
Ultimate_Fields\Datastore\Widget	Widget
Sub-field datastores
Ultimate_Fields\Datastore\Complex	Complex fields
Ultimate_Fields\Datastore\Group	The Repeater and Layout fields

Both during the loading and saving processes of containers, datastores are generated by locations upon a controller's request and associated with containers.

Loading	Saving	Description
Yes	Yes	1. The Ultimate_Fields\Controller\Post_Type class receives a post, which is being edited or saved.
Yes	Yes	2. The controller forwards the post to the first location in each container-locations combination. The location creates and returns a Ultimate_Fields\Datastore\Post_Meta datastore, which has already been associated with the post.
Yes	Yes	3. The controller forwards each datastore to the container, whose location created it. Internally, the container forwards it to each of its fields.
Yes	No	4. The controller instructs the containers to load all data, needed for editing the post. During this process, each field accesses directly the datastore, which it is associated with.
No	Yes	5. The controller uses the data from JavaScript and relays it to every active container and field. During this process fields dump their values into the datastore, while validating them.
No	Yes	6. Once all data has been validated, the controller instructs all datastores to save their values in the database. This ensures that if there are validation issues even just in a single field, no data will be actually committed.

Using non-default datastores

During both saving and loading, datastores are generated by individual locations in the beginning of the process.

In specific scenarios, you can mix and match datastores and locations if you prefer to. The following example will generate an options page in the admin, but will save the data from that options page as meta data of the currently logged in user. This works because instead of generating a custom datastore, we will create a datastore manually and use the overwrite_datastore method of the location in order to force it to use that datastore instead of creating a new one.

if( is_user_logged_in() ) {
	$datastore = new Ultimate_Fields\Datastore\User_Meta;
	$datastore->set_id( get_current_user_id() );

	$location = new Ultimate_Fields\Location\Options;
	$location->overwrite_datastore( $datastore );

	$field = Ultimate_Fields\Field::create( 'select', 'my_color_scheme' )
		->add_options(array(
			'light'	=> 'Light',
			'dark'  => 'Dark'
		));

	Ultimate_Fields\Container::create( 'Color Scheme' )
		->add_location( $location )
		->add_field( $field );
}

Scenarios like this highlight the flexibility of the class structure of the plugin.