Programming

Topincs programming uses small code artifacts to achieve a certain domain task. The fundamental concepts are:

Tobjects (short for topic objects) provide read-write access to topics from PHP.
Domain classes extend the data-driven interface of tobjects with computational methods.
Services are parameterized scripts that are accessed from the main menu or topic pages.
Triggers are executed automatically when certain events in the web database happen.
Topic access filters are used to specify conditions under which a user group is denied access to certain topics.

Example domain: Invoicing

Hint: Use Guest/Guest to log in to the example store accompanying this guide.

The concepts presented will be illustrated with code examples from an invoicing system of a software company: an invoice has an hourly rate and invoices a number of issues for which a number of work sessions are used. A work session has a start and an end of datatype xsd:dateTime. In this system we can identify a need for:

an XML view of an invoice for generating a PDF with XSLFO,
a CSV view of all invoices for data exchange with another system,
a service to access online banking to check which open invoices have been paid, and
a trigger to compute and persist the time spent on an issue.

Tobjects

API reference

Tobject

Hint: Both works: get_invoice_number or getInvoiceNumber!

Hint: Use the strict equals comparison operator === or equals if you want to know if two tobjects represent the same topic!

A service gains access to data in the store by retrieving a tobject. A tobject is a topic as a PHP object with a virtual interface driven by the constraints of the type of the topic. The following example fetches an invoice and prints its number and issues.

Simple tobject usage

$invoice = Tobject::get($some_invoice_id);
echo $invoice->get_invoice_number() ."\n";
foreach ($invoice->get_all_issues() as $issue) {
  echo $issue->label() ."\n";
}

During one PHP runtime (instantiated either by a service request, in a job execution or by a command line call) a topic that is retrieved multiple times will always result in the same tobject. This behavior can be used to aggregate additional information on the tobject by storing computational results or frequently used data. This simple behavior of tobjects becomes very useful in any sort of complex computation since it reduces the need to revert to secondary data structures thus reducing the overall complexity of source code.

data properties

Hint: If you need to ensure a certain property structure on a tobject in more than one service, you can declare an init method in a domain class.

$invoice = Tobject::get($some_invoice_id);
// Declare an additional member on this tobject
$invoice->total_hours = 0;
foreach ($invoice->get_all_issues() as $issue) {
      $invoice->total_hours += $issue->compute_hours();
}

Virtual interface

Hint: Keeping serialization names constant is a good idea, but a broken interface can be repaired by using a domain class!

The virtual interface is driven by constraints and serialization names. We need to set it up by assigning serialization names to all relevant items on the page Programming interface. You can reach it from the admin menu. The interface of our invoicing example is available online. The following table illustrates the relationship between serialization names and method names.

How to setup the PHP programming interface

Serialization name	Item type	Method name examples
`invoice-number`	Name type	`has_invoice_number` `get_invoice_number`
`start`	Occurrence type	`get_start` `set_start`
`issue`	Role type	`get_all_issues` `delete_all_issues`
`issue`	Topic type	`make_Issue` `isa_Issue`
`invoice`	Topic type	`make_Invoice` `isa_Invoice`

The interface allows access and manipulation of statements about the topic that a tobject represents. There is several method families available: has, count, get, set, add, delete, and isa. The programming interface page only displays the methods that make sense given the constraints of the topic type.

Method families by example

Hint: The individual statements are independent from each other.

// has
if ($invoice->has_invoice_date()) {
  ...
}

// count
echo $invoice->count_issues();

// get
$rate = $invoice->get_hourly_rate();
foreach ($issue->get_all_work_sessions() as $session) {
  ...
}
      
// add
$invoice->add_issue($issue);
$some_invoice->add_all_issues($another_invoice->get_all_issues());

// delete
$session->delete_end(); // delete one
$invoice->delete_all_issues();

// set (delete all and then add)
$session->set_end(new DateTime());
$some_invoice->set_all_issues($another_invoice->get_all_issues());
      
// word (similar to get, but respects language preference in a multilingual store)
echo $photo->word_description();

// isa
if ($something->isa_Invoice()) {
  ...
}

Topic creation and deletion

// Creating a topic
$session = Tobject::make_WorkSession()
  ->set_start(new DateTime())
  ->set_issue($some_issue);

// Deleting a topic
$session->delete();

// Deleting many topics
Tobject::delete($issue->get_all_work_sessions());

Accessing instances of a topic type

// Iterate over all invoices
foreach (Tobject::all_invoices() as $invoice) {
 ...
}

Domain Classes

Hint: It is good programming practice to have only one class per file!

A domain class extends a tobject with non-data based methods. It can be registered for one or more topic types. The tobject will have methods of all domain classes that are registered (loaded) at call time. It is convenient to think of a domain class as being assigned to a topic type, but this correspondence is not essential to a domain class. A domain class is rather a mixin which has certain implicit expectations towards the tobject.

Creating a domain class

A domain class is created on the page of the topic type. ClickCreate domain class, provide a name, click Ok and you can edit the source code of the class.

How to create a domain class

In our invoicing system we need to calculate the time spent on all issues of an invoice so we know how much to charge. This information needs to be computed since it is not persisted in the store. In order to distinguish computational results from persistence, it is helpful to name methods of a domain class other than get_something, e.g. compute_something.

Domain class example

require_once("domain/Issue.php");

class Invoice extends Tobject {
    function compute_amount() {
        return $this->get_hourly_rate() * $this->compute_hours();
    }
    function compute_hours() {
        $hours = 0;
        foreach ($this->get_all_issues() as $issue) {
            $hours += $issue->compute_duration_in_hours();
        }
        return $hours;
    }
}

Tobject::register("Invoice", "id:368");

Another related example

require_once("domain/WorkSession.php");

class Issue extends Tobject {
    function compute_duration_in_hours() {
        $duration = 0;
        foreach ($this->get_all_work_sessions() as $session) {
            $duration += $session->compute_duration_in_sec() / 60 / 60;
        }
        return $duration;
    }
}

Tobject::register("Issue", "si:https://www.topincs.com/trial/invoicing/376");

One more related example

class WorkSession extends Tobject {
    function compute_duration_in_sec() {
      return $this->get_end()->format("U") - $this->get_start()->format("U");
    }
}

Tobject::register("WorkSession", "si:https://www.topincs.com/trial/invoicing/392");

Topincs services

A Topincs service satisfies a domain specific need. Some basics of HTTP requests will help your understanding. HTTP requests

are addressed to an URL,
have a verb, usually GET or POST,
return a response which may have a body, e.g. a HTML document, and
may specify a preference for a certain response format.

When you provide a read-only view of data in the store, you should use the GET verb, otherwise POST.

Creating a service

A service is created on the schema page of the store. After creating the topic the source code can be edited by clicking on Source code in the menu on the topic page. Normally two files are created, e.g. GET.php and GET.xml. The first one is supposed to be a pure PHP file without any markup – the computational component. The second one is called the representational component and uses PHP or markup for generating the output. In case of POST the second one may contain a summary of the operations performed or may be completely omitted.

Service arguments

Hint: By default parameters are accessed parsed. In rare case you might need them unparsed. Use get_unparsed.

API reference

ServiceParameters

Service arguments can be added during the service creation or later. There is two kinds of arguments: topic arguments and value arguments. For the first ones you need to specify one or more topic types of which the instances can be used as parameters. They will be rendered as a select box in the parameter query form. For the latter you need to specify a datatype.

On a service call the arguments are bound to parameter values. The service can access parameters via their formal name through the variable $p which is an instance of ServiceParameters.

In our invoicing system the following example creates an XML format of an invoice which interfaces with another system that generates a PDF document with XSLFO.

Service parameters

require_once("domain/Invoice.php");

// We use "invoice" as the formal name of our service parameter
$invoice = $p->get("invoice");

// Just for illustration and out of context of service coding:

// Default values
$tax_rate = $p->get("taxrate", 20);

// Unparsed value
$tax_rate_string = $p->get_unparsed("taxrate");

An example XML template

<invoice>
   <number><?php echo $invoice->get_invoice_number() ?></number>
   <date><?php echo $invoice->get_invoicing_date()->format("j.n.Y") ?></date>
   <service>
<?php foreach ($invoice->get_all_issues() as $issue) { ?>
     <issue>
       <name><?php echo $issue->label(false) ?></name>
       <duration-in-hours><?php echo $issue->compute_duration_in_hours() ?></duration-in-hours>
       <amount><?php echo $issue->compute_duration_in_hours() * $invoice->get_hourly_rate() ?></amount>
     </issue>
<?php } ?>
   </service>
   <total>
     <hours><?php echo $invoice->compute_hours() ?></hours>
     <amount><?php echo $invoice->compute_amount() ?></amount>
   </total>
</invoice>

How to create and program a service

Using a service

Hint: Is it easy to call a service from JavaScript or PHP.

Services can be accessed unparameterized from the default main menu. An auto-generated form will be presented to gather the service parameters, e.g. which invoice to generate. If you created a service connection for the menu of the topic type invoice, the user has the option on the page of an invoice to access the service parameterized meaning that the invoice displayed will be bound to the parameter of the service. It is very common to simply link from services with HTML output to other services.

Triggers

A trigger is a piece of PHP code that is executed when certain events in the web database happen. Examples for events are:

after an instance of type invoice is saved
after a file of type picture is archived
after an occurrence of type end is inserted or updated
before a topic of type invoice is deleted
after a role of type invoiced is created

A trigger is created in the programming section on the schema page of the store. First specify on which events the trigger fires. There is three classes of events:

Item events fire when items are created, updated, or deleted.
File events fire when file are archived (uploaded).
Form events fire when users save an instance of a topic type.

After the trigger topic is created, click on Source code to program the trigger. The parameters passed to the trigger code are explained in the source code file. For item events the following table explains what the parameter $topic_id is bound to:

Item type	$topic_id is bound to
Name	id of the parent
Occurrence	id of the parent
Role	id of the player
Topic	id of self

How to create a trigger

In our invoicing system work sessions are recorded as people progress through their issues. If the end of a work session is recorded, the persisted duration of the time spent on the issue should be updated:

Example trigger

require_once("domain/Issue.php");

// $topic_id is the only parameter passed to a trigger!
$session = Tobject::get($topic_id);
$issue = $session->get_issue();
$duration_in_hours = $issue->compute_duration_in_hours();
if ($duration_in_hours) {
  $issue->set_duration($duration_in_hours);
} else {
  $issue->delete_duration();
}

Now all that remains is to specify on the topic page of the trigger that it should run after an occurrence of type start or end is inserted, updated or deleted. With this mechanism the duration at the issue is always up to date.

Summary

Topincs programming continues the Topincs principle to achieve a lot with little work. By assigning serialization names to statement types a virtual programming interface comes alive in a matter of minutes. Domain classes are a flexible tool to temporarily tie computational behavior to one or more topic types. They make it possible to change the underlying data in the topic map and still keep dependent code functional by using a domain class as an adaptor and importing it in the scripts that rely on the old data schema. These properties make it possible to quickly react to changes in the requirements.

Programming

Example domain: Invoicing

Tobjects

Simple tobject usage

data properties

Virtual interface

How to setup the PHP programming interface

Method families by example

Topic creation and deletion

Accessing instances of a topic type

Domain Classes

Creating a domain class

How to create a domain class

Domain class example

Another related example

One more related example

Topincs services

Creating a service

Service arguments

Service parameters

An example XML template

How to create and program a service

Using a service

Triggers

How to create a trigger

Example trigger

Summary

We are sorry