diff --git a/source/_images/educator_how_tos/taxonomy_add_root_tag_button.png b/source/_images/educator_how_tos/taxonomy_add_root_tag_button.png new file mode 100644 index 000000000..7014cb26f Binary files /dev/null and b/source/_images/educator_how_tos/taxonomy_add_root_tag_button.png differ diff --git a/source/_images/educator_how_tos/taxonomy_add_root_tag_input.png b/source/_images/educator_how_tos/taxonomy_add_root_tag_input.png new file mode 100644 index 000000000..399db626d Binary files /dev/null and b/source/_images/educator_how_tos/taxonomy_add_root_tag_input.png differ diff --git a/source/_images/educator_how_tos/taxonomy_add_sub_tag_input.png b/source/_images/educator_how_tos/taxonomy_add_sub_tag_input.png new file mode 100644 index 000000000..6d9918345 Binary files /dev/null and b/source/_images/educator_how_tos/taxonomy_add_sub_tag_input.png differ diff --git a/source/_images/educator_how_tos/taxonomy_add_sub_tag_menu.png b/source/_images/educator_how_tos/taxonomy_add_sub_tag_menu.png new file mode 100644 index 000000000..f3ae9a67b Binary files /dev/null and b/source/_images/educator_how_tos/taxonomy_add_sub_tag_menu.png differ diff --git a/source/_images/educator_how_tos/taxonomy_cancel_tag.png b/source/_images/educator_how_tos/taxonomy_cancel_tag.png new file mode 100644 index 000000000..fb1008ffa Binary files /dev/null and b/source/_images/educator_how_tos/taxonomy_cancel_tag.png differ diff --git a/source/_images/educator_how_tos/taxonomy_delete_tag_menu.png b/source/_images/educator_how_tos/taxonomy_delete_tag_menu.png new file mode 100644 index 000000000..42fed1af0 Binary files /dev/null and b/source/_images/educator_how_tos/taxonomy_delete_tag_menu.png differ diff --git a/source/_images/educator_how_tos/taxonomy_detail_page.png b/source/_images/educator_how_tos/taxonomy_detail_page.png new file mode 100644 index 000000000..67504e229 Binary files /dev/null and b/source/_images/educator_how_tos/taxonomy_detail_page.png differ diff --git a/source/_images/educator_how_tos/taxonomy_overview_page.png b/source/_images/educator_how_tos/taxonomy_overview_page.png new file mode 100644 index 000000000..ac2de4a24 Binary files /dev/null and b/source/_images/educator_how_tos/taxonomy_overview_page.png differ diff --git a/source/_images/educator_how_tos/taxonomy_rename_tag_menu.png b/source/_images/educator_how_tos/taxonomy_rename_tag_menu.png new file mode 100644 index 000000000..7d53cc64b Binary files /dev/null and b/source/_images/educator_how_tos/taxonomy_rename_tag_menu.png differ diff --git a/source/_images/educator_how_tos/taxonomy_tab.png b/source/_images/educator_how_tos/taxonomy_tab.png new file mode 100644 index 000000000..3032495e9 Binary files /dev/null and b/source/_images/educator_how_tos/taxonomy_tab.png differ diff --git a/source/_images/educator_how_tos/taxonomy_tag_usage_count.png b/source/_images/educator_how_tos/taxonomy_tag_usage_count.png new file mode 100644 index 000000000..4c22e48a8 Binary files /dev/null and b/source/_images/educator_how_tos/taxonomy_tag_usage_count.png differ diff --git a/source/educators/how-tos/content-tagging-how-tos/manage_taxonomy_tags.rst b/source/educators/how-tos/content-tagging-how-tos/manage_taxonomy_tags.rst new file mode 100644 index 000000000..f03476442 --- /dev/null +++ b/source/educators/how-tos/content-tagging-how-tos/manage_taxonomy_tags.rst @@ -0,0 +1,293 @@ +.. _manage-taxonomy-tags: + +#################### +Manage Taxonomy Tags +#################### + +.. tags:: educator, how-to + +This guide describes how to create, organize, and manage tags within a taxonomy using the Taxonomy Detail. A detail page for a taxonomy can be found by navigating to the Taxonomies tab in the Studio, then selecting a taxonomy, which will then show that taxonomy's detail page. + +Taxonomy Tab: + +.. image:: /_images/educator_how_tos/taxonomy_tab.png + :alt: Screenshot of the tabs in Studio home, with an arrow pointing to the Taxonomies tab. + +Taxonomy Overview Page: + +.. image:: /_images/educator_how_tos/taxonomy_overview_page.png + :alt: Screenshot of the Taxonomies Overview page showing multiple taxonomies. + +Taxonomy Detail Page: + +.. image:: /_images/educator_how_tos/taxonomy_detail_page.png + :alt: Screenshot of the Taxonomies Overview page showing multiple taxonomies. + +Overview +******** + +Tags allow you to organize and label content across: + +* Courses +* Course content +* Content libraries + +From the Taxonomy Detail page, you can: + +* View tag hierarchy +* See usage counts +* Add root-level tags and sub-tags +* Rename existing tags +* Delete tags and sub-tags + +View Tag Usage Counts +********************* + +Each tag can display a usage count indicating how many unique content objects are associated with it. + +How Usage Is Calculated +======================= + +Counts include: + +* Courses +* Course content +* Content library items + +Both published and unpublished content items are included. + +Each object counts once per tag, even if: + +* Multiple child tags are applied +* The same tag is applied multiple times + + +Parent Tag Aggregation +====================== + +Parent tags include usage from all child tags. + +Example: + +* ``Object A`` is tagged with ``Chemistry`` +* ``Object B`` is tagged with ``Physics`` and ``Chemistry`` + +Parent tag ``Natural Science`` shows a usage count of ``2`` because +``Object A`` and ``Object B`` are each counted once. + +.. image:: /_images/educator_how_tos/taxonomy_tag_usage_count.png + :alt: Screenshot of usage count badges displayed in the taxonomy tag list. + +No Usage Display +================ + +If a tag has no associated content, no usage count is shown. + +Add a Root-Level Tag +******************** + +To create a new top-level tag: + +#. Navigate to the Taxonomies page from Studio Home +#. Choose a Taxonomy to add to and select it +#. Select the + (plus) icon at the top of the tag list + + .. image:: /_images/educator_how_tos/taxonomy_add_root_tag_button.png + :alt: Screenshot of the plus icon used to create a root-level tag. + +#. Enter a tag name in the inline input field + + .. image:: /_images/educator_how_tos/taxonomy_add_root_tag_input.png + :alt: Screenshot of the inline input field for adding a root-level tag. + +#. Click Save or press Enter + +After the tag is saved, the new tag appears at the top of the list and a +success notification is displayed. + +Cancel Tag Creation +============================== + +To cancel a tag creation, select Cancel or press Esc. The input +row is removed, and the tag is not created. + + .. image:: /_images/educator_how_tos/taxonomy_cancel_tag.png + :alt: Screenshot of the cancel button to cancel the process of adding a root-level tag. + +Validation Rules +=============================== + +You cannot save a tag if: + +* The input is empty +* The input contains only whitespace +* The name includes invalid characters: + + * Leading or trailing whitespace + * TAB character + * > (space-greater-than-space) + * ; (semicolon) + +* The name duplicates an existing tag, regardless of letter casing. + + * Example: “Learning” and “learning” are considered duplicates + +Add a Sub-Tag +************* + +To create a tag under an existing parent: + +#. Locate the parent tag +#. Open the actions menu by selecting the three dots +#. Select Add sub-tag + + .. image:: /_images/educator_how_tos/taxonomy_add_sub_tag_menu.png + :alt: Screenshot of the Add sub-tag option in the tag actions menu. + +#. Enter the sub-tag name + + .. image:: /_images/educator_how_tos/taxonomy_add_sub_tag_input.png + :alt: Screenshot of the inline input field for adding a sub-tag. + +#. Select Save, or press Enter + +After the sub-tag is saved, the sub-tag appears directly beneath the parent tag +and is indented to reflect hierarchy. + +Cancel Tag Creation +======================= + +To cancel tag creation, select Cancel or press Esc. The row is +removed without saving. + +Sub-Tag Validation Rules +======================== + +Sub-tags follow the same rules as root tags: + +* No empty or whitespace-only names +* No invalid characters +* No duplicates under the same parent (case-insensitive) + +Rename a Tag +************ + +To rename a tag: + +#. Open the actions menu next to the tag by selecting the three dots +#. Select Rename + + .. image:: /_images/educator_how_tos/taxonomy_rename_tag_menu.png + :alt: Screenshot of the Rename option in the tag actions menu. + +#. Edit the tag name inline +#. Select Save, or press Enter + +After the tag is renamed: + +* The updated name is displayed immediately. +* A success notification appears. +* All tag associations are updated across courses, libraries, and the search + index. + +Cancel Rename +============= + +To cancel a rename, select Cancel or press Esc. The original name is +restored, and no changes are saved. + +.. note:: + + The Save button is disabled until the tag name is changed. Usage counts + remain unchanged after rename. + +Delete a Tag +************ + +.. warning:: + + Deleting a parent tag also deletes its sub-tags. Any uses of the deleted tag + or its sub-tags are removed from associated content. + +Delete a Tag Without Sub-Tags +============================= + +To delete a tag that does not have sub-tags: + +#. Open the actions menu for the tag +#. Select Delete + + .. image:: /_images/educator_how_tos/taxonomy_delete_tag_menu.png + :alt: Screenshot of the Rename option in the tag actions menu. + +#. In the confirmation dialog, type ``DELETE`` +#. Confirm deletion + +Delete a Tag With Sub-Tags +========================== + +To delete a tag that has sub-tags: + +#. Open the actions menu for the tag +#. Select Delete +#. Review the warning that sub-tags will also be deleted +#. Type ``DELETE ALL # TAGS``, where ``#`` is the number of tags being deleted +#. Confirm deletion + +After deletion: + +* The tag is removed +* All sub-tags, if any, are removed +* All tag associations are removed from content +* A confirmation notification is displayed + +Keyboard Accessibility +********************** + +All workflows support keyboard interaction. Users can: + +* Navigate menus using keyboard controls +* Trigger actions such as Rename, Delete, and Add sub-tag +* Save using Enter +* Cancel using Esc + +Permissions +*********** + +Only users with admin permissions can: + +* Add root-level tags +* Add sub-tags +* Rename tags +* Delete tags + +Users without admin permissions do not see the controls for these actions. + +.. seealso:: + + :ref:`build-taxonomy-using-template` (how-to) + + :ref:`create-flat-taxonomy` (how-to) + + :ref:`import-export-taxonomy` (how-to) + + :ref:`Update/Re-import a taxonomy` (how-to) + + :ref:`tag-ids-for-taxonomy-import` (concept) + + :ref:`Manage Permissions on a Taxonomy` (how-to) + + :ref:`add-tags-to-a-course` (how-to) + + :ref:`Add and delete tags on course content` (how-to) + + :ref:`Export tag data from a course` (how-to) + + +**Maintenance chart** + ++--------------+-------------------------------+----------------+--------------------------------+ +| Review Date | Working Group Reviewer | Release | Test situation | ++--------------+-------------------------------+----------------+--------------------------------+ +| 2026-05-05 | Unicon | Verawood | Pass | ++--------------+-------------------------------+----------------+--------------------------------+ diff --git a/source/educators/navigation/advanced_features.rst b/source/educators/navigation/advanced_features.rst index 5dccb9982..59ac806d1 100644 --- a/source/educators/navigation/advanced_features.rst +++ b/source/educators/navigation/advanced_features.rst @@ -112,6 +112,7 @@ Course Tags and Taxonomies ../how-tos/content-tagging-how-tos/import_export_a_taxonomy.rst ../how-tos/content-tagging-how-tos/Create_flat_taxonomy_by_uploading_CSV.rst ../how-tos/content-tagging-how-tos/update_reimport_taxonomy.rst + ../how-tos/content-tagging-how-tos/manage_taxonomy_tags.rst ../concepts/advanced_features/why_taxonomy_tag_id.rst ../how-tos/content-tagging-how-tos/manage_permissions_taxonomy.rst ../how-tos/content-tagging-how-tos/add_delete_course_tags.rst @@ -207,4 +208,4 @@ Use Custom Courses (CCX) :glob: - ../how-tos/enable_ccx.rst \ No newline at end of file + ../how-tos/enable_ccx.rst