Documentation: Resourceindex

From UniLang Wiki

The resourceindex is the system that manages and lists all resources and enables users to navigate amongst them, and administrators to track and edit their entries.

Since August 2005, the Resourceindex backend migrated to mysql and the frontend, the user interface, got more unified and had a drastic makeover.

Contents

[edit]

The Resourceindex Backend

The resourceindex backend is located in /styles/loadresources.php. This script is included by any system making use of the resourceindex, most notably by the frontend.

The function loadresources is responsible for loading a set of resourceindex entries into an array and is defined as follows: 

function loadresources($collection, $sortby = "title", $sourcefilter = "", 
$targetfilter = "", $subcategory = "",$keyword =  "", $datetreshhold = "",
$exactid = "",$maxcount=20,$page=1, $activated = 1)

A dissertation on the various arguments will follow now:

  • $collection: The name of the collection/category you want to load, classical collection names are "grammar", "courses", "pronscript","vocab" but new ones can be added if necessary. $collection can be set to an empty string if you want resources from all collections, or can be set to "!links" when you resources from all categories except "links".
  • $sortby: Sort results by either "title","url","category","subcategory","date","source","target","author","id" or any other valid column according to the resourceindex table in mysql...
  • $sourcefilter: Empty for no filter, set to a language-code to only obtain entries matching the same source language
  • $targetfilter: Empty for no filter, set to a language-code to only obtain entries matching the same target language
  • $subcategory: A filter for the subcategory, to obtain matching results only
  • $keywords: A filter for keywords, to obtain matching results only
  • $datetreshhold: Can hold a string in YYYYMMDD format and only newer entries will be obtained
  • $exactid: Useful to retrieve only one resourceindex item by its ID
  • $maxcount: Number of results to return
  • $page: The page of the results (given a $maxcount of 20, 1 would correspond to retrieving entries 1-20, 2 -> 21-40, etc )
  • $activated: List only "activated" resources (non-activated resources are not for the general public)

This function will return an array (we'll call it $res here) of the following structure:

  • $res['count']: Number of entries in the array
  • $res[$number]: Gives the ID of entry number $number (between 1 and $res['count']). Which can in turn be used to retrieve any field from the resourceindex database about that entry:
  • $res[$field][$id]: Returns the given *field* for a particular *id*, $field can be any of "title","url","category","subcategory","date","source","target","author","id","batch","alliedprojectid","remark","activated","extra" or any other valid column according to the resourceindex table in mysql...


In addition to loading resources, the backend can also add, edit and delete resources using the following functions: 

function addresource($id,$category,$type, $title, $url,$author,
$subcategory = "",$source = "", $target = "", $desc = "", $printurl = "", 
$thumbnail = "", $activated = 1 , $keywords = "", $alliedprojectid = "", 
$batch = "", $date = "",$remark = "", $extra = "", $dbhandler = "",$dontclose = 0)

function editresource(...) [same arguments as addresource]

function deleteresource($id, $dbhandler = "" ,$dontclose = 0)

The arguments of addresource/editresource correspond to the various fields in the database, with the sole exception of the two last arguments. We will loop through them all:

  • $id: A unique and short name for this resource. In editresource, this will overwrite any resource with the ID mentioned. In deleteresource, this is the ID of the resource that will be deleted.
  • $category<//tt>: The category/collection this resource will belong to (see loadresources)
  • <tt>$type<tt>: An integer corresponding to the type of the resource, 1 for a normal 'static' resource, and 2 for a so-called 'dynamic' resource, where the user selects one source language from a list of source languages, and one target language from a list of target languages. (see <tt>$url for further information on how to handle this)
  • $title: The title of this resource. May be in MULTILINGUAL FORMAT (see next section)
  • $url: The URL of this resource, the URL has a specific form though:
    • For UniLang resources in any subdiretory of /resources/ you only need to mention the filename! The frontend system will automagically resolve this correctly.
    • For Wiki pages, use Wiki://Name_of_Page
    • For Sonidos del Mundo, use sdm://languagecode
    • For a Forum topic, use forum://topicnumber
    • For pages in /main/, use main://pagename.php
    • For anything else, a full http:// URL can be used
    • URLs can contain the following variables for TYPE 2 resources (see $type): {$lng1} will resolve to the language-code of the source-language the user selected. {$lng2} will resolve to the language-code of the target-language the user selected. {$mglng1} will resolve to the MediaGlyphs language-code of the source-language the user selected, {$mglng2} will resolve to the MediaGlyphs language-code of the target-language the user selected.
  • $author: The author of the resource, preferably in id:nick format, though any of the two will work to a lesser extend.
  • $subcategory: The subcategory this resource is in, can be empty if none (in fact, this is default)
  • $source: A comma seperated list of source-language-codes .. These are the languages this resource is written in
  • $target: A comma seperated list of target-language-codes .. These are the languages this resource is written for
  • $desc: A short description of this resource. May be in MULTILINGUAL FORMAT (see next section)
  • $printurl: URL to the printable version of this resource (see $url>)
  • $thumbnail: filename of the thumbnail of this resource (per definition located in /thumbnails/<tt>)
  • <tt>$activated: Integer (one or zero) indicated whether or not this resource is activated (non-activated resources will not show up in the results)
  • $keywords: Comma seperated list of keywords applicable to this resource
  • $allieprojectid: ID name of an allied project if these resource is made by, or in cooperation with, an allied project.
  • $batch: If this resource is parto f a batch, mention its batch name here (See the section on batches for more information)
  • $date: Date of this resource's entry in YYYYMMDD resource, will automatically be set to the current date if left empty, which is recommended.
  • $remark: A very short remark that will be added in red text next to the title. Could contain something like "UPDATED!" or "FIXED!"
  • $extra: Put anything user-defined in here, this field is not used by the system.

The following two arguments have nothing to do with the actual resource and will not reflect in the database:

  • $dbhandler: The Mysql-DBHANDLER, if not empty, the database won't have to be reopened (if empty, this function will create open a connection to the database and give the DBHANDLER as a return value of the function if $dontclose is set to zero (applies too all three functions))
  • $dontclose: Integer value of 0 or 1, determines whethere or not to close the database connection.

These two arguments come in handy if you have a whole set of resources to add and want to keep the connection the the database open for faster processing.

[edit]

Multilingual Format

Some fields (title, desc) support a multilingual format which allows them to contain data for multiple languages. The frontend will pick the language from the data if it's present or default the english otherwise.

The multilingual format goes like this 

// [LANGUAGECODE] text // [LANGUAGECODE] text // [LANGUAGECODE] text //

Example: 

// [en] This is an interesting course // [fr] Ceci est un cours interessant //  [es] Esto es un curso interesante //
[edit]

Batches

There are a lot of dynamic resources, like stories, phrasebooks, interactive resources, that are readded to the resourceindex automatically on a recurring basis. These are added in batches. There is a field in the resourceindex for specifying to what batch a resource belongs. And there are PHP scripts in /resourceindex/ (named makeautoindex_*.php that will scan dynamic resources and readd them to the resourceindex database. To achieve this, these scripts first call the function defined as deletebatch($batch, $dbhandler ="" ,$dontclose = 0) to delete the entier batch, and then read it.

The CRON system on the server calls the bash script /resourceindex/makeautoindex, which in turn calls the variuos PHP scripts that will regenerate resourceindex data. For entirely new kinds of dynamic resources, new such indexing scripts will have to be written. For dynamic scripts based on MediaGlyphs or Phrasebook data, no new scripts have to be written as the existing scripts will generate such data using configuration variables in /main/interactive_resourceindex.php, you will merely have to add configuration variables there (don't worry, the file is heavily commented).


[edit]

The Resourceindex Frontend

The Frontend is responsible for displaying the resourceindex data on screen, It consists out of a set of functions to do the actual displaying (/styles/resourceindex.php) which are called by the main resource browser (/main/resources.php).

In the past we had several resource-browsers and even systems that did not use the resourceindex at all. These are now obsolete cause everything is integrated into the highly flexible resourceindex. Creation of other browsers is now highly discouraged! Always use the Resourceindex! This will keep resource navigation uniform and simple yet powerful for both users and maintainers, and will help us create easy statistics, backups, etc..

The core function of the the frontend is printresources($res,$restext), where $res is the result of a loadresources() command (see the backend), and $restext is the result of a loadlanguage('resources',$lang) command (see the LANG-System.

The frontend also enables administrators to administrate the resourceindex, since also comes with a resourceindex-editor. There is a link to it on the admin page. Later on it will also be opened to all users, once the member-rights-system is in place.

Retrieved from "http://home.unilang.org/wiki3/index.php/Documentation:_Resourceindex"
Personal tools