justinvoelker / yii2-tagging
Turn delimited data into tags
Installs: 3 860
Dependents: 2
Suggesters: 0
Security: 0
Stars: 8
Watchers: 5
Forks: 6
Open Issues: 1
Type:yii2-extension
Requires
- yiisoft/yii2: *
This package is not auto-updated.
Last update: 2024-11-19 04:37:03 UTC
README
#Tagging for Yii2
Turn delimited data into tags
There are multiple extensions for brining tagging functionality into Yii but Tagging aims to be the simplest. Built for Yii2, Tagging does not use additional tables, models, or relationships to store or manage tags or how often they appear. Instead, it works with an existing field of your choosing and turns its contents into tags.
We'll use the following posts
table as an example.
Tagging includes two classes: TaggingQuery and TaggingWidget. TaggingQuery returns a php array which can be used in form's select field or as input to TaggingWidget which can display the tags as a list or tag cloud.
Keep in mind that your tags don't need to be comma-delimited. You can use practically any delimiter you like!
##Installation
###Install the extension
The preferred way to install this extension is through composer.
Either run
php composer.phar require --prefer-dist justinvoelker/yii2-tagging "*"
or add
"justinvoelker/yii2-tagging": "*"
to the require section of your composer.json
file.
Styles
Follow one of the directions below to use the styles necessary for the tag_cloud
Option 1: Manually combine stylesheets
Open your the vendors\justinvoelker\yii2-tagging\css
directory and add the styles found in tagging.css
to your own stylesheet.
Option 2: Include the delivered asset bundle
Add justinvoelker\tagging\TaggingAsset
as a dependency in your assets\AppAsset
file. It should look similar to the following:
...
public $depends = [
'yii\web\YiiAsset',
'yii\bootstrap\BootstrapAsset',
'justinvoelker\tagging\TaggingAsset',
];
...
##Usage
###TaggingQuery
To create a php array of key=>value pairs (where key is the tag and value is the frequency of that tag), use TaggingQuery:
$query = new TaggingQuery; $tags = $query ->select('tags') ->from('posts') ->getTags();
###TaggingWidget
To create a tag cloud or list, use TaggingWidget:
echo TaggingWidget::widget([ 'items' => $tags, ]);
###TaggingQuery and TaggingWidget
If necessary, you can combine the two. If you have multiple widgets on the same page that will use roughly the same set of data, simple pass the results of an initial TaggingQuery into another TaggingQuery for further limiting or ordering as follows:
$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', ]);
The above example will only use one database query but will display two TaggingWidgets. The first will be a tag cloud of tags sorted by name whereas the second will be an unordered list (ul) sorted from most to least frequent.
##Available Options
Many options are available for selecting and formatting the data and results. The following examples show which options are available. Exploring the code will give further descriptions of each option.
###TaggingQuery
Only select
and from
or an array of items
are required. If all three are specified, the items
values will be used. Note that exclude
and includeOnly
would likely not be used at the same time which is why includeOnly
is commented out in the examples below. Also commented out for this example is items
.
Since TaggingQuery extends yii\db\Query
you can use any other properties available to that class as well. While using where
may come in handy, be careful not to use properties such as distinct
which could have unintended consequences.
The following TaggingQuery would result in an array of the 50 most frequent comma-separated tags from the post table, except for the 'junk' tag, displayed alphabetically.
$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
Only items
is required.
All of the selecting, limiting, sorting, and excluding/including of tags is performed by TaggingQuery. Once a list of items is returned from TaggingQuery, it may be passed into a TaggingWidget for display.
Continuing with the previous example, the following TaggingWidget would result in the previously selected tags being displayed in a tag cloud whose text will be justified, with tags ranging in size from 14-22px, and linking to pages in the format of /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' => [], ]);