User Tools

Site Tools


vortex:usermanual

Vortex User Manual

This page is the user manual for Vortex. It will be updated continuously as new features are implemented in the Vortex.

Admin

Users adminstration

In order to authenticate using AD over LDAP the Vortex needs to be configured for LDAP use. The password can be set to whatever for the user and the ad_user field needs to be set to the AD user to authenticate as. Note however that the local password in the Vortex will be active and the Vortex will authenticate the user either way.

Groups administration

Tables administration

Table fields

Here follows a description of the fields in a Table.

Name

This is the database name of the table. The name follows the same name standard as SQL table names. No spaces are allowed and a minimum of special characters. Tablenames starting with the _ character are reserved for internal use and not allowed on user tables. When scripting the vortex, this is the name that's used to refer to this table.

Description

This is the name of the table that will be used in the GUI of the Vortex, ie this is what's shown to the user.

Describing field

This is a VXString describing a record in this table, ie a short summary of the record.

Template file

Not used at the moment, to be removed later.

Icon

The URL or filename of an icon to use for this table. Shown in the menu and on the details page for records.

Keep history

Flag that decides wether to keep history for this table. History is kept for fields having the history flag in the extra field set to true.

Enable WorkFlow

Enabling this flag makes the Vortex check for WorkFlows mathing the criteria of the records in this table when they are modified. For more information, see Workflow.

Creating fields

The charachter _ is reserved as the first character in both table and field names. This is to prevent duplicates with system fields and system tables.

Default Value

The default value for a field can be assigned by placing a value in the default value parameter of the Field. The value is parsed as a Vortex String and variables and function calls are substituted before the value is set to the field.

Extra information

Using the Extra field you can supply instructions to the Vortex on how to handle the field. Information is supplied in the form

 [parameter_name]:[parameter_value];[parameter_name]:[parameter_value];...

If the parameter value is omitted it will be set to true. Following is a list of currently supported extra information parameters:

Parameter nameValuesScopeDescription
closedtrue/falseCategoryFieldWether this category is closed by default.
cols<int>*The number of columns for this field to cover in the details view. Normally 1 to 4.
historytrue/false*When true, this field triggers saving of a new history post.
rows<int>*For multi-row fields this parameter sets the number of rows to display per default.
value<String>*When the value parameter is defined this field will ALWAYS have the value of the parameter value. The parameter value is a VxString which is parsed and variables and functions are substituted by their respective results.
Store history

To activate the logging of changes for a table the flag Keep history has to be set on the table. This is done in the details view of the table admin. This activates the history feature for the table and will make the Vortex search for historic posts when entering the details view for a TableRecord in this table. However nothing will trigger the saving of history posts. To determine which changes will trigger a history post the keyword

  history;

is added to the extra field of each Field that should trigger a history post when changed.

For example, a table containing the Fields a,b and c with the Keep history flag set and the history; keyword set in the Extra field for a and b will create a history post whenever changes to a or b are saved. It will however not create a history post if only c is changed.

Data types

Category fields

The category field is used to categorize other fields in the Details view. The description of the field is shown as the title of the category, and the categories can be opened/closed. Fields with fieldorder values between the value of this category and the next category are placed in the category. Fields with fieldorders outside any categories are placed in a default category.

Categories are per default open, but the Extra info field can be used to set the category to be closed by default by adding the string

closed;

Colorstatus fields

The colorstatus field contains a RGB value and shows a box with the chosen color in the showlist and details view.

Relations

There are three types of relations in the Vortex:

Relation typeExplanation
1 - 1One record is connected to none or exactly one other record where both records contain a RelationField pointing to the other record.
Example: One house having one address.
1 - xOne record is connected to none, one or more records. One RelationField exist in the records on the 1-side, pointing to the related record. On the X-side a RelationPane is displayed with a list showing all the connected records.
Example: One home housing none, one or several people.
x - xNone, one or more records are connected to none, one or more records. No RelationField exists but RelationPanes are shown on both sides of the relation with related data.
Example: One person having none, one or several phone numbers.

The default relation field will popup a list of matching relations when the user changes the information in the field. This behaviour can be disabled by supplying

disablequicksearch;

in the Extra field.

1)

Float fields

The float field stores a number with a fraction part. If an invalid number is entered into a float field the Vortex will remove all invalid characters to make the data valid.

Float fields can be summed and the result shown in the bottom of the showlist. Only the rows that are shown in the current showlist are summed. To enable summation of this field use the Extra Field should contain:

showsum;

Int fields

The int field stores a number without a fraction part. If an invalid number is entered into an int field the Vortex will remove all invalid characters to make the data valid.

Int fields can be summed and the result shown in the bottom of the showlist. Only the rows that are shown in the current showlist are summed. To enable summation of this field use the Extra Field should contain:

showsum;

Text fields

The text field is a simple textbox keeping track of a String of characters.

TextArea fields

The TextArea shows a larger textbox capable of containing multiple lines and columns of text. The Extra information variables cols and rows are used to define how many rows and columns the TextArea should span.

cols:4;rows:5;

Sets the width to 4 columns, in default it will span the whole screen in details view. The height of the TextArea is set to 5 rows of text.

Relations administration

A relation connects two records to eachother. The relation is defined by referring to the tables contining the records (Table1 and Table2), names and descriptions for the relations, a relation type and the relation fields. Theese are described below. Observe that Table1 can be the same as Table2 to connect records of the same type to eachother. Several relations can refer to the same relation field as well, connecting the record to several different record types.

Table1, Table2

The tables of the related records.

Name1, Name2

The name of the relation on either side. The name is used when scripting the Vortex to refer to this relation.

Description1, Description2

Description of the relation on either side.This description will be shown in the list of related records if this is an X-side of a relation.

Type

Type of relation, 1-1, 1-x or x-x

Field1, Field2

If this is the x-side of a relation this field is left empty. Otherwise the related field is entered here.

The relations also contain an Extra field in the same manner as a normal field does. Parameters added here will control the behaviour of the relation. Valid extra parameters are:

KeywordValuesDescription
display1SearchStringThis searchstring will be applied to the list for the relation on the 1-side
display2SearchStringThis searchstring will be applied to the list for the relation on the 2-side
filter1SearchStringThis searchstring will be applied to the search-box for the relation on the 1-side
filter2SearchStringThis searchstring will be applied to the search-box for the relation on the 2-side
hide1N/AWill hide the relation from the 1-side, if this is the X-type of a relation. To hide the field on the 1-type just set the fields hidden flag to true
hide2N/AWill hide the relation from the 2-side
order10-99Will decide the order in which the tabs are displayed on the 1-side
order20-99Will decide the order in which the tabs are displayed on the 2-side

Import data

The documentation on importing and exporting data from the Vortex has been moved to here.

Exporting/Importing DBI

This function lets you export the DBI you are working on for distribution. The DBI is exported to an XML file containing all configurations, datbase structure, scripts and webservices.

Exporting DBI

If available, click the DBI Export menu option (usually under Admin/DBI). This presents a download link where you can download the DBI export.

Importing DBI

If available, click the DBI Import menu option (usually under Admin/DBI). Here you are given the option to choose a DBI export XML file to import. Notice that when importing a DBI the current DBI will be erased! If this is not a new empty DBI, make sure to backup all data before importing a new DBI.

WorkFlows

As of 1.2.1120 the Vortex has support for WorkFlows. This is discussed in the Workflows section.

Usage

General

Details

Modifying data

Update button location There are two ways to modify data in the Vortex. Either data is modified in the list, or in the details view.

In order to modify the data the currently logged in user must have Update permission on the table, field and record to update. Generally the update permission is set for the table and the fields and records in that table inherits permissions from the table. For more information regarding permissions, see Security admin.

In list editing

In list editing When modifying data in the list all dirty records are marked with bold text. When saving the modifications the records are un-marked as they are stored to the database.

To delete a record from the list simply click the red delete icon in the row of the record you want to delete. A question whether you are sure will pop up, and upon answering yes the record will be crossed over. Still, nothing is saved to the database until you click the Update button located in the topmost right corner of the list. When updating the deleted records will be removed from the list.

Detail view editing

Details view editing

To modify data in the details view simply change the information in the fields in the details view. Dirty fields will be marked with bold text, and when the information is stored to the database the fields will be un-marked. To store the data to database use the Update button located at the far bottom of the details view.

In the details view permissions can be set for the specific record. Record permissions override table permissions and will merge with field permissions. For more information about permissions see Security admin.



Connecting relations

One of the great features of the Vortex is the way it handles relations between tables. For information about how to create relations, see Relation administration.

The relation field with functionsmenu For more information about relations see Relations.

The 1-side of a relation can be connected from the details view, or from the list. Connecting existing records to a RelationField can be done in two ways. By rightclicking the information-icon on the right side of the RelationField a popup-menu will be generated. This menu contains relations tied to the field and functions to handle the RelationField. Clicking a relation will show the Relation Search Box, which contains a normal ShowList. Here you can search using the Quick Search field or Filters and use Views to choose how the information will be displayed and ordered. When the chosen record has been found, clicking on it will connect it to the active RelationField. When connecting a RelationField the Relation Search box will be closed when clicking to connect a record.

The Relation Search box

When the chosen record has been found, clicking on it will connect it to the active RelationField. As usual, nothing is written to the database before the Update button is clicked. If chosing a record already connected to another RelationField, the record will first be disconnected from the current field and then reconnected to the new RelationField. When connecting a RelationField the Relation Search box will be closed when clicking to connect a record.

Another way of connecting existing records to the RelationField is by using the QuickSearch Textbox inside the RelationField. Typing letters in the textbox will generate a list of matching posts. Clicking a post will connect the record.

Relation QuickSearch

It should be noted that, as usual, nothing is written to the database before the Update button is clicked. If chosing a record already connected to another RelationField, the record will first be disconnected from the current field and then reconnected to the new RelationField.

You can also create new records of related tables directly from the RelationField. This is done by rightclicking the information-icon of the RelationField to generate the functions popup-menu, and the clicking the New Post-option. This will generate a submenu where you can choose which relation to create a new record for (if the RelationField has more than one relation). Clicking an option in the submenu will open an empty details-window. When the new record is saved it will automatically be connected to the RelationField. If the RelationField has only one relation the submenu-step will be omitted.

Relation New Post

To connect records to the x-side of a relation, click on the magnifying glass in the bottom of the RelationPane shown only in the details view. The Relation Search Box will appear. When connecting the x-side of a relation from a RelationPane the search box will not disappear when clicking a record. You can click on multiple records before closing the box, and each record will appear in the RelationPane for the active record. New connections will be marked with a green background and a + sign on the left side of the list row. Note that nothing will be stored to the database until the Update button is clicked. If chosing a record with a previous connection using the current relation the previous connection will first be disconnected before it is reconnected to the chosen record.

To disconnect a relation from a RelationField, rightclick the information-icon of the field and then click the disconnect-option in the displayed popup-menu. To disconnect an x-siderelation, rightclick the information-icon on the left side of the RelationPane and then click the disconnect-option. From the RelationPane you will also have the choise to delete the related record by choosing the delete-option. Just like when connecting relations, nothing is stored to the database until the update-button is clicked.

Relation Menu in a RelationPane




Working with selections

In the ShowList of the Vortex there is the possibility to select multiple rows to work with simultaniously. The selection is toggled by clicking the counter, ie. the number at the beginning of each row.



Selected rows are, depending on the CSS configuration, shown in a different way than other rows. Default is by a light blue shade of the row background.

Selections can be modified by right clicking the selection modifier icon at the top of the counter-column.



Here you can select All, None or invert the current selection.

When one or many rows are selected some special rules apply.

  • Changing one field in any row will copy the change to every selected row, marking the selected rows as dirty. This applies to all types of fields.
  • Running a per-table script will run this script only for the selected rows. If no rows are selected, all currently shown rows will be passed to the script.
  • Creating a static filter based on the current selection will make the filter contain only selected rows. If no rows are selected, all currently show rows will be added to the filter.

Filters

Searching

There are two methods of searching in the Vortex. Using filters or using the quick search bar. Filters are recommended for reoccuring searches, such as listing all new orders or expired invoices. The quick search bar, which will be described in this section, is used for one-time searches to find a specific record in the list.

The simplest way to search is simply to enter the search criteria in the quick search box and pressing Enter, or clicking on the magnifying glass next to the field. All fields in the active view will be searched for the given criteria and all records having at least one field in the view matching the criteria will be shown. This type of search will perform a LIKE search and add %-wildcards to both sides of the criteria. If spaces occur in the criteria the separate words are treated as separate search criteria and by default the LIKE searches will be ANDed together. See AND / OR Searching.

For example, searching for

my biscuits

will return the results having at least one field in the active view containing the letters my and having at least one field in the active view containing the letters biscuits. An example from a test database containing a library of books:

TitleAuthorGenreShown?
Lord of the RingsJRR TolkienFantasy, AdventureNO
MythbustingLeonard BiscuitsStrangeYES
Biscuits in historySomeone elseMythologyYES
My summer vacationStina BrownDocumentaryNO

To specify which field to be searched brackets ([) are used. Surrounding a criteria with brackets and prefixing it with the field name will cause the Vortex to only search in that field for the criteria.

[title=ring]

will search the title field for occurances of the letters ring and show the matching records. Spaces within the brackets will be treated as part of the critera, so searching for

[title=of the ring]

will show all the records where the title contains the letters of the ring, spaces included. The criteria within the brackets will count as one search criteria and will be ANDed together with the other criteria in the quick search box. The result of the last search would be:

TitleAuthorGenreShown?
Lord of the RingsJRR TolkienFantasy, AdventureYES
MythbustingLeonard BiscuitsStrangeNO
Biscuits in historySomeone elseMythologyNO
My summer vacationStina BrownDocumentaryNO

To specify an exact match, surround the value part of the criteria within brackets with “”.

[title="Mythbusting"]

will show only records having the title exactly matching the phrase Mythbusting.

All of the search types can be combined into one set of search criteria, for example

myth [title=bust] [author="Leonard Biscuits"]

will search for records where at least one field in the active view contains the letters myth and the title field contains the letters bust and the author field exactly matches Leonard Biscuits.

Negating and greater/lesser searches

As of version 0.9.680b you can also negate searches, and use greater and lesser operators for searching. Theese functions can only be used when searching a specific field using [] brackets surrounding the criteria. Negating the search is done by preceeding the fieldname with the negator !.

[!myField="myTest"]
[!myField=myTest]

Here the first example will show all records where myField does not exactly match the value myTest. The second example will show all records where a LIKE search does not match %myTest%, in other words all records not containing the string myTest.

Greater than and lesser than searches are done by substituting the = sign with the relevant < or >.

[myField>4]
[myField<5]
[!myField>4]
And / Or Searching

As of version 0.9.680b you can specify wether to use AND or OR when searching using the quick search bar. By default Vortex uses AND to concatenate the search critera, but by replacing the space with a pipe | you can specify that the criteria should be OR:ed togeather.

[myField="myTest1"] [myField2="myTest2"]

will return records where myField equals myTest1 AND myField2 equals myTest2.

[myField="myTest1"]|[myField2="myTest2"]

will return records where myField equals myTest1 OR myField2 equals myTest2.

IN Search operator

As of version 0.9.680b you can use the IN operator in the quick search bar. This function can only be used when searching a specific field using [] brackets surrounding the criteria. This is done by substituting the = sign with the # sign. The value to search for can be either a comma separated list of values to match or a reference to a pre-defined SQL query to run.

[myField#(1,2,3)]

returns records where myField is either 1, 2 or 3.

[myField#(sql._table.getrecordsxxaddition;idrelation:1;uuid:testUUID)]

returns all records matching the sql._table.getrecordsxxaddition query as defined in the SQL configuration file. The arguments idrelation and uuid with the respective values 1 and testUUID will be passed to the SQL parser and used in the translation of the SQL query.

Paranthesis and table condition

As of version 0.9.761b you can use paranthesis and prefix fieldnames with table conditions. The full syntax is:

[field1=test] ([field2="abc"]|[field2="efg"])

Paranthesis are handled the intuitive way grouping conditions. The search above will be interpreded as all posts where field1=test and having field2 either abc or efg. Paranthesis can be inserted at any location in the searchstring and the Vortex will handle unmatched paranthesis by not inserting unmatched ) and appending closing paranthesis to the end of the string for unmatched (.

The table condition syntax is:

[table1:field1=test]

This search condition will only be valid if we are currently searching table1 for posts. If any other table is active, the criteria will be ignored.

Variable substitution

As of version 0.9.762b you can use variables in SearchStrings. The syntax of variables is:

[myfield={user.username}]

This will match all posts where the field myfield contains the username of the currently logged in user. The variables currently supported are:

VariableSyntaxDescription
useruser or user.[variable]Using just user returns the UUID of the current user. Supplying variable gets the value of the variable instead. Relations works using the . syntax
currentuser
activeuser
usergroupsusergroupsReturns a comma separated list of all the group ids connected to the current user. Usually used like [“UserAdmin”#({usergroups})]
currentusergroups
activeusergroups
datedate.[modifiers]Using the current date modified with modifiers. Using PHP date() function with format Y-m-d which is standard date format in the Vortex. Modifiers is a . separated list of modifiers on the form Y-10, returning 10 years prior to current date, Y+10 returning 10 years from current date or Y=2010 returning year 2010
selfself.[fieldname]|modifier:value1:value2Matches a field in the same TableRecord. Related fields can be used. The same modifiers as in this can be used.
thisthis.[fieldname]|modifier:value1:value2Matches to a field in the currently active TableRecord. Modifiers can be used to get substrings etc from the field. Related fields can be used. Modifiers currently supported are left(value1), right(value1) and mid(value1, value2) which will get a substring with the given lengths (left/right) and starting at value1 of value2 length (mid)
timetime.[modifiers]Same functionallity as date only using format Y-m-d H:i:s.

Note. The name of the field is the fieldname as it is in the database, not necessary the name shown in the list and detail view.

Views

1)
Add information about multi relations
vortex/usermanual.txt · Last modified: 2019/06/28 07:12 by hubbe