Home

Awesome

<h1 align="center"> 🌳 dTree-Seed 🌰 </h1> <p align="center"> <i> A library for converting a list of objects into a hierarchical data structure for <a href="https://github.com/ErikGartner/dTree">dTree.</a> </i> </p> <p align="center"> <a href="#β„Ή%EF%B8%8F-about">About</a> β€’ <a href="#-demo">Demo</a> β€’ <a href="#-installation">Installation</a> β€’ <a href="#-requirements">Requirements</a> β€’ <a href="#-usage">Usage</a> β€’ <a href="#%EF%B8%8F-acknowledgements">Acknowledgements</a> β€’ <a href="#-technologies-used">Technologies Used</a> β€’ <a href="#-license">License</a> </p> <p align="center"> <a href="/LICENSE"> <img alt="GitHub" src="https://img.shields.io/github/license/jmheartley/dtree-seed?color=red" alt="MIT License"> </a> <img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/jmheartley/dtree-seed?color=orange"> <img alt="GitHub contributors" src="https://img.shields.io/github/contributors/jmheartley/dtree-seed?color=yellow"> <img alt="Lines of code" src="https://img.shields.io/badge/total%20lines-4.4k-brightgreen"> <img alt="GitHub repo size" src="https://img.shields.io/github/repo-size/jmheartley/dtree-seed"> <img alt="NPM version" src="https://img.shields.io/npm/v/dtree-seed?color=blueviolet"> </p>

ℹ️ About

Structuring data for dTree is hard... but not anymore! Painlessly, with just one method call, you can:

Before

[
    {
        "id": 0,
        "name": "Father",
        "parent1Id": null,
        "parent2Id": null
    },
    {
        "id": 1,
        "name": "Mother",
        "parent1Id": null,
        "parent2Id": null
    },
    {
        "id": 2,
        "name": "Child",
        "parent1Id": 0,
        "parent2Id": 1
    }
]

After

[
  {
    "id": 0,
    "name": "Father",
    "depthOffset": 1,
    "marriages": [{
      "spouse": {
        "id": 1,
        "name": "Mother",
        "depthOffset": 1
      },
      "children": [{
        "id": 2,
        "name": "Child",
        "depthOffset": 2
      }]
    }],
    "extra": {}
  }
]

πŸš— Demo

Check out how dTree-Seed can be used to recreate the dTree sample on JSFiddle.

πŸ“¦ Installation

There are a few ways to start working with dTree-Seed, all of which globally expose the dSeeder variable:

  1. Manually download the compiled file dSeeder.js from dist to your appropriate project folder and load using a relative path:
<script src="/path/to/dSeeder.js"></script>
  1. Use <script> to reference the code through jsDelivr's CDN:
<script src="https://cdn.jsdelivr.net/npm/dtree-seed@1.0.0/dist/dSeeder.min.js"></script>
  1. Install as a package via npm with the following command:
npm install dtree-seed

β›½ Requirements

dTree-Seed has no dependencies itself as it's just a data processor. However, it's intended for use with dTree v2.4.1, which requires the following:

<!-- required for dTree -->
<script src="https://d3js.org/d3.v4.min.js"></script>
<script src="https://cdn.jsdelivr.net/lodash/4.17.4/lodash.min.js"></script>
<!-- load dTree -->
<script src="https://cdn.jsdelivr.net/npm/d3-dtree@2.4.1/dist/dTree.min.js"></script>

🚘 Usage

To preprocess your data for dTree, use the dSeeder.seed() command:

seededData = dSeeder.seed(data, targetId, options);
dTree.init(seededData);   // command provided by dTree

πŸ’Ύ Data

The data object should be an array of objects, each of which should have at least these properties:

[{
        id: number,
        name: "Hugh Mann", // optional, but recommended
        parent1Id: number, // use null for no value
        parent2Id: number  // use null for no value
}]

Note: if parent1Id or parent2Id references an id, but no object in data contains that id, an error will be thrown. In such cases, please set that property to null.

See Member for the Typescript interface for objects in data.

🎯 TargetId

The targetId is the id of the object you wish to build your tree around.

πŸ€” Options

Add callbacks to the options object to dyanmically set the corresponding class, textClass, and extra properties for each node.

Each callback takes a member object, which is an object in your data.

{
    class: (member) => string,      // sets CSS class of each node
    textClass: (member) => string,  // sets CSS class of text in each node
    extra: (member) => object       // sets extra object, custom data for renders
}

options is an optional parameter, when no callbacks are used, class and textClass will default to an empty string and extra to an empty object for each node.

See SeederOptions for its Typescript interface.

<details> <summary>πŸ’‘ Examples</summary>

class

If your objects have an ageInYears property that cooresponds with a CSS class named minor for people younger than 18, you can conditionally set the CSS of the node using the class callback:

{
    class: (member) => {
        if (member.ageInYears < 18)
            return "minor";
    }
}

textClass

If you want to set the same CSS class fw-bold for all node text, return a static value using the textClass callback:

{
  textClass: (member) => "fw-bold"
}

extra

If you have properties on each member you want to persist on each node in the tree, you can pass them into an object using extra callback:

{
  extra: (member) => {
    return {
      height: member.height,
      ageInYears: member.ageInYears,
      favoriteColor: member.favoriteColor
    };
  }
}

The extra object is passed to dTree's callbacks , the above properties would accessbile on the extra parameter using extra.height, extra.ageInYears, and extra.favoriteColor.

For the above examples, here's what the data might look like:

[{
        id: 0,
        parent1Id: null,
        parent2Id: null,
        name: "Father",
        ageInYears: 26,
        height: "5ft 9in"
        favoriteColor: "Green"
},
{
        id: 1,
        parent1Id: null,
        parent2Id: null,
        name: "Mother",
        ageInYears: 24,
        height: "5ft 6in",
        favoriteColor: "Blue"
},
{
        id: 2,
        parent1Id: 0,
        parent2Id: 1,
        name: "Child",
        ageInYears: 1,
        height: "2ft 5in",
        favoriteColor: null
}];

For more examples on how to use the options object, check out its unit tests.

</details>

❀️ Acknowledgements

πŸ§™πŸ» Erik GΓ€rtner for writing and sharing dTree

πŸ‘©πŸΏβ€πŸ« Microsoft Learn for teaching me Typescript

πŸ‘©β€πŸ’» Technologies Used

πŸ“ƒ License

The MIT License (MIT)

Copyright (c) 2022 Justin M Heartley