OSBib v3.0

UTF8::encodeUtf8()
$utf8String = $utf8->encodeUtf8(STRING: $string);

Properly encode a string into multi-byte UTF-8.

UTF8::decodeUtf8()
$string = $utf8->decodeUtf8(STRING: $utf8String);

Properly decode a multi-byte UTF-8 string.

UTF8::utf8_strtolower()
$utf8String = $utf8->utf8_strtolower(STRING: $utf8String);

Convert a UTF-8 string to lowercase. Where PHP has been compiled with mb_string, mb_strtolower() will be used.

UTF8::utf8_strtoupper()
$utf8String = $utf8->utf8_strtoupper(STRING: $utf8String);

Convert a UTF-8 string to uppercase. Where PHP has been compiled with mb_string, mb_strtoupper() will be used.

UTF8::utf8_substr()
$utf8String = $utf8->utf8_strtolower(STRING: $utf8String, INT $start [, INT: $length=NULL]);

Return a portion of a UTF-8 string. Where PHP has been compiled with mb_string, mb_substr() will be used.

UTF8::utf8_ucfirst()
$utf8String = $utf8->utf8_ucfirst(STRING: $utf8String);

Ensure that the first letter of a UTF-8 string is uppercase.

UTF8::utf8_strlen()
$length = $utf8->utf8_strlen(STRING: $utf8String);

Return the length of a UTF-8 string. Where PHP has been compiled with mb_string, mb_strlen() will be used.

BIBFORMAT::loadStyle()
list($info, $citation, $styleCommon, $styleTypes) = $bibformat->loadStyle(STRING: $pathToStyleFiles, STRING: $styleFile);

Parses the XML style file into raw arrays (to be further processed in BIBFORMAT::getStyle(). The four associative arrays returned are:
$info -- general information about the resource including description, language, version etc.
$citation -- in-text citation styling (not currently used).
$styleCommon -- common styling for bibliographic output such as formatting of names, title capitalisation etc.
$styleTypes -- bibliographic styling for each resource type supported by that particular style.

These last two are used in BIBFORMAT::getStyle().

BIBFORMAT::getStyle()
$bibformat->getStyle(ASSOC_ARRAY: $styleCommon, ASSOC_ARRAY: $styleTypes);

Transform the raw XML arrays from BIBFORMAT::loadStyle() into OSBib-usable arrays and perform some pre-processing.

loadStyle() and getStyle() need be called only once so can be outside your process loop.

The following should be called for each database row you wish to process.

BIBFORMAT::preProcess()
$row = $bibformat->preProcess(STRING: $type, ASSOC_ARRAY: $row);

$row -- an associative array returned from your SQL query as described in the STYLEMAP section above.
$type -- the resource type which must be one of the ones listed in $this->types in STYLEMAP.

Among other things, preProcess() supplies one of the three generic style definitions if the requested bibliographic style does not provide a definition for a specific resource type. It also handles editor/author switching for books which have only editors.

BIBFORMAT::formatNames()
$bibformat->formatNames(ASSOC_ARRAY: $creators, STRING: $nameType);

This method should be called for each type of creator the resource has. (See BIBSTYLE for an example of how this is used in WIKINDX.)

$creators -- Multi-associative array of creator names. e.g. this array might be of the primary authors (in 'creator1'):
array(
[0] => array(['surname'] => 'Grimshaw', ['firstname'] => Mark, ['initials'] => 'N', ['prefix'] => ),
[1] => array(['surname'] => 'Witt', ['firstname'] => Jan, ['initials'] => , ['prefix'] => 'de')
);
$nameType -- One of 'creator1', 'creator2', 'creator3', 'creator4' or 'creator5'. This is mapped against the resource type array in STYLEMAP to determine what type of creator we're looking at. 'creator1' is always assumed to be the primary creator whether that is an author, composer, inventor etc.

BIBFORMAT::formatTitle()
$bibformat->formatTitle(STRING: $title[, STRING: $delimitLeft, STRING: $delimitRight]);

Format the title of the resource.

$title -- The title of the resource.
$delimitLeft
$delimitRight -- Some bibliographic styles require all except the first letter of the title to be lowercased. If your bibliographic system allows users to specify groups of letters in the title that should not be lowercased (for example, proper names), then you enter the delimiters here. WIKINDX uses '{' and '}' as delimiters to protect character case.

BIBFORMAT::formatEdition()
$bibformat->formatEdition($edition);

Bibliographic styles may require the book edition number to be a cardinal or an ordinal number. If your edition number is stored in the database as a cardinal number, then it will be formatted as an ordinal number if required by the bibliographic style. If your edition number is stored as anything other than a cardinal number it will be used unchanged. The conversion is English - i.e. '3' => '3rd'. This works all the way up to infinity-1 ;-)

BIBFORMAT::formatRunningTime()
$bibformat->formatRunningTime(INT: $minutes, INT: $hours);

Running time for films, broadcasts etc.

BIBFORMAT::addItem()
$bibformat->addItem(STRING: $item, STRING: $fieldName);

Add an item to the internal $item array in BIBFORMAT. Use this to add elements of your resource to the $item array that do not require special formatting with the methods above. If it's not added, it won't be displayed. You'll notice a use of this in the example BIBSTYLE. for the URL of a resource. If you don't need to do your own special formatting, it's far easier to useaddAllOtherItems() below.

BIBFORMAT::addAllOtherItems()
$bibformat->addItem(ASSOC_ARRAY: $row);

Add all remaining items to the internal $item array in BIBFORMAT. Use this to add elements of your resource to the $item array that do not require special formatting with the methods above. If it's not added, it won't be displayed.

If you do not intend to use STYLEMAPBIBTEX, the following is a rough order of events within the loop described above. It's a general outline of what happens in BIBSTYLE as used by WIKINDX:

// Instantiate the BIBFORMAT class and initialize various parameters
include_once("core/styles/BIBFORMAT.php");
$bibformat = new BIBFORMAT();
list($info, $citation, $styleCommon, $styleTypes) = $bibformat->loadStyle("styles/bibliography/", "APA");
$bibformat->getStyle($styleCommon, $styleTypes);

After loading $bibformat->getStyle(), you can set some localisation for months and other variables. For example (these settings are the default):

	  		$bibformat->longMonth = array(
				1	=>	'January',
				2	=>	'February',
				3	=>	'March',
				4	=>	'April',
				5	=>	'May',
				6	=>	'June',
				7	=>	'July',
				8	=>	'August',
				9	=>	'September',
				10	=>	'October',
				11	=>	'November',
				12	=>	'December',
			);
		$bibformat->shortMonth = array(
				1	=>	'Jan',
				2	=>	'Feb',
				3	=>	'Mar',
				4	=>	'Apr',
				5	=>	'May',
				6	=>	'Jun',
				7	=>	'Jul',
				8	=>	'Aug',
				9	=>	'Sep',
				10	=>	'Oct',
				11	=>	'Nov',
				12	=>	'Dec',
			);

The title/subtitle separator can be set as:

		$citeformat->titleSubtitleSeparator = ": ";

// process loop starts here:
// Get the resource type ('book', 'journal_article', 'artwork' etc.)
$resourceType = $row['type'];
$row = $bibformat->preProcess($resourceType, $databaseRow);
// PreProcessing may change the value of $resourceType so get it back!
$resourceType = $bibformat->type;
// Add various resource elements to the BIBFORMAT::item array that require special processing and formatting
1. Creator names
2. Resource title
3. Resource edition
4. Resource pages
5. Resource date
6. Resource running time
7. Add the URL creating a hyperlink for web browser display
// Add all the other elements of the resource to BIBFORMAT::item array
$bibformat->addAllOtherItems($row);
// Finally, get the formatted resource string ready for printing to the web browser or exporting to RTF, OpenOffice or plain text
$string = $bibformat->map();
// process loop ends here

If you are using STYLEMAPBIBTEX for reasons described in the sections above, then the following is a rough order of events within the loop described above (with an example bibtex array supplied).

// Instantiate the BIBFORMAT class and initialize various parameters
include_once("core/styles/BIBFORMAT.php");
$bibformat = new BIBFORMAT(FALSE, TRUE);
list($info, $citation, $styleCommon, $styleTypes) = $bibformat->loadStyle("styles/bibliography/", "APA");
$bibformat->getStyle($styleCommon, $styleTypes);

// process loop starts here:
// $resourceArray must be an array of all the elements in the resource where the key names are valid, lowercase BibTeX field names. e.g.:
$resourceArray = array(
'author' => 'Grimshaw, Mark and Boulanger, Christian',
'title' => 'How Bibliographies Ruined our Lives',
'year' => '2005',
'volume' => '20',
'number' => '4',
'journal' => 'Journal of Mundane Trivia',
'pages' => '42--111',
'howpublished' => "\url{http://bibliophile.sourceforge.net}",
);
// Get the resource type ('book', 'article', 'inbook' etc.)
$resourceType = 'misc';
// In this case, BIBFORMAT::preProcess() adds all the resource elements automatically to the BIBFORMAT::item array...
$bibformat->preProcess($resourceType, $resourceArray);
// Finally, get the formatted resource string ready for printing to the web browser or exporting to RTF, OpenOffice or plain text
$string = $bibformat->map();
// process loop ends here

The following is a rough order of events you will need to set up and is a general outline of what happens in CITESTYLE as used by WIKINDX. Anything with $this->citeformat you should not change and should be very careful to position such variables in the code as WIKINDX uses them:

// Instantiate the CITEFORMAT class and initialize various parameters
include_once("core/styles/CITEFORMAT.php");
$citeformat = new CITEFORMAT();
list($info, $citation, $styleCommon, $styleTypes) = $citeformat->loadStyle("styles/bibliography/", "APA");
$citeformat->getStyle($styleCommon, $styleTypes);

After loading $citeformat->getStyle(), you can set some localisation for months and other variables. For example (these settings are the default):

	  		$citeformat->longMonth = array(
				1	=>	'January',
				2	=>	'February',
				3	=>	'March',
				4	=>	'April',
				5	=>	'May',
				6	=>	'June',
				7	=>	'July',
				8	=>	'August',
				9	=>	'September',
				10	=>	'October',
				11	=>	'November',
				12	=>	'December',
			);
		$citeformat->shortMonth = array(
				1	=>	'Jan',
				2	=>	'Feb',
				3	=>	'Mar',
				4	=>	'Apr',
				5	=>	'May',
				6	=>	'Jun',
				7	=>	'Jul',
				8	=>	'Aug',
				9	=>	'Sep',
				10	=>	'Oct',
				11	=>	'Nov',
				12	=>	'Dec',
			);

Two forms of possessive (for creator names) and 'et al.' equivalent can be set as:

		$citeformat->possessive1 = "'s"; // Set to FALSE if not used
		$citeformat->possessive2 = "s"; // Set to FALSE if not used
		$citeformat->textEtAl = "et al.";

// start() is the method called externally that starts the whole process:
1. Parse the input text for citations tags. WIKINDX uses BBCode-like [cite]....[/cite] tags that hold the unique ID from the database for the resource being cited in addition to any page numbers. Text prior to citation tags and within the citation tags are captured into two separate arrays.
2. Store the resource IDs from the citation tag in an array.
3. For these resource IDs, get the raw bibliographic data from the database and place this into a multi-dimensional array keyed by the resource's ID. Each element of this array should be an array in the same format as the array you use in BIBSTYLE or equivalent class (it will later be sent one array at a time to BIBSTYLE::process() within CITEFORMAT) -- the resource type (book, journal article etc.) is also required. The order you get data from the database in is important as it used for citation disambiguation.
4. Loop through the captured text formatting the resource title, creators, publication year and pages storing these in various $this->citeformat arrays.
5. Run $this->citeformat->process() to process the citations.
6. Finally, gather the appended bibliography formatted for either in-text or endnote-style citations and return the formatted text block.
// start() ends here