Hint: Resource is more general than page. HTML pages are just one type of resource, other common types are images, style sheets, PDF documents, and CSV files.
The Uniform Resource Locator, short URL, plays a central role in Topincs. This page explains its anatomy in general and then the particularities in Topincs in greater detail. It describes how to create URLs to link to the resources of a Topincs store in application menus or HTML services. The reduction of detours and other unnecessary actions leads to a better, more fluid user experience. This essential knowledge for Topincs application development helps you improve the productivity of your users.
External references
The URL is one of the building blocks of the World Wide Web, besides HTML and HTTP. It is a string consisting of four parts: scheme, host, path, and query. Let's take a look at the URL of the current page.
https://www.topincs.com/manual/url
// scheme: https
// host: www.topincs.com
// path: /manual/url
As you can see not all of the parts are required. In the example above query is missing. So let's examine another one where it is present.
External references
https://www.topincs.com/clickthrough/.index?tt=715
// scheme: https
// host: www.topincs.com
// path: /clickthrough/.index
// query: tt=715
The query part has important internal structure. In tt=715
you see a key tt
and a value 715
. tt
is short for topic type and 715
is the system id of the topic type Clickthrough test in the respective database. Any number of such key values pairs can be contained in query. They are separated by AMPERSAND &
and are called query parameters.
https://no.topincs.com/short/list?car=71&car=98&fuel=0
// car=71
// car=98
// fuel=0
A Topincs store is located at a URL, which is called the store URL. It terminates with a slash. Everything the database contains (topics) and offers (services) has a URL that starts with the store URL. Some resources are generic and driven by the Topincs code, all others are system specifc services implemented by you. Generic resources start with a dot, to keep the namespace completely at your disposal.
One host can give access to any number of independent stores. Let's take another look at the above examples and determine their store URL.
https://www.topincs.com/clickthrough/.index?tt=715
// Store URL: https://www.topincs.com/clickthrough/
// Resource: .index?tt=715
https://www.topincs.com/manual/url.html
// Store URL: https://www.topincs.com/
// Resource: manual/url.html
As you know Topincs uses three schema driven base components: the factsheet, the form, and the index. In addition you program services, which are basically high level functions, that are called by HTTP requests and executed on the server. We will now take a closer look on how to tailor URLs to prefill the form and the service form.
Hint: The most common side effects of POST services are changes to the database via the API and sending an email.
As already mentioned above services are high level functions. Just like a function they have parameters, perform a computation, produce a result (GET) or have a side effect (POST). When a service is called, the parameters get bound to values, which are then referred to as arguments. Now if an ordinary function in any programming language misses a required argument, it fails to work. A service in this case will present the service form to the user to provide the missing arguments. This mechanism can be used to create shortcuts for your users by prefilling the service form with everything you already know from their current context in the application.
A GET service call will be executed, if all required parameters are given. If the action a user perfoms with a service requires extraordinary attention, it is possible to force the service form by appending &
(AMPERSAND). This way you can make the user aware of an optional parameter the service has. This will show the service form even if all required arguments are already given. In which circumstances you chose to require confirmation is domain specific and should be discussed with the users.
Check it out
Check it out
// This URL executes the service 'overview' in Santa Claus.
https://www.topincs.com/santaclaus/overview.html?year=2021
// By appending AMPERSAND we get the service form.
https://www.topincs.com/santaclaus/overview.html?year=2021&
The form either creates a new topic or edits an old one. While prefilling form fields works for both cases, we focus here soley on prefilling an otherwise empty form for creating a new topic. Let's first take a look at the basic, empty form for creating an instance of Wish in the Santa Claus store. The topic type Wish has the system id 1276
there.
Check it out
// This URL addresses the wish form:
https://www.topincs.com/santaclaus/.form?tt=1276
// Query parameters
// tt=1276
The form is composed of paragraphs corresponding to the constraints defining the respective topic type. Each paragraph consists of a headline and one or more input elements. You can prefill input elements by using query parameters. The id of the respective type is used as a key and the value forms the input of the form element. Let us prefill the wish form with a name and age of the child. The system id of the name type Child's name is 1275
. The occurrence type Age carries the system id 1278
.
Check it out
// We omit the store URL from now on.
.form?tt=1276&1275=Kurt&1278=7
// Query parameters
// tt=1276
// 1275=Kurt
// 1278=7
Prefilling values for association types is a bit more complicated as you need to specify the association type and the role type. The key is built from the respective system ids connected by -
(DASH).
Check it out
.form?tt=1276&1284-1276=1273
// Query parameters
// tt=1276
// 1286-1276=1273
When you want to prevent the user from changing the prefilled value, you need to put an *
(ASTERISK) in front of the =
(EQUAL SIGN). This works accordingly in the service form.
Check it out
.form?tt=1276&1278*=7
// Query parameters
// tt=1276
// 1278*=7
Topincs uses child forms to edit adjuncts to the main topic. They might be row displayed, in which case no new form is rendered, but it is inlined directly in the parent form as a row form. Child forms can be prefilled by as well. For your understanding we will discuss briefly how this works. Thereafter we will introduce you to a method which will circumvent the tedious work of collecting the system ids of the relevant schematic topics.
The child form is connected via an association type to the main form. Thus we use its key followed by an index denoting the position.
.form?tt=715&741-715_0_730-729=709&741-715_0_735=1
// Query parameters
// tt=715
// 741-715_0_730-729=709
// 741-715_0_735=1
// Child form 741-715_0
// Association type/role type: 741-715
// Index: 0
// 730-729 and 735 are axis in that form.
The administrator can easily capture the state of any form through the admin menu. The function is called Capture form state and is only present on the form and the service form. This eases the creation of URLs for linking to prefilled forms during service programming. Simply fill out the fields you need, capture the state, and copy the URL.
This page cannot be displayed in your browser. Use Firefox, Opera, Safari, or Chrome instead.
Saving …