Skip to content

Commit

Permalink
Merge pull request #1 from UB-Heidelberg/issue-100
Browse files Browse the repository at this point in the history 
Add possibility to include affixes in lambda functions, Issue #100
  • Loading branch information
@nongenti
nongenti authored Sep 22, 2021
2 parents afdfbfd + 1939c82 commit f1b408b
Show file tree
Hide file tree
Showing 3 changed files with 81 additions and 28 deletions.
60 changes: 38 additions & 22 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# citeproc-php #
[![Latest Stable Version](https://poser.pugx.org/seboettg/citeproc-php/v/stable)](https://packagist.org/packages/seboettg/citeproc-php)
[![Total Downloads](https://poser.pugx.org/seboettg/citeproc-php/downloads)](https://packagist.org/packages/seboettg/citeproc-php/stats)
[![Latest Stable Version](https://poser.pugx.org/seboettg/citeproc-php/v/stable)](https://packagist.org/packages/seboettg/citeproc-php)
[![Total Downloads](https://poser.pugx.org/seboettg/citeproc-php/downloads)](https://packagist.org/packages/seboettg/citeproc-php/stats)
[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://opensource.org/licenses/MIT)
[![Build Status](https://scrutinizer-ci.com/g/seboettg/citeproc-php/badges/build.png?b=master)](https://scrutinizer-ci.com/g/seboettg/citeproc-php/build-status/master)
[![Code Coverage](https://scrutinizer-ci.com/g/seboettg/citeproc-php/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/seboettg/citeproc-php/code-structure/master/code-coverage/src/)
Expand Down Expand Up @@ -95,8 +95,8 @@ If you have trouble using composer you will find further information on [https:/

## How to use citeproc-php ##

citeproc-php renders bibliographical metadata into html formatted citations or bibliographies using a stylesheet which defines the
citation rules.
citeproc-php renders bibliographical metadata into html formatted citations or bibliographies using a stylesheet which defines the
citation rules.


### Get the metadata of your publications ###
Expand All @@ -108,42 +108,42 @@ $ mkdir mycslproject
$ cd mycslproject
```

First, you need json formatted metadata array of publication's metadata. There are a lot of services that supports CSL exports. For instance [BibSonomy](https://www.bibsonomy.org), [Zotero](https://www.zotero.org/), [Mendeley](https://www.mendeley.com/).
First, you need json formatted metadata array of publication's metadata. There are a lot of services that supports CSL exports. For instance [BibSonomy](https://www.bibsonomy.org), [Zotero](https://www.zotero.org/), [Mendeley](https://www.mendeley.com/).
If you don't use any of these services, you can use the following test data for a first step.

```javascript
[
{
"author": [
{
"family": "Doe",
"given": "James",
"family": "Doe",
"given": "James",
"suffix": "III"
}
],
"id": "item-1",
],
"id": "item-1",
"issued": {
"date-parts": [
[
"2001"
]
]
},
"title": "My Anonymous Heritage",
},
"title": "My Anonymous Heritage",
"type": "book"
},
{
"author": [
{
"family": "Anderson",
"family": "Anderson",
"given": "John"
},
},
{
"family": "Brown",
"family": "Brown",
"given": "John"
}
],
"id": "ITEM-2",
],
"id": "ITEM-2",
"type": "book",
"title": "Two authors writing a book"
}
Expand Down Expand Up @@ -176,15 +176,15 @@ echo $citeProc->render(json_decode($data), "citation");
Since version 2.1 you have also the possibility to apply a filter so that just specific citations appear.

```php
<p>This a wise sentence
<p>This a wise sentence
<?php echo $citeProc->render($data, "citation", json_decode('[{"id":"item-1"}]')); ?>.</p>
<p>This is the most wise setence
<p>This is the most wise setence
<?php echo $citeProc->render($data, "citation", json_decode('[{"id":"item-1"},{"id":"ITEM-2"}]')); ?>.</p>
```

### Bibliography-specific styles using CSS ###

Some CSL stylesheets use bibliography-specific style options like hanging indents or alignments. To get an effect of these options you can render separated Cascading Stylesheets using CiteProc.
Some CSL stylesheets use bibliography-specific style options like hanging indents or alignments. To get an effect of these options you can render separated Cascading Stylesheets using CiteProc.
You have to insert these styles within the `<head>` tag of your html output page.

```php
Expand Down Expand Up @@ -282,11 +282,11 @@ $citeProc = new CiteProc($style, "en-US", $additionalMarkup);
You can also use custom Lambda Functions in order to enrich citations with additional HTML markup.
If you want to restrict citeproc-php to use a custom Lambda Function either for bibliographies or citations, or you want to apply different
If you want to restrict citeproc-php to use a custom Lambda Function either for bibliographies or citations, or you want to apply different
functions for both, you can define the array as follows:
```php
<?php
<?php
$additionalMarkup = [
"bibliography" => [
"author" => $authorFunction,
Expand All @@ -313,13 +313,29 @@ $citeProc = new CiteProc($style, "en-US", $additionalMarkup);
In this example each entry of the bibliography gets an anchor by its `id` and the citation (in Elsevier-Vancouver style [1]) gets an URL with a fragment by its `id`. Hence, every citation mark gets a link to its entry in the bibliography.
Further examples you will find in the example folder.
To include affixes in a lambda function, you can define the array as follows:
```php
<?php
$additionalMarkup = [
"title" => array(
'function' => $titleFunction,
'affixes' => TRUE),
"author" => array(
'function' => $authorFunction,
'affixes' => TRUE)
];
$citeProc = new CiteProc($style, "en-US", $additionalMarkup);
?>
```
### Good to know ###
* A custom Lambda Function must have two parameters (`function ($item, $renderedValue) { ... }`) in their signature and must return a string.
* The 1st parameter of a custom Lambda Function is the item (either a citation item or a name item. Both of type `\stdClass`). The 2nd parameter is the rendered result of the associated item.
* Custom Lambda Functions may be applied on all Standard Variables (according to the [CSL specification](http://docs.citationstyles.org/en/1.0.1/specification.html#standard-variables)).
* Custom Lambda Functions may be applied on all Name Variables (according to the [CSL specification](http://docs.citationstyles.org/en/1.0.1/specification.html#name-variables)). Be aware, just one name item will passed as parameter instead of the full citation item.
* Custom Lambda Function for Number Variables or Date Variables will be ignored.
* ```csl-entry``` is not a valid variable according to the CSL specifications. citeproc-php use ```csl-entry``` to hook in and apply a custom Lambda Function after a whole citation item or bibliography entry is rendered.
* ```csl-entry``` is not a valid variable according to the CSL specifications. citeproc-php use ```csl-entry``` to hook in and apply a custom Lambda Function after a whole citation item or bibliography entry is rendered.
## Contribution ##
You want to contribute to citeproc-php? Follow these [instructions](CONTRIBUTING.md)!
Expand Down
14 changes: 10 additions & 4 deletions src/Rendering/Text.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,9 @@ public function render($data, $citationNumber = null)
if (CiteProc::getContext()->getRenderingState()->getValue() === RenderingState::SUBSTITUTION) {
unset($data->{$this->toRenderTypeValue});
}
$renderedText = $this->applyAdditionalMarkupFunction($data, $renderedText);
if (!CiteProcHelper::isUsingAffixesByMarkupExtentsion($data, $this->toRenderTypeValue)) {
$renderedText = $this->applyAdditionalMarkupFunction($data, $renderedText);
}
break;
case 'macro':
$renderedText = $this->renderMacro($data);
Expand All @@ -125,7 +127,7 @@ public function render($data, $citationNumber = null)
$renderedText = !empty($term) ? $this->applyTextCase($term, $lang) : "";
}
if (!empty($renderedText)) {
$renderedText = $this->formatRenderedText($renderedText);
$renderedText = $this->formatRenderedText($data, $renderedText);
}
return $renderedText;
}
Expand Down Expand Up @@ -239,13 +241,17 @@ private function renderVariable($data, $lang)
}

/**
* @param $renderedText
* @param $data
* @param $renderedText
* @return string
*/
private function formatRenderedText($renderedText)
private function formatRenderedText($data, $renderedText)
{
$text = $this->format($renderedText);
$res = $this->addAffixes($text);
if (CiteProcHelper::isUsingAffixesByMarkupExtentsion($data, $this->toRenderTypeValue)) {
$res = $this->applyAdditionalMarkupFunction($data, $res);
}
if (!empty($res)) {
$res = $this->removeConsecutiveChars($res);
}
Expand Down
35 changes: 33 additions & 2 deletions src/Util/CiteProcHelper.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,13 +27,21 @@ public static function applyAdditionMarkupFunction($dataItem, $valueToRender, $r
{
$markupExtension = CiteProc::getContext()->getMarkupExtension();
if (array_key_exists($valueToRender, $markupExtension)) {
$function = $markupExtension[$valueToRender];
if (is_array($markupExtension[$valueToRender]) && array_key_exists('function', $markupExtension[$valueToRender])) {
$function = $markupExtension[$valueToRender]['function'];
} else {
$function = $markupExtension[$valueToRender];
}
if (is_callable($function)) {
$renderedText = $function($dataItem, $renderedText);
}
} elseif (array_key_exists($mode = CiteProc::getContext()->getMode(), $markupExtension)) {
if (array_key_exists($valueToRender, $markupExtension[$mode])) {
$function = CiteProc::getContext()->getMarkupExtension()[$mode][$valueToRender];
if (is_array($markupExtension[$mode][$valueToRender]) && array_key_exists('function', $markupExtension[$mode][$valueToRender])) {
$function = $function = CiteProc::getContext()->getMarkupExtension()[$mode][$valueToRender]['function'];
} else {
$function = CiteProc::getContext()->getMarkupExtension()[$mode][$valueToRender];
}
if (is_callable($function)) {
$renderedText = $function($dataItem, $renderedText);
}
Expand All @@ -54,4 +62,27 @@ public static function cloneArray(array $array)
}
return $newArray;
}

/**
* @param stdClass $dataItem the actual item
* @param string $valueToRender value the has to apply on
* @return bool
*/
public static function isUsingAffixesByMarkupExtentsion($dataItem, $valueToRender)
{
$markupExtension = CiteProc::getContext()->getMarkupExtension();
if (array_key_exists($valueToRender, $markupExtension)) {
if (is_array($markupExtension[$valueToRender]) && array_key_exists('affixes', $markupExtension[$valueToRender])) {
return $markupExtension[$valueToRender]['affixes'];
}
} elseif (array_key_exists($mode = CiteProc::getContext()->getMode(), $markupExtension)) {
if (array_key_exists($valueToRender, $markupExtension[$mode])) {
if (is_array($markupExtension[$mode][$valueToRender]) && array_key_exists('affixes', $markupExtension[$mode][$valueToRender])) {
return CiteProc::getContext()->getMarkupExtension()[$mode][$valueToRender]['affixes'];
}
}
}

return FALSE;
}
}

0 comments on commit f1b408b

Please sign in to comment.