Custom Taxonomies

Introduction

Like WordPress Posts, Connections Entries can have taxonomies such as Categories attached to them. The cn_register_taxonomy() function allows you to register new custom taxonomies that can be attached to Connections Entries.

This function automatically adds support for exporting and importing the custom taxonomy terms via the CSV Import addon, registers a Content Block to display the custom taxonomy terms attached to an Entry, and registers a Widget that can be added to the theme’s sidebar to display the custom taxonomy terms attached to an Entry.

If you are familiar with adding custom taxonomies to WordPress Posts using the register_taxonomy() function, this function has been modeled after it to provide you with familiarity and ease of use.

Functions

Registers a custom taxonomy.

cn_register_taxonomy( string $taxonomy, array $args = array() )

Parameters

• $taxonomy (string) (required) The taxonomy slug, must not exceed 32 characters.
• $args (array) (optional) The taxonomy parameters.
  • labels (array) An array of labels for the taxonomy. By default, Tag labels are used for non-hierarchical taxonomies, and Category labels are used for hierarchical taxonomies.
    • name (string) The taxonomy name, in the plural.
      • Default: Categories or Tags
    • singular_name (string) The taxonomy name, in the singular.
      • Default: Category or Tag
    • menu_name (string) The taxonomy name that is displayed in the admin sidebar menu.
      • Default: Categories or Tags
    • search_items (string) The search items text.
      • Default: Search Categories or Search Tags
    • all_items (string) The all items text.
      • Default: All Categories or All Tags
    • select_items (string) The select all items text.
      • Default: Select Categories or Select Tags
    • parent_item (string) The parent items text. This text is not used on non-hierarchical taxonomies.
      • Default: Parent Category when the taxonomy is hierarchical.
    • parent_item_colon (string) The same as parent_item, but with a colon.
      • Default: Parent Category:
    • name_field_description (string) The description label displayed under the name field.
      • Default: The name is how it appears on your site.
    • slug_field_description (string) The description label displayed under the slug field.
      • Default: The “slug” is the URL-friendly version of the name. It is usually all lowercase and contains only letters, numbers, and hyphens.
    • parent_field_description (string) The description label displayed under the parent field.
      • Default: Assign a parent term to create a hierarchy. The term Jazz, for example, would be the parent of Bebop and Big Band.
    • desc_field_description (string) The description label displayed under the description field.
      • Default: The description is not prominent by default; however, some themes may show it.
    • edit_item (string) The edit item text.
      • Default: Edit Category or Edit Tag
    • view_item (string) The view item text.
      • Default: View Category or View Tag
    • update_item (string) The update item text.
      • Default: Update Category or Update Tag
    • add_new_item (string) The add new item text.
      • Default: Add New Category or Add New Tag
    • new_item_name (string) The new item name text.
      • Default: New Category Name or New Tag Name
    • not_found (string)
      • Default: No categories found. or No tags found.
    • no_terms (string)
      • Default: No categories or No tags
    • items_list_navigation (string)
      • Default: Categories list navigation or Tags list navigation
    • items_list (string)
      • Default: Categories list or Tags list
    • back_to_items (string) The text displayed after a taxonomy term has been updated as a link back to the term admin management page.
    • content_block_option_name (string) The text displayed on the Settings admin page for the Content Block settings option name.
    • content_block_heading (string) The text displayed as a heading above the taxonomy terms attached to the directory entry.
    • content_block_label (string) The text display before the taxonomy terms attached to the directory entry.
    • content_block_label_colon (string) The same as content_block_label, but with a colon.
    • widget_name (string) The name of the widget displayed on the Widgets admin settings page.
    • widget_description (string) The widget description displayed on the Widgets admin settings page.
• description (string) Descriptive summary of what the taxonomy is for.
• public (bool) Whether a taxonomy is intended for use publicly either via the admin interface or by front-end users. The default settings of publicly_queryable and show_ui are inherited from public.
  • Default: true
• publicly_queryable (bool) Whether the taxonomy is publicly queryable. If not set, the default is inherited from public.
• hierarchical (bool) Whether the taxonomy is hierarchical.
  • Default: false.
• show_ui (bool) Whether to generate and allow a UI for managing terms in this taxonomy in the admin. If not set, the default is inherited from public.
• show_in_menu (bool) Whether to show the taxonomy in the admin menu. If true, the taxonomy is shown as a submenu. If false, no menu is shown. show_ui must be true. If not set, default is inherited from show_ui.
• register_content_block (bool) Whether or not to register a Content Block that will display a list of attached taxonomy terms. If not set, the default is inherited from public.
  • Default: true
• register_widget (bool) Whether or not to register a widget that will display a list of attached taxonomy terms. If not set, the default is inherited from public.
  • Default: true
• content_block_props (array) These parameters are optional and will be set automatically if the register_content_block parameter is set to true. By default, Tag labels are used for non-hierarchical taxonomies, and Category labels are used for hierarchical taxonomies.
  • name (string) The Content Block option name displayed on the Settings admin page.
  • register_option (bool) Whether or not to register the option with the Settings API. Must be set to true in order to allow the Content Block to be shown on the Settings admin page.
  • heading (string) The heading to display above the taxonomy terms list.
• content_block_render_props (array) The properties that are to be passed to the taxonomy terms Content Block.
  • container_tag (string) The HTML tag to be used for the Content Block container.
    • Default: div
  • label_tag (string) The HTML tag to be used for the taxonomy term label element.
    • Default: span
  • item_tag (string) The HTML tag to be used for the taxonomy term element.
    • Default: span
  • type (string) The display type to be used to display the taxonomy terms.
    • Accepts: block or list
    • Default: block
  • list (string) If the type is a list, which type?
    • Accepts: ordered or unordered
    • Default: unordered
  • label (string) The label to be displayed before the taxonomy terms.
    • Default: Categories:
  • separator (string) The taxonomy term separator used when separating taxonomy terms when type is list.
    • Default: ‘, ‘
  • parent_separator (string) The separator to be used when displaying the taxonomy term’s hierarchy.
    • Default: ‘ » ‘
  • link (bool) Whether or not render the taxonomy terms as permalinks.
    • Default: false
  • parents (bool) Whether or not to display the taxonomy term hierarchy.
    • Default: false
  • child_of (int) The taxonomy term ID to retrieve child terms of.
    • Default: 0
• meta_box_cb (callable) Provide a callback for the admin metabox display. If no callback is defined the default taxonomy term metabox will be utilized.
• meta_box_sanitize_cb (callable) Callback for sanitizing taxonomy data saved from a metabox. If no callback is defined, default sanitization will be applied based the taxonomy is hierarchical or not.
• capabilities (array)
  • manage_terms (string)
    • Default: connections_manage_{$this->name}
      The variable part of the name is the taxonomy slug.
  • edit_terms (string)
    • Default: connections_edit_{$this->name}
      The variable part of the name is the taxonomy slug.
  • delete_terms (string)
    • Default: connections_delete_{$this->name}
      The variable part of the name is the taxonomy slug.
  • assign_terms (string)
    • Default: connections_assign_{$this->name}
      The variable part of the name is the taxonomy slug.
• rewrite (true|array) Registers rewrites for the taxonomy. To prevent rewrite rules from being registered, set to false.
  • Default: true
  • Accepted array parameters:
    • hierarchical (bool) Default: false
    • slug (string) Default: $taxonomy slug.
• query_var (string|bool) Define the query variable key for the taxonomy.
  • Default: $taxonomy slug
• update_count_callback (callable) Not yet implemented.
• show_in_rest (bool) Not yet implemented.
• rest_base (string) Not yet implemented.
• rest_controller_class (string) Not yet implemented.
• default_term (array|string) The default term to use for the taxonomy.
  • name (string) The term name.
  • slug (string) The term slug.
  • description (string) The term description.
• sort (bool) Not yet implemented.
• _builtin (bool) Internal property, do not use or the sky will fall.

Example

Register a “Disciplines” hierarchical taxonomy.

add_action(
	'Connections_Directory/Taxonomy/Init',
	static function() {

		cn_register_taxonomy(
			'discipline',
			array(
				'hierarchical'               => true,
				'query_var'                  => 'cn-discipline',
				'rewrite'                    => array( 'slug' => 'cn-discipline' ),
				'public'                     => true,
				'show_ui'                    => true,
				'content_block_render_props' => array(
					'type'  => 'list',
					'label' => '',
				),
				'labels'                     => array(
					'name'                       => 'Disciplines',
					'singular_name'              => 'Discipline',
					'search_items'               => 'Search Disciplines',
					'all_items'                  => 'All Disciplines',
					'select_items'               => 'Select Disciplines',
					'parent_item'                => 'Parent Discipline',
					'parent_item_colon'          => 'Parent Discipline:',
					'edit_item'                  => 'Edit Discipline',
					'view_item'                  => 'View Discipline',
					'update_item'                => 'Update Discipline',
					'add_new_item'               => 'Add New Discipline',
					'new_item_name'              => 'New Discipline Name',
					'not_found'                  => 'No disciplines found.',
					'no_terms'                   => 'No disciplines',
					'items_list_navigation'      => 'Disciplines list navigation',
					'items_list'                 => 'Disciplines list',
					'back_to_items'              => '← Go to Disciplines',
					'content_block_option_name'  => 'Disciplines',
					'content_block_heading'      => 'Disciplines',
					'content_block_label'        => 'Disciplines',
					'content_block_label_colon'  => 'Disciplines:',
					'widget_name'                => 'Entry Disciplines',
					'widget_description'         => 'Entry Disciplines',
				),
			)
		);
	}
);

Hooks

Actions

• Connections_Directory/Taxonomy/Init Custom Taxonomies should be registered on this action hook.
• Connections_Directory/Taxonomy/Registry/Registered
• Connections_Directory/Taxonomy/Registry/Unregistered

Widget

• Connections_Directory/Taxonomy/Widget/Form/Before
• Connections_Directory/Taxonomy/Widget/Form/After
• Connections_Directory/Taxonomy/Widget/Before
• Connections_Directory/Taxonomy/Widget/After

Filters

• Connections_Directory/Taxonomy/Set_Properties
• Connections_Directory/Taxonomy/Labels/{$taxonomy->name}
• Connections_Directory/Taxonomy/Register/Content_Block/ID
• Connections_Directory/Taxonomy/Register/Widget/ID

Widget

• Connections_Directory/Taxonomy/Widget/Default_Options
• Connections_Directory/Taxonomy/Widget/Form/Instance
• Connections_Directory/Taxonomy/Widget/Update
• Connections_Directory/Taxonomy/Widget/Instance
• Connections_Directory/Taxonomy/Widget/Block