Version 2.19.0 of WordPress Libs is now available for public use. This was the biggest release we have had in a while for this library. Many features were introduced and improved, bugs were squashed, and redundancies were combined. All around improved REST and meta support.
WordPress 5.5 is required to take advantage of many of the enhancements. It’s not required but recommended to update to WP 5.5 when updating to version 2.19.0.
Option Page Enhancements
CMB2 uses a special mapping process to translate option page field to a single shared options which is stored as serialized and back again. The meta repo calls the template tags built into CMB2 to handle this translation. In version 2.19.0 we’ve enhanced this process for additional support.
Options pages which are set to show in the network admin will now function within the meta repo and values will be saved and retrieved from the correct location automatically. Nothing is required for this work, simply register your options page like normal using the `Options_Page` class and it will work.
Taxonomy type fields store the ID of a term on the main site when using network options pages. Now you may retrieve this value from any site in the network and it will automatically translate to the term on the main site.
Introduce Network_Trait
The new Network_Trait follows the same patterns as the other meta traits with the main difference being values are retrieved and stored using the network_option API.
Looking at the database structure, storing network options uses identical database tables as the other meta APIs and could function just fine using the existing site meta API the repo supports. However, upon deep investigation we realized site meta uses a different cache structure than the network option API. CRUD from the database works the same using either path, but the cache is not stored nor flushed the same so the risk of stale data is very real. After much strategy, and since there are no helper functions for interacting with the site meta path, we opted to use the network option path for this trait’s interactions.
We also opted to exclude the site_id property from this trait as it does not exist on the WP_Network class and is only accessible via a magic method. Since our object system does not support magic methods, leaving this property available would be confusing at best. Instead you may use the blog_id property which will always contain the same value as site_id.
Support __call on Mutator_Trait
Previously, you could access all properties on the child object directly via the __get magic method. Now you may access all methods on the child object directly via the __call method.
We’ve also added all WP_User methods to the php docs on the User_Trait so your IDE will automatically know they are available.
Note: Some object types support __call as well, but the Mutator_Trait system does not support an additional level of __call and will only access explicitly defined methods and properties.
Default Taxonomy Term
WordPress 5.5 added support for defining a default term for use with custom taxonomies. The Taxonomy class now supports both defining initial terms to be added to a taxonomy on register, and a default term to be assigned to any post type which supports a taxonomy and does not specify any terms.
Add initial terms using the add_initial_terms:
Add a default term using set_default_term
To reduce confusion on the difference of these two processes, we deprecated the set_default_terms and register_default_terms methods. They will continue to function for now, but you should start using the news ones as the old ones will be removed in version 3.
Add show_in_rest Meta Fields to meta Responses
Previously, if you marked a field as show_in_rest, it would automatically show up in the REST endpoints under the cmb2 key. Now the field will also show up under the standard meta key as well.
If you specify a box as show_in_rest, it will not include the fields in the meta key on its own. You must specify the field directly which you would like to show in meta. This will prevent duplicating a bunch of keys when you only need a small number.
The keys shown in meta are given simplified keys with namespaces removed as long as you are using the standard namespace/key naming convention. For instance, if your meta key is onpoint/featured-tag, a value will be available within the meta key as featured-tag. This does not apply to keys within the cmb2 key which will remain the same as they always were with the name-spaced keys.
Add show_in_rest Fields to Options Page REST Responses
Previously, if you marked a field as show_in_rest, it would automatically show up in the REST endpoints under the cmb2 key. Now fields added to an Options Page box which are marked as show_in_rest will now appear in responses from the /settings REST endpoint.
The keys will also use the simplified keys with namespaces removed and follow the same box vs field principles as the meta responses.
Default Values
WordPress 5.5 added support for registering a default value to be returned from various meta API calls. While the meta repo previously supporting defining a default value to be used in the form fields, it now supports returning the provided value from various meta API calls from within and outside the meta repo.
Options page boxes also support retrieving default values, however, since CMB2 stores the values of an options page as one big blog in a single setting, default values only work when using the meta repo or calling cmb2_options directly. Standard calls to get_option will not honor the default values (which would be confusing since update_option does not work for updating option page values).
Note: Calls from outside the meta repo will not translate the values to their CMB2 types but will instead return the raw standard value.
Support Excluding _links from Initial_Data
To make this enhancement more intuitive we changed the signature of the methods available in the Initial_Data class.
Previously, all methods in this class included a 3rd argument $embed_links which made all links in the response embed themselves the same way a standard REST response would. This $embed_links was almost never used (we actually are not aware of a single use of it).
Now all methods include the following arguments:
$items: arrayList of items.$with_links: boolInclude the_linksin responses (defaults to false).$embed: boolEmbed the links in responses (defaults to false; requires$with_links).
Be default _links will now be excluded in responses which makes for a much lighter and cleaner JavaScript configuration.
Miscellaneous
- Removed superfluous methods in
Site_Traitwhich have the same signature as our meta repo. - Fixed warning in the
auth/v1REST API for WP 5.5. - Added support for the
block_editorargument onExtended_CPTS. - Fixed spacing of check-boxes within tabs.