API Guide

Table of Contents

1. Introduction
2. The TSD Hierarchy
   1. Navigating the Hierarchy
   2. Creating New Nodes
3. tsd_api_Alignments
4. tsd_api_Relationships

Introduction

TSD is designed to manage standards, textbooks, dictionary words, resource relationships and alignments in a project-agnostic fashion using a modern API and a web-based tool for management. The API is object-oriented, like many of the APIs in common. Make sure you read the Conceptual Overview first before delving into this guide.

The TSD Hierarchy

TSD provides two hierarchies, plus the dictionary: standards and textbooks. Each hierarcy has a set of objects to represent the different levels in the hierarchy. These hierarchies are shown below:

• Organization: TSDStandardOrganization
  • Grade: TSDStandardGrade
    • Category: TSDStandardCategory
      • Objective: TSDStandardObjective
• Book: TSDBook
  • Chapter: TSDChapter
    • Section: TSDSection
• Word: TSDWord

Navigating the Hierarchy

There are several ways to get nodes from the hierarchy. If you know the ID of a node, you can simply create the object and pass that ID to the constructor, like so:

$org = new @ref TSDStandardOrganization "TSDStandardOrganization"(2);

If you already have a node and you want to get its children, you can call listChildren() on that node. This method will return a list of nodes that belong to the given node. So, if you have a grade and want a list of all categories in it, you can do the following:

// get the grade object
$grade = new @ref TSDStandardGrade "TSDStandardGrade"(14);

// get an array of child objects
$children = $grade->@ref TSDStandardGrade::listChildren "listChildren"();

// prints the name of the first category returned
print $children[0]->name;

You can control which children are returned and how many are returned with additional arguments to listChildren(). These types of arguments are explained in the Guide to Database Constraints.

All node classes additional have a static method called getList() which will return a list of objects of that type. If you want to retrieve a list of all organizations, you could do the following:

$organizations = TSDStandardOrganization::getList();

foreach($organizations as $org)
    print "Organization: $org->name<br />";

All non-root nodes have a getParent() method which returns an object representing the parent, or containing, node. If you have a grade object, you can call getParent() to get the organization that that grade belongs to:

$grade = new TSDGrade(24);

$org = $grade->getParent();

Creating New Nodes

The method for creating new nodes in the hierarchy depends on the nature of the node. Root nodes (organizations, books and words) use the following method: create an empty object, fill it with details and commit it. The other nodes require that you call a method on the intended parent object to create the new child. So if you want to add a new category to a grade, you must have a grade object and then call addCategory() on it. Examples are given below.

First method, for root nodes:

// create the empty object first
$org = new @ref TSDStandardOrganization "TSDStandardOrganization"()

// fill in details (but not the ID, this will be done automatically)
$org->name = 'My Organization';
$org->state = 'NC';

// commit the new organization to the database
$org->commit();

For non-root nodes, the following method must be used:

// get the parent node
$grade = new @ref TSDStandardGrade "TSDStandardGrade"(47);

// create the new category
$cat = $grade->@ref TSDStandardGrade::addCategory "addCategory"('My Category');

Alignments

Alignments connect CSERD resources with TSD nodes. The CSERD resources can only be connected to leaf nodes in the TSD hierarchy (i.e., Objective, Section and Word). Additionally, there are two versions of each alignment: dev and live. If there is an alignment at all, it will have a dev version, but it may not have a live version. The dev version will only show up newdev and other dev servers, while the live version will show up on live servers, like www and intranet.