README

#Yii2的标签功能

将分隔数据转换为标签

虽然有多款扩展可以将标签功能引入Yii，但Tagging旨在保持最简单。为Yii2构建的Tagging不需要额外的表、模型或关系来存储或管理标签或它们的出现频率。相反，它使用您选择的现有字段，并将其内容转换为标签。

以下我们将使用以下posts表作为示例。

Tagging包括两个类：TaggingQuery和TaggingWidget。TaggingQuery返回一个PHP数组，可以在表单的选择字段中使用，或作为输入到TaggingWidget，后者可以显示标签列表或标签云。

请记住，您的标签不需要以逗号分隔。您可以使用几乎任何您喜欢的分隔符！

##安装

###安装扩展

安装此扩展的首选方式是通过composer。

运行以下命令之一：

php composer.phar require --prefer-dist justinvoelker/yii2-tagging "*"

或

"justinvoelker/yii2-tagging": "*"

将其添加到您的composer.json文件的require部分。

样式

按照以下任一方向使用标签云所需的样式：

选项1：手动合并样式表

打开vendors\justinvoelker\yii2-tagging\css目录，并将tagging.css中的样式添加到您自己的样式表中。

选项2：包含提供的资源包

在您的assets\AppAsset文件中将justinvoelker\tagging\TaggingAsset作为依赖项添加。它应该看起来像以下内容

...
public $depends = [
    'yii\web\YiiAsset',
    'yii\bootstrap\BootstrapAsset',
    'justinvoelker\tagging\TaggingAsset',
];
...

##使用方法

###TaggingQuery

要创建一个键=>值对的PHP数组（其中键是标签，值是该标签的出现频率），请使用TaggingQuery

$query = new TaggingQuery;
$tags = $query
    ->select('tags')
    ->from('posts')
    ->getTags();

###TaggingWidget

要创建标签云或列表，请使用TaggingWidget

echo TaggingWidget::widget([
    'items' => $tags,
]);

###TaggingQuery和TaggingWidget

如果需要，您可以结合使用这两个类。如果您在同一页面上有多个将使用类似数据集的widget，简单地将初始TaggingQuery的结果传递给另一个TaggingQuery进行进一步的限制或排序，如下所示

$query = new TaggingQuery;

$tagsA = $query
    ->select('tags')
    ->from('posts')
    ->displaySort(['name' => SORT_ASC])
    ->getTags();
echo TaggingWidget::widget([
    'items' => $tagsA,
    'format' => 'cloud',

$tagsB = $query
    ->items($tagsA)
    ->displaySort(['freq' => SORT_DESC])
    ->getTags();
echo TaggingWidget::widget([
    'items' => $tagsB,
    'format' => 'list',
]);

上述示例将仅使用一个数据库查询，但将显示两个TaggingWidgets。第一个将按名称排序的标签云，而第二个将按频率从高到低排序的无序列表（ul）。

##可用选项

有许多选项可用于选择和格式化数据及其结果。以下示例显示了哪些选项可用。探索代码将给出每个选项的进一步描述。

###TaggingQuery

仅需要select和from或一个items数组。如果指定所有三个，则将使用items值。请注意，exclude和includeOnly可能不会同时使用，这就是为什么以下示例中的includeOnly被注释掉。此外，此示例中注释掉了items。

由于TaggingQuery扩展了yii\db\Query，因此您还可以使用该类提供的任何其他属性。虽然使用where可能会有所帮助，但请小心不要使用如distinct之类的属性，这可能会导致意外的后果。

以下TaggingQuery会返回从帖子表中提取的50个最常出现的以逗号分隔的标签数组，不包括'垃圾'标签，并按字母顺序显示。

$query = new TaggingQuery;
$tags = $query
    // used to refine an existing list
    //->items($existingTaggingQueryResults)
    // field that contains the desired tags
    ->select('tags')
    // table to select from
    ->from('post')
    // delimiter (default: `,` (comma))
    ->delimiter(',')
    // number of tags to display (omit for all tags)
    ->limit(50)
    // order used when a limit is being applied
    ->limitSort(['freq' => SORT_DESC, 'name' => SORT_ASC])
    // order of the resulting list
    ->displaysort(['name' => SORT_ASC])
    // array of tags to be excluded
    ->exclude(['junk'])
    // array of tags to be included (all other omitted)
    //->includeOnly(['feature', 'special'])
    // return the array of tag=>frequency pairs
    ->getTags();

###TaggingWidget

只需要items即可。

所有选择、限制、排序以及排除/包含标签的操作都由TaggingQuery执行。一旦从TaggingQuery返回了项目列表，它可以传递给TaggingWidget进行显示。

继续上一个示例，以下TaggingWidget将导致之前选中的标签以标签云的形式显示，其文本将进行居中处理，标签大小在14-22px之间，并链接到格式为/index.php?r=post/index&tag=TAGNAME的页面。

echo TaggingWidget::widget([
    // TaggingQuery results
    'items' => $tags,
    // smallest tag size (default: 14)
    'smallest' => '14',
    // largest tag size (default: 22)
    'largest' => '22',
    // unit for tag sizes (default: px)
    'unit' => 'px',
    // display format of 'cloud', 'ul', or 'ol' (default: cloud)
    'format' => 'cloud',
    // url for links (omit for no link)
    'url' => ['post/index'],
    // parameter to be appended to url with tag
    'urlParam' => 'tag',
    // options applied to the list
    'ulOptions' => ['style' => 'text-align:justify'],
    // options applied to the list item
    'liOptions' => [],
    // options applied to the link (if present)
    'linkOptions' => [],
]);