Introduction
Hint: Together with the Topincs Reference this manual contains all you need to know. They are easy to access from the admin menu in any store.
Topincs is an online 4GL platform for building systems using PHP, HTML, CSS, JavaScript and Topic Maps. The last technology is the most important one in this stack since it introduces a unique and powerful way to think about data.
The applicability of Topincs is vast. You can build an enterprise ERP system or make it into a tailored formalized collaboration tool for a research group. Use it as your own programmable personal knowledge database in its original purpose. Or build a manual like this one. Your imagination is the only limit.
A Topincs online database
There is very few core principals – once understood they will open all doors along the way. All of them are explained in this manual in great detail. But be ready for a steep climb. If you feel lost or discouraged, go through the relevant sections again. And most importantly: try it out! You will only fully comprehend Topincs when using and shaping it yourself. Your effort to understand and change your way of thinking about data and development will be worth while, since it will take you less time to build complex and better systems that can be extended indefinitely while remaining maintainable.
Before you start
Topincs lets you create a basic system with little to no knowledge in programming. Yet, formal and abstract thinking is a strong prerequisite. An online database is a fully functional product and is built without programming. But as soon as you take the step into application development, you will need to be able to code. The majority of coding is done in PHP, followed by markup authoring, predominately HTML. For styling you need to be familiar with CSS, with SCSS, if you want to make your life easier. And to enrich pages, JavaScript and a familiarity with the DOM will come in handy, not to forget the basics of the HTTP protocol and the anatomy of the URL. None of these technologies are covered in this manual as there is numerous resources available in print and online.
Hint: Do not worry! Under the hood Topincs is all OOP.
Object-orientation is an essential ingredient in Topincs, but not quite the way you might expect. There is rarely a need to define or instantiate a class, neither is there the necessity to contemplate namespaces or third party libraries. In other software engineering approaches many activities a developer performs are infrastructional – not the given task, but the choice of tools motivates them. Topincs aims to minimize these and favors functions over classes when suitable.
Like any software technology, Topincs is best understood through trial and error. While it may feel unfamiliar in the beginning, you will soon grasp the advantages it has to offer, once the new mechanics become familiar and the task at hand takes center stage. At the end of this introduction you can set up your own personal study database free of charge.
Use case: Santa Claus
The following use case will accompany us throughout this manual. All screencasts in later chapters show the actual development of this system. The system's main goal is educational. It should give you the general idea of how things are done. If Santa Claus ever approaches or even hires you, be sure to go into more depth during conception and implementation. Plus do thorough check of his identity and your sanity.
Hint: You can recognize paragraphs about the use case easily. They have a colored bar to their left like this one.
Santa Claus feels overwhelmed lately, the kids population is growing each year and they all have a free wish for Christmas. It is a lot of information to manage and since a couple of years the number of errors keeps increasing despite the unlimited work force of immortal elves: wishes stay unfulfilled, presents get mixed up and the overall stress level in the organization increases. He is hoping that the introduction of an information system will make everything a little easier again, like in the old days.
Online databases
An online database is similar to a wiki but stores information as data rather than text. In a wiki, users edit pages about topics using markup. In Topincs they complete forms. What they produce is immediately available for other users with the adequate permissions. It can be navigated through links and appears in select boxes in forms.
At the heart of any online database lies its schema. It powers a small number of generic base UI components and an API for developing special components, called services. All of these can be combined in a flexible way to create any number of applications on top of the database. The base components are the form for creating new records aka topics or editing existing ones. The factsheet for viewing a topic and the index for finding topics.
An online database is located at an URL, e.g. https://www.topincs.com/santaclaus/. The terminating slash is significant. We call this URL the store URL, since we call an online database also store. Accessing the store URL, brings the user to the user group specific start page. By default this is an index page which lists all topics grouped by type. Think of a topic as a record or simply something the online database has information about. In the next chapter you will learn a lot more about this term and the technology around it, Topic Maps. A topic is usually connected to other topics. These connections are rendered as hypertext links. At any time you can stop and edit the current topic through a form.
Hint: Check out the different layouts of Topincs by resizing your desktop browser window!
Hint: It is possible to use a customized header, like in this Topincs page you are reading.
All pages in the online database have the same header. It holds the main menu which collapses when too wide and can hold sub menus. To the right, users can search and sign in. A primary design goal of the Topincs user interface is to work well on any screen size, while maintaining a coherent and small set of usage principles. Let us now take a closer look at the three base components: index, fact sheet and form.
Index
The index has two main functions: finding existing topics and creating new ones. For each type in the online database a rectangular bar is displayed. This bar displays the name of the type, how many topics (or instances) of that type exist and a link to create a new instance. When the bar is clicked or tapped, it expands and lists all instances. They can be searched and their display order can be changed. A topic is displayed by clicking or tapping its name or the area around it.
Schematic layout of the index
Factsheet
The factsheet displays all information that is recorded in the database about the topic. The headline holds type, name and meta data of the topic. All information (also called statements) are listed below. By default textual information is displayed to the left and data is displayed to the right.
Hint: Even large systems perform well due to many optimizations under the hood.
In the right margin a context menu for the current topic is displayed. It holds a few standard entries of which Edit is the most important. Delete is hidden under More, since it is not frequently used. A Topincs online database is very much like an archive which never forgets. The context menu can be extended. You will learn how in the chapter User interface.
In smaller layouts the separation of text and data is automatically omitted and the context menu is collapsed into the headline. Resize your browser window in one of the example factsheets to observe this behavior.
Examples
The fact sheet can be configured in many ways. Some of the advanced features are:
- Tabs: Statements can be grouped into so called 'views' and displayed in tabs.
- Replacement: The fact sheet can be replaced by a manual programmed component.
- Access restriction: For every user group the fact sheet can be individually configured, allowing fine grained control over who may see/edit what.
Form
The form for a topic type is generated from the schema. It is used to create new topics or change existing ones. An empty form can be accessed from the index by clicking Record. An existing topic can be edited by using the context menu entry Edit. With Ok the changes are sent to the server and the factsheet is displayed.
Hint: The form is by far the most sophisticated base component. It is used daily hundredfold by numerous different professions.
Special value editors exist for date and many other datatypes. Select boxes are used to create associations to other topics. By default they display only the most likely options and allow access to all options through the entry More. New entries can be created on the fly. In this case a sub form opens and the current form is suspended. It will be reactivated once the sub form is committed or cancelled. Of course sub forms can open sub forms and so on.
Schematic layout of the form page
Generic Workflows
An online database is the foundation of one or more online applications, but it is also a finished product which can be put to good use. These generic workflows work well with any type of factual information independent of the domain. Given a familiarity with the domain and an understanding of the two basic workflows, any user can work with the system.
Workflow for adding a new topic to the database
Workflow for accessing and changing an existing topic in the database
Other components
Besides the above mentioned main components, an online database offers an Ongoing page page which simply list the topics which have recently been create or modified. It is the short-term memory of the web database.
Developing
These generic workflows with the base components are not only used by your users to create, edit, search, and view domain data, but also by yourself when developing a system. Topincs is then just using the Topic Maps meta-schema to drive the base components. We refer to this activity as modeling, even though it is sometimes just configuring some behavior. The other activity, coding, entails editing any form of linear source code that influences the behavior of the system. You will do both. Modeling is quick and easy. Coding takes more time and is error prone, but makes a system fit arbitrary requirements.
The big majority of coding is in PHP followed by HTML or Twig authoring, with optional small adjustments in SCSS. Excursions into JavaScript are rare and only necessary when you need to pull functionality into a single HTML page.
Building a system in Topincs might be unfamiliar in the beginning, since coding is not the only activity. In the initial stage of a system modeling is the main activity, later coding takes over. It is recommended to work on a desktop/laptop computer, ideally with a second screen. There are no other software tools needed. Everything is done directly in Topincs. During development you will sometimes need more than one session: one for the administrator and one to check out the application for the user group in focus. We recommend to do this in an incognito window. Alternatively you can use a second user profile or an entirely different web browser.
Online applications
A Topincs online application offers a tailored view on the store which is optimized for the requirements of a specific user group. Think of it as a restriction and streamlining of the multiple ways tasks can be achieved in a online database. It leads users on predefined and familiar paths which originate in a customized main menu or start page.
Topincs web applications
Hint: Find out more about URLs in Topincs in this in-depth article!
Every component in Topincs is fully defined by an URL. In the case of forms the state of the component can be influenced by query parameters as well: form fields can be prefilled. They can be made immutable too. URl construction is one big part of development in Topincs. It reduces the work load for the user since the application draws conculsions or simply looks something up and prefills a form.
The other big part of a Topincs application is special components which aggregate information in the web database. This can have many purposes. Two reocurring ones are:
- Overview: offers a number of statements for multiple topics and allows to act on them. The page is the point of return when the action is finished.
- Report: large excerpts of the database are used for computations with numerous results which then are displayed in tabular or graphical form.
For Santa Claus we will build an online application for various user groups. Wishes can be requested by anyone without authentication. This predefined user group is called the unauthenticated user in Topincs. A system may also define any number of new user groups. Santa Claus is one of two users in the user group boss. The other is his wife, Mrs. Claus. Their application will help them to keep the overview over this years wishes and plays a central role on Christmas day. And of course the system provides an application for the user group elf.
API
The components of the application access and manipulate the online database through an object-oriented programming interface. This is powered by the schema and setup within seconds. It is intuitive to anyone familiar with object-oriented programming. Topics are represented by PHP objects called Tobjects.
Santa has a question
<?php
// Santa: "How many of each gift do we need to build this year?"
$year = Tobject::get("si:year/" . strftime("%Y"));
foreach ($year->get_all_wishs() as $wish) {
$gift = $wish->get_gift();
// Tobjects can be augmented with transient properties.
if (isset($gift->count) === false) {
$gift->count = 0;
}
$gift->count += 1;
}
Since data is not everything you can just wrap a domain class around your topic and have methods that perform some computation or complex modification. Here are the most common programming artifacts:
- Services are parametrized components which have a computational and presentational aspect,
- Triggers execute some code on certain events,
- Chores execute a service in a predefined interval, and
- Topic access filters control access to topics for user groups based on domain criteria.
Study Database Setup
The best way to understand Topincs is to try every step yourself while studying this manual. For this purpose you can setup your own personal study database for free.
- In a first email you will receive the activation code to complete the setup in this page.
- Once that is accomplished the system will send a second email with the URL of the database, username, and password.
How to study
Hint: Together with the Topincs Reference this manual contains all you need to know. They are easy to access from the admin menu in any store.
Work through this manual in linear fashion, like you would with textbook on math or programming. The chapters in the horizontal main menu outline the journey. The first three chapters are essential to building any database. Coding skills, mainly PHP, are required after that. As of the chapter Modeling you can get a first hand look of how it is supposed to be done by watching short videos. You can skip the chapter Rights, if you are in an environment, where everyone can see and do everything. The chapter In Depth covers important miscellaneous topics that you might need at a later stage.
This should be a hands-on experience. Thus a good project to realize in your study store will prove invaluable. Start looking for one right away! Apply everything you learn immediately to your own use case in the study database.
Public systems
Some public systems can be used to reverse engineer interesting aspects in these applications. They contain a readonly admin account giving access to the complete schema and code. Modification is disabled for this user, not only for schematic data, but also for domain data. The username is Study and the password Topincs, Study/Topincs. Get it? This manual also provides links to directly log in. So you can forget the credentials for now.
Santa Claus
This is the use case system of this manual. It has no practical value whatsoever other than educate you and make you smile every now and then.
Click through
This system serves us to document manual tests of Topincs. These complement the numerous nightly tests to stay in touch with the look and feel of Topincs on different devices. It also documents the evolution of the user interface. The system runs in two languages, English and German.
