GUI reference - pascalfree/ProjectLK GitHub Wiki

This page should contain all the information necessary to create a new GUI or to modify an existing one.

• URL parsing
• Global Variables
• Helper functions
• Core Events
• Hash
• Request
• Query-Engine

It is important to know how the URL is parsed in order to know which page inside /gui will be loaded.

http://HOST/dirname/page

• dirname: Is the same as DIRNAME in your config.php file.
• page: corresponds to the name of an *.xml file inside /content (without the ending). Having only the page as a keyword in the URL, the core checks if a corresponding content file exists. If so, it loads the content.php file in the gui folder. There the keyword 'page' from the URL will be available as $plk_here->keyoption.

http://HOST/dirname/user/register/group

• dirname: see above
• user: the username or id of the logged in user (the core ignores this and uses the value from the session instead)
• register: the register id (optional)
• group: the group id (optional)

additionally there are keyword/value pairs that can be added:

• /tag/tagid
• /save/saveid
• /search/searchtext
• /word/wordid
• /edited/someid
• /group/groupid (yes, this is an alternative)
• /query/queryid
• /person/personid
• /form/formid
• /wordclass/wordclassid
• /verbquery/verbqueryid
• /without/withoutid

these can be added to the url in any order. Note: The default GUI does not use all of those keywords but the core is designed to accept them. The following 'defining' keywords can be added at the end of the URL:

• /show
• /overview
• /settings
• /add
• /edit
• /verb
• /taglist
• /export
• /import

Only the last keyword is recognised here. Now the core decides which page to load with these rules:

1. /export won't load any gui file and instead create an export *.xml file containing all words etc. of the current path to be downloaded by the user.
2. If any, the other defining keywords will load the *.php file in the gui folder with the same name as the keyword.
3. If any, the last appearing keyword of a keyword/value pair will load the *.php file named like the keyword.
4. If group is defined group.php will be loaded
5. If register is defined register.php will be loaded
6. If user is defined (if any characters are there) dashboard.php will be loaded
7. content.php is loaded with keyoption set to 'home'.

The first rule that is applicable will be used. It's important to notice, that the core will validate all ids i.e. if http://HOST/dirname/username/45 is called and there is no register with the id 45 that belongs to that user, it will be ignored and the dashboard will be loaded instead. If the *.php file to be loaded doesn't exists a 404 error page (404.php) will be shown.

$plk_here in php and plk.here in javascript is an object that contains all information about the current path. The information can be accessed by $plk_here->key and plk.here.key (or plk.here['key']), respectively.

• url: the current URL without the HOST
• login: 1 if login was successful, an error code otherwise
• nregerr: error code when user just tried to register. 1 if successful
• forgot: error code when trying to restore password. 1 if successful
• username: the username of the logged in user
• userid
• registerid
• groupid
• tagid
• saveid
• wordclassid
• wordid
• timerange: filters words by time of creation
• formid
• personid
• withoutid
• queryid
• searchid
• searchtext: a modified searchterm. Is null in the beginning.
• keyoption: contains a defining keyword the a content page
• page: name of the php file that is loaded
• gui: used GUI
• style: used theme
• language: used language
• hints: 1 if hints should be shown, 0 else
• statuscount: number of unfinished reviews
• browser: ff - Firefox, gc - Google Chrome, ie - Internet Explorer, sa - Safari, op - Opera, NULL otherwise
• mobile: 1 if user uses a mobile device

In Javascript, the values of 'plk.here' can not be changed directly. Instead these functions are used:

• plk.here.set({key:value, key:value, ...}); changes value of 'key'
• plk.here.clear([key, key, ...]); deletes the entries 'key'
• plk.here.clear(key); deletes the single entry 'key'

plk.here.set will call gui_refresh_here(key), once for every changed key, if this function exists.

$plk_la in php and plk.la in javascript contains expressions in the chosen language. To see what expressions are available open a language file in /language.

usage: $plk_la['key'] in php and plk.la.key or plk.a['key'] in javascript.

Functions are documented in detail in the code inside /core/php/utilty.php and /core/javascript/functions.js.

• $plk_here->path(level); returns the URL up to 'level'. $plk_here->path(); returns the whole URL. the levels are:

1. username
2. registerid
3. groupid
4. saveid
5. tagid
6. wordclassid
7. wordid
8. personid
9. formid
10. searchid
11. queryid
12. keyoption

• plk_util_getLanguages($prefix=''); returns an array of all installed language files (language code with $prefix)
• plk_util_getGui(); returns array of installed GUIs
• plk_util_getThemes(); returns array of available themes
• plk_util_getLangKey($expr); searches '$expr' inside the language file and returns the key.
• plk_util_iSearchArray($str, $array) returns the key of an array matching a string (case-insensitive)
• plk_util_matchArray($arraya, $arrayb) returns true if any value of the first array is also in the second one
• plk_util_rSearchArray($str, $array) recursive search of a string in a multidimesional array.
• mres($input) A shortcut for recursive mysql_real_escape_string for arrays.
• plk_util_getName($type, $id) returns the name of a type with given id, from database.
• plk_util_regExpEncode($string) regular expression encoder for mysql
• plk_util_flat($array) flaten Array
• plk_util_passGen($len) Generate Password
• plk_util_trim(&$value) trim with call by reference. Used for array_walk
• plk_util_commaArray( $string ) get comma separated, trimmed values
• plk_util_removeForbidden( &$string, $forbidden = array('\\"', '#', '+') ) remove forbidden characters
• plk_util_makeArray( &$param ) if parameter isn't an array make a single value array out of it
• q(id, add); will be explained in the chapter Query-Engine

• plk.here.path(level, params) or plk.here.path(params) where params is optional. Returns path until level (see PHP functions). Modifies URL specified by params: params = {key: value, key: value, ...}
• plk.word.validate(string) validates string. Returns 0 if all brackets in string are balanced. returns 1-6 as errorcodes.
• plk.word.errorAt(string) returns position of the first unbalanced bracket. returns -1 if no error.
• plk.util.trim(string) trims whitespaces left and right of a string.
• plk.util.clean(string) trim + removes whitespace
• plk.util.fill_array(value, len) returns array filled with 'value' of length 'len'
• plk.util.changeCase(string) toggle from uppercase to lowercase and vise versa (changes to uppercase if it was mixed)
• plk.debug.warnung(msg) writes a warning to the console if the browser supports it and DEBUG is set to 1.
• this list may be incomplete.

On some events the core will call a javascript function if this is defined. Those events and functions are:

gui_error(out) is called in case of any error. 'out' is the errormessage. If this function doesn't exist the core will show an alert instead.

gui_request_error(info) is called in case of an error during a request to the database. 'info' is an object with:

• errnum: Error code
• errname: A string describing the error
• lastquery: The last executed MySQL query (probably the reason for the error)
• errloc: Database function that caused the error

If this function is indefined gui_error(out) will be called instead combining 'info' into a string.

gui_ajaxcatch(num) will be called every time the ajax status changes. 'num' represents the status of the request:

0. right after req(...) was called
1. Created
2. Uninitialized
3. Loading
4. Loaded
5. Interactive
6. Complete
7. Success
8. called the function, that should be called after the request

Status 1-7 correspond to the Ajax.Responders of the prototype framework.

The core provides functions for checking and manipulating the URL hash.

plk.hash.onChange() must be called once when the page is loaded (<body onload="plk.hash.onChange()">). Afterwards it will modify the global variable 'here' and call gui_load_hash() whenever the hash is changed.

Note: If the browser supports the onhashchange event it is used, otherwise the hash is checked every second.

plk.hash.update() writes the contents of 'here' to the hash. First modify 'here' and then call plk.hash.update().

Note: gui_load_hash() will not be called if the hash is changed this way.

Requests are the link to the database. They allow to read and write from and to the database. All requests pass through the core and will be validated. Requests are available in php and in javascript (via ajax). The syntax is very similar in both cases:

plk_request( $function, $params = NULL )

$function is the name of the function that should be called and $params is an object containing all parameters for that function.

The functions are *.php files located in /core/database/. A Reference of the functions and their parameters will be posted here some day.

plk.req( function, params, action, passthrough )

function and params are as described in the PHP section. action is the name of the function, that will be called once the request is finished. It may have the following forms:

• action = after_functionname without brackets at the end.
• action = [before_functionname] (single value array) this function will be called before the request is sent.
• action = [before_functionname, after_functionname] functions to be called before and after the request.

The corresponding functions can take these parameters:

• after_functionname( info, params, passthrough )

• before_functionname( params, passthrough )

• info is an object filled with the response from the database.

• params is the object that has been passed to the database function.

• passthrough can be anything. It is not sent to the database function but passed as a parameter to the before- and after functions.

In addition there exists a request object:

• var = plk.reqObj( functionname, params, action, passthrough ) create the object
• plk.reqObj#addparams( params ) method to add more parameters to the object
• plk.reqObj#send( params ) method to send the request, after adding more parameters (optional).

The parameters of the object are the same as for plk.req. This object can be passed to other functions which may be useful.

The Query-Engine is the part of the core, that lets the user review (or query) their words. The GUI will decide how the review page will look like i.e. position and look of the buttons and provided information. The process, however, is controlled by the query engine directly. It will load the words, check if the input was correct etc. More information will follow.