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 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.

$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 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.

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);
$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.

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 practise 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. Click Create domain class, provide a name, click Ok and you can edit the source code of the 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.

stores/invoicing/php/domain/Invoice.php

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");

stores/invoicing/php/domain/Issue.php

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");

stores/invoicing/php/domain/WorkSession.php

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

Hint: A service may have more than one representational components.

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.

stores/invoicing/php/services/invoice/GET.php

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 the context of the actual service task:

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

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

// Acceleration
Tobject::accelerate("invoice", "invoice-number", "invoicing-date", "issue");

stores/invoicing/php/services/invoice/GET.xml

<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>

Acceleration

API reference

Tobject::accelerate

Services that run slow because they aggregate large parts of the database can be sped up manually by using Tobject::accelerate. This pulls relevant parts into memory and has a very positive impact on the runtime while it increases memory consumption.

Acceleration does not make any sense if only a few topics are of interest during service runtime. This will pull everything into memory and only a fragment is acutally accessed. An inappropriate use of acceleration can have a negative impact on the overall performance of the application.

Using a service

Hint

Is it easy to call a service from JavaScript or Tabluar data export

Exporting data in tabluar form is reoccurring task in any development project. The Topincs API offers a number of classes that makes this task a matter of minutes rather than hours by streamlining the code and avoiding pitfalls. Following you find the computational and presenatational code for such a service.

stores/invoicing/php/services/export/GET.php

require_once("api/export/DataTable.php");

$columns = [["name" => "Invoice nr"],
            ["name" => "Invoice date", "format" => "d.m.Y"],
            ["name" => "Issue count"],
            ["name" => "Hour rate", "format" => "mformat"]];

$table = new DataTable(count($columns));

foreach (Tobject::all_invoices() as $invoice) {
  $table->add([$invoice->get_invoice_number(),
               $invoice->get_invoice_date(),
               $invoice->count_issues(),
               $invoice->get_hourly_rate()]);  
}


function mformat($n) {
  return number_format($n, 2, ",", "");
}

stores/invoicing/php/services/export/GET.csv

require_once("api/export/CsvWriter.php");

content_type("csv", "attachment", "export.csv");

// For easy debugging:
// content_type("plain");

echo CsvWriter::write($table, $columns, 
                      ["delimiter" => ";", 
                       "encoding"  => "ISO-8859-1"]);

Triggers

A trigger is a piece of PHP code that is executed when a certain events in the web database happens. 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

Example

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:

stores/invoicing/php/triggers/567.php

require_once("api/Tobject.php");
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

Virtual interface

Method families by example

Topic creation and deletion

Accessing instances of a topic type

Domain Classes

Creating a domain class

Topincs services

Creating a service

Service arguments

Acceleration

Using a service

Triggers

Example

Summary

We are sorry