This is a small tutorial intended to help you to understand and develop web applications with sgsML.

Introduction

For many years now I'm writing web applications. Using PHP, Java, HTML, CSS, Javascript in combination with MySQL, Oracle, MsSQL, etc. always struggling with the complexity of web applications. Making changes in one point always influences many other parts of the program. Often applications have several thousand lines of code (or even more). Searching bugs or making daily changes like adding fields takes a lot of time because you need to test the whole application again. Since time is rare and deadline are sharp, it's time to optimize the common web application architecture.

Looking at bigger programs with many web applications, people start writing frameworks for common functions, managing users and parts of the user interface. But these frameworks are often very limited in functionality or require too much time to learn. Using a small framework, you still need to deal with the full complexity of coding PHP, Java, HTML, etc. Moreover when working in bigger teams with a small framework, everyone writes its own specializations for his part. This creates a unmanageable lack of consistency and increases costs for adding new functionality and fixing bugs. Therefore many companies create bigger frameworks to prevent programmers from getting too individual with their code. With Java this is enforced using object-oriented programming (maybe also with PHP in the future). But I think that all these concepts are still too difficult to learn and understand in short time.

That's why I created a new programming language only intended for web applications. You might ask: Hey, are you just creating another language with the intention to replace all the others? The answer is no. The other languages are still used, but in a different way. This is important to understand, because today programming languages are so complex in usage and syntax, and this gets harder every year.

So what is different when working with sgsML?

You no longer need to be the super nerd of a programming language. Now you can create good web applications without having learned programming for ten years. To build web applications with sgsML it is enough if you can write functions with 5 to 10 lines of code. You no longer write functions to store or load data in the database. You no longer write GUI components just like HTML editors, spreadsheets or data selectors. How can this work?
The name sgsML already indicates a relation to XML. To produce applications written in sgsML, XML version 1.0 has been chosen as the syntax for sgsML files. This format is easier to read and interpret than many other formats (e.g. ini, CSV, CSS, etc.). As said before we are talking about sgsML files, meaning that one module (e.g. companies or appointments) is written into one file with the extension ".xml".

Types

With sgsML a field is generally defined by its type. This can be a text, a date, a number, etc. So when you define a field as text with sgsML, Simple Groupware creates this field in the database with the correct type and size in the corresponding table. Furthermore Simple Groupware already knows how to display this field (You only have to decide between a horizontal or a vertical view) including sorting, searching, etc. Additionally, forms to create or edit this field inside a dataset are created automatically for you.

Syntax: Types are declared with simple_type="type" where type is one of int, float, text, password, id, hidden, select, wikiarea, codearea, textarea, htmlarea, checkbox, files, date, time, datetime ... for a complete list, see src/modules/schema/!examples.html.

Validators

To be able to validate inputs made by a user you are able define functions that take care of this. E.g. you define a field as type text and also declare that it has to be validated with the two functions myvalidate1 and myvalidate2. When a user wants to save a new dataset these two functions are called with the value of the field as a parameter and you only have to return a true/false-like answer to tell the program that the input is valid or not. You don't have to care about displaying the form again, mark the field with color red, display the error message to the user, etc. This is all done for you automatically. These 2 functions are normally pretty easy and so small that even beginners can write them very quickly (they don't need any knowledge about the database, or HTML forms with heavy usage of Javascript). To make these functions smaller in size, you can define more than one functions for the validation of a field. This also helps you reuse functions (-> you automatically produce reusable code).
E.g. you want a field to be a positive number: Just write one function "is_numeric" that controls if the value is a number and a second one called "is_positive" that tests if it is positive.
Of course, validating a German, English or ISO formatted date requires some work. Therefore a large number of functions for validating dates, strings and numbers is already shipped with Simple Groupware by default.

Syntax: To collect these functions in a central place, all validators are stored in core/functions_user.php and have a "validate_" prefix, e.g. "validate_is_numeric". To define a validator in a sgsML file, write <validate function="is_numeric"/> between the <field>-tags to validate the field with the function validate_is_numeric.

Filters

Reading carefully you have read that Simple Groupware automatically displays your fields. But oftentimes you want to display fields differently from the value stored in the database. This is no conflict since you can define filters that change the value of a field before being displayed. This is elementary when working with dates. E.g. your database is configured for English dates, but you want to display them in German. Or you want to crop long texts to only show the first 20 words. Similar to validators you assign a function to the field that performs the filtering operation. This function takes the value of the field as input and returns the filtered value back to the program. This is also very easy for beginners who don't need to care where the field is displayed or where the value comes from. As said Filters are similar to Validators, which means you can make the functions smaller in size by defining more than one function for the filtering process of a field. This also helps you reuse functions (-> you automatically produce reusable code).
E.g. you want a date field to be presented as a German date, take a look at the following code:

This illustrates you the syntax of a filter and also the syntax for applying parameters to your functions (simply add a "|" to separate the parameters). To make working with dates easier for you, the function to format dates is already shipped with Simple Groupware. The first parameter takes a verbal date modification, e.g. now + 1 month which returns the date increased by 1 month. The second parameter defines the format of the date.
An overview of the format parameters can be found at http://www.php.net/date. Examples dealing with modifications of dates are here: http://www.php.net/strtotime.

Syntax: To collect these functions in a central place, all filters are stored in core/functions_user.php and have a "modify_" prefix (because they modify data), e.g. "modify_dateformat". To define a filter in a sgsML file, write <filter views="all" function="truncate|20"/> between the <field>-tags to truncate the field to a maximum of 20 characters with the function modify_truncate. (The "views=all" parameter indicates that this filter is used with every view and will be discussed later) Other functions are included to help you to manage files, URLs, source code highlighting, etc.

Note: for being neutral the date is stored in the database as timestamp (=an integer value).

sgsML: Part 1 - sgsML: Part 2 - sgsML: Part 3 - sgsML: Part 4