Taxonomies

Purpose

Although taxonomies are a crucial component of categorising the material on your application, the phrase frequently confuses newcomers because Taxonomy isn't a term that most of us use on a daily basis. Taxonomy are really just a technique to group similar posts entries (or other types of content) together. That's it! It's a large term, but it's not as hard to understand as it would seem.

Why We Use Taxonomies

In VaahCMS, taxonomies serve several important purposes and are used for specific reasons:

Real Life Example

Imagine you're developing an e-commerce website where you sell a wide range of products. Each product has numerous details, including product origin, material, expiry date, price,and more. Additionally, you want to categorize your products into different groups, such as For Adults, For Children, and For Women.

Using Taxonomies for Categories

Product Details

When it comes to product details, you have a wealth of information to manage. This includes product names, descriptions, images, pricing, inventory, and more. Creating a full CRUD (Create, Read, Update, Delete) for each of these product details can be complex and overwhelming.

Categories

On the other hand, product categories are relatively straightforward. They typically involve a name and a brief description. Instead of creating a full CRUD for categories, you can use taxonomies to define and manage these categories efficiently.

How Taxonomies Work

Taxonomy Type:

You create a Categories taxonomy type specifically for categorizing products. This taxonomy type consists of basic attributes like Name and Description.

Category Entries:

Within the Categories taxonomy, you add entries for different categories such as For Adults, For Children, and For Women. Each entry represents a product category.

Associating Categories with Products:

In your product CRUD, you include a field for Category. Instead of manually entering category names for each product, you link them to the corresponding category entry within the Categories taxonomy. This association can be done through a simple dropdown or selection process.

When Not to Use Taxonomies

Certainly, here are a few scenarios where it might not be necessary to use taxonomies in VaahCMS:

1. When You Need Extensive Data Associations:

If you want to associate a significant amount of data with another dataset, such as detailed information like movie name, actors' names, release year, genre, duration, and poster, it's often more suitable to create a full CRUD (Create, Read, Update, Delete) for that data. For instance, if you want to manage comprehensive movie details, creating a dedicated CRUD for movies would be more appropriate than using taxonomies.

2. Complex Data Structures:

Taxonomies are ideal for organizing simple data structures or limited sets of information. If your data requires complex relationships, hierarchies, or multiple attributes, creating a CRUD with custom fields and relationships may be a better choice.

3. Extensive Customization Needs:

When you require extensive customization and control over the data presentation, storage, and retrieval, a CRUD provides greater flexibility. Taxonomies are more suitable for straightforward categorization and tagging.

4. Data Validation and Integrity:

If you need to enforce strict data validation and integrity checks, especially when dealing with various data types, CRUDs offer more robust validation mechanisms and control over data input.

In contrast, taxonomies are best used when you have relatively simple data that needs categorization or tagging. For example, if you only need to associate movie directors' names with movies, creating a taxonomy type for directors and linking them to movies in a CRUD is an efficient approach. This is especially valuable when you require minimal data, like just the director's name, and don't need extensive fields or complex relationships.

Conclusion

Taxonomies are a valuable feature within VaahCMS that provide a structured and organized approach to managing and categorizing data. They offer flexibility in classifying various types of content, making it easier to navigate, search, and retrieve information. Taxonomies contribute to improved data organization, effective content management, and streamlined user experiences. Whether you're building a website, application, or custom CRUD module, VaahCMS's taxonomy system empowers you to create hierarchical classifications, manage data relationships, and enhance the overall efficiency of your content management processes. By utilizing taxonomies wisely, you can optimize data storage, retrieval, and presentation, ultimately contributing to a more user-friendly and well-structured digital ecosystem.

Default Taxonomy Types

By default, VaahCMS have following types of Taxonomies:

1. Countries
2. Registrations

Features & Demos

Create Taxonomy and Taxonomy Types via VaahSeeder

Through seeds, you can create Taxonomy and Taxonomy types. Make two json files with the names taxonomy.json and taxonomy_types.json in the directory ../VaahCms/Modules/<module-name>/Database/Seeds/json/.

taxonomy.json

[

    {
        "type_slug": "roles",
        "name": "Backend"
    },
    {
        "type_slug": "roles",
        "name": "Frontend"
    },
    {
        "type_slug": "registrations",
        "name": "Email Verification Pending"
    }
]

taxonomy_types.json

[

    {
        "name": "Countries"
    },

    {
        "name": "Cities",
        "parent_slug": "countries"
    },

    {
        "name": "Roles"
    }
]

In order to run these seeds you need to add these lines in run() method of DatabaseTableSeeder.php file

VaahSeeder::taxonomyTypes(__DIR__.'/json/taxonomy_types.json');
VaahSeeder::taxonomies(__DIR__.'/json/taxonomy.json');

DatabaseTableSeeder.php

<?php
namespace VaahCms\Modules\{module_name}\Database\Seeds;


use Illuminate\Database\Seeder;
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Str;
use WebReinvent\VaahCms\Libraries\VaahSeeder;

class DatabaseTableSeeder extends Seeder
{
    /**
     * Run the database seeds.
     *
     * @return void
     */
    public function run()
    {
        VaahSeeder::taxonomyTypes(__DIR__.'/json/taxonomy_types.json');
        VaahSeeder::taxonomies(__DIR__.'/json/taxonomy.json');
    }

}

Now you need to login to the backend and activate your module again by first deactivating it.

Create Taxonomy via Dashboard

To view the Taxonomies section, go to the following url:

<project-url>/backend#/vaah/manage/taxonomies/

Follow below image for reference:

You can create a new taxonomy by clicking on Create button. When you click on Create button you will see a form with following fields. Type is the first field, and the options are organised hierarchically. You can manage the taxonomy types also by clicking on the Manage button. The Tree View of Taxonomy Types PopUp with 'CRUD' Operation will now show.

You will notice a new field called Select a Parent name with the taxonomies of the parent of the type you have chosen if you choose any of the children types.

Complete every field and press the Create & New button. A new taxonomy will be added to the list of taxonomies.

You can view the video attached below for more info:

Create Taxonomy Type via Dashboard

To create a new Taxonomy Type you need to click on Manage button.

Follow below image for reference:

When you click on manage button a PopUp will open with the following fields.

Here in the Select a Parent dropdown you need to select a parent for the new taxonomy type that we are going to create. You also need to provide the name of the taxonomy type.

Once you filled these details you need to click on Add button. A new taxonomy type will be showm to you in the same page.

Watch the below video for better understanding

Permissions

The following permissions are necessary for Taxonomies and Taxonomy Type management in order to carry out certain actions.

Files

• Laravel Route: vaahcms/Routes/backend/route-texonomies.php
• Laravel Controller: vaahcms/Http/Controllers/Backend/TaxonomiesController.php
• Laravel Model: vaahcms/Models/Taxonomy.php
• Vue Route: vaahcms/Vue/routes/vue-routes-taxonomies.js
• Vue Store: vaahcms/Vue/stores/store-taxonomies.js
• Vue Page Directory: vaahcms/Vue/pages/taxonomies

Methods

Some reusable method of Taxonomy and TaxonomyType mentioned bellowed:

TaxonomyType::getTaxonomyByType($type)

You can use this method to retrieve all taxonomies that are currently active under given TaxonomyType by just giving the desired TaxonomyType slug.

use WebReinvent\VaahCms\Models\Taxonomy;  // Import Taxonomy class at the top

$taxonomy_type_slug = 'cities';
return $active_taxonomies = Taxonomy::getTaxonomyByType($taxonomy_type_slug);

API

VaahCMS has APIs for every method, allowing you to interact with NuxJS or other frameworks.

You can access APIs method from vaachms/Http/Controllers/Api/TaxonomiesController.php and routes from vaahcms/Routes/api/api-routes-taxonomies.php

We mention some methods bellow which help you to understand the structure.

Create Taxonomy

Method: POST

Action: creatItem

URL: <public-url>/api/vaah/manage/taxonomies/

Sample Request

parameter = [
    'type',              //required
    'name',              //required
    'slug',              //required
    'is_active'          //required
    'note',              //optional
    'seo_title'          //optional
    'seo_keywords'       //optional
    'seo_description'    //optional
];

Sample Response

{
  "data": {
    "item": {
      ...
    }
  },
  "messages": [
    "Saved successfully."
  ],
  "success": "true"
}

Fetch Taxonomies

Method: GET

Action: getList

URL: <public-url>/api/vaah/manage/taxonomies/

Sample Request

parameter = [
    'filter' => [
        'q'            // for search queary (optionl)
        'trashed'      // for include or exclude trashed data (optionl)
        'is_active'    // for fetching only active or inactive data (optionl)
        'sort'         // for sorting the data (optionl)
    ];  
];

Sample Response

{
  "data": {
    "data" : {
      ...
    }
  }
}

Fetch Single Taxonomy

Method: GET

Action: getItem

URL: <public-url>/api/vaah/manage/taxonomies/{id}

Sample Response

{
  "data": {
      ...
  },
  "success": "true"
}