227 lines
10 KiB
HTML
227 lines
10 KiB
HTML
<!doctype html>
|
|
<html lang="en-us">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta http-equiv="X-UA-Compatible" content="chrome=1">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<title>Star Rating by pryley</title>
|
|
<meta name="keywords" content="starrating star-rating star rating">
|
|
<meta name="description" content="A zero-dependency library that transforms a SELECT with numerical-range values (i.e. 1-5) into a dynamic star rating element.">
|
|
<meta name="author" content="Paul Ryley">
|
|
<link rel='stylesheet' href='https://fonts.googleapis.com/css?family=Open+Sans:400,700' type='text/css'>
|
|
<link rel="stylesheet" href="demo/styles.css">
|
|
</head>
|
|
<body>
|
|
<header class="page-header">
|
|
<h1 class="project-name">star-rating.js</h1>
|
|
<h2 class="project-tagline">A zero-dependency library that transforms a SELECT with numerical-range values (i.e. 1-5) into a dynamic star rating element.</h2>
|
|
<a class="button medium" href="https://github.com/pryley/star-rating.js">View on GitHub</a>
|
|
<a class="button medium" href="https://github.com/pryley/star-rating.js/zipball/master">Download .zip</a>
|
|
<a class="button medium" href="https://github.com/pryley/star-rating.js/tarball/master">Download .tar.gz</a>
|
|
</header>
|
|
|
|
<main class="main-content">
|
|
|
|
<section class="section">
|
|
<a class="badge" href="https://badge.fury.io/js/star-rating.js"><img src="https://badge.fury.io/js/star-rating.js.svg" alt="npm version" height="18"></a>
|
|
<a class="badge" href="https://github.com/pryley/star-rating.js/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" height="18"></a>
|
|
<p>For production, use the files from the <code>dist/</code> folder.</p>
|
|
</section>
|
|
|
|
<section class="section" id="section-1">
|
|
<h2>Demo</h2>
|
|
<form class="form-1">
|
|
<label for="glsr-ltr">Left to Right</label>
|
|
<div class="form-field">
|
|
<select id="glsr-ltr" class="star-rating">
|
|
<option value="">Select a rating</option>
|
|
<option value="5">Fantastic</option>
|
|
<option value="4">Great</option>
|
|
<option value="3">Good</option>
|
|
<option value="2">Poor</option>
|
|
<option value="1">Terrible</option>
|
|
</select>
|
|
</div>
|
|
<label for="glsr-rtl">Right to Left</label>
|
|
<div class="form-field" style="direction: rtl;">
|
|
<select id="glsr-rtl" class="star-rating">
|
|
<option value="">Select a rating</option>
|
|
<option value="5">Fantastic</option>
|
|
<option value="4">Great</option>
|
|
<option value="3">Good</option>
|
|
<option value="2">Poor</option>
|
|
<option value="1">Terrible</option>
|
|
</select>
|
|
</div>
|
|
<label for="glsr-custom-options">Using the "data-options" attribute to hide the tooltip and prevent the control from being cleared</label>
|
|
<div class="form-field">
|
|
<select id="glsr-custom-options" class="star-rating" data-options='{"clearable":false, "showText":false}'>
|
|
<option value="">Select a rating</option>
|
|
<option value="10">10</option>
|
|
<option value="9">9</option>
|
|
<option value="8">8</option>
|
|
<option value="7">7</option>
|
|
<option value="6">6</option>
|
|
<option value="5" selected>5</option>
|
|
<option value="4">4</option>
|
|
<option value="3">3</option>
|
|
<option value="2">2</option>
|
|
<option value="1">1</option>
|
|
</select>
|
|
</div>
|
|
<div class="button-group">
|
|
<button type="button" class="button large toggle-star-rating">Toggle Star Rating</button>
|
|
<button type="reset" class="button large secondary">Reset form</button>
|
|
</div>
|
|
</form>
|
|
</section>
|
|
|
|
<section class="section">
|
|
<h2>Installation</h2>
|
|
<p>Use one of the following methods to add the Star Rating library to your project:</p>
|
|
<ul>
|
|
<li><a href="https://github.com/pryley/star-rating.js/zipball/master">Download ZIP</a></li>
|
|
<li><code>yarn add star-rating.js</code></li>
|
|
<li><code>npm install star-rating.js</code></li>
|
|
<li><code>bower install star-rating.js</code></li>
|
|
</ul>
|
|
</section>
|
|
|
|
<section class="section">
|
|
<h2>Usage</h2>
|
|
<p>Load the <code>dist/star-rating.css</code> and <code>dist/star-rating.min.js</code> files somewhere on your page and then trigger the Star Ratie Star Rating library as follows:</p>
|
|
<div class="highlight highlight-Javascript"><pre class="alt"><code>var starRatingControls = new StarRating( '.star-rating' );</code></pre></div>
|
|
<p>To rebuild all star rating controls (e.g. after form fields have changed with ajax):</p>
|
|
<div class="highlight highlight-Javascript"><pre class="alt"><code>starRatingControls.rebuild();</code></pre></div>
|
|
<p>To fully remove all star rating controls, including all attached Event Listeners:</p>
|
|
<div class="highlight highlight-Javascript"><pre class="alt"><code>starRatingControls.destroy();</code></pre></div>
|
|
<h3>HTML markup</h3>
|
|
<p>Your SELECT option fields must have numerical values.</p>
|
|
<div class="highlight highlight-Html"><pre class="alt"><code><select class="star-rating">
|
|
<option value="">Select a rating</option>
|
|
<option value="5">Excellent</option>
|
|
<option value="4">Very Good</option>
|
|
<option value="3">Average</option>
|
|
<option value="2">Poor</option>
|
|
<option value="1">Terrible</option>
|
|
</select></code></pre></div>
|
|
</section>
|
|
|
|
<section class="section">
|
|
<h2>Options</h2>
|
|
<h3>Default options</h3>
|
|
<div class="highlight highlight-Javascript"><pre><code>{
|
|
classname: "gl-star-rating",
|
|
clearable: true,
|
|
initialText: "Select a Rating",
|
|
maxStars: 10,
|
|
showText: true,
|
|
}</code></pre></div>
|
|
<h4>classname</h4>
|
|
<blockquote>
|
|
<p>Type: <code>String</code></p>
|
|
<p>Determines the classname to use of the rendered star-rating HTMLElement. If you change this, make sure you also change the SCSS <code>$star-rating[base-classname]</code> map variable to match.</p>
|
|
</blockquote>
|
|
<h4>clearable</h4>
|
|
<blockquote>
|
|
<p>Type: <code>Boolean</code></p>
|
|
<p>Determines whether the star rating can be cleared by clicking on an already pre-selected star.</p>
|
|
</blockquote>
|
|
<h4>initialText</h4>
|
|
<blockquote>
|
|
<p>Type: <code>String</code></p>
|
|
<p>Determines the initial text when no value is selected. This has no effect if `showText` is set to false.</p>
|
|
</blockquote>
|
|
<h4>maxStars</h4>
|
|
<blockquote>
|
|
<p>Type: <code>Integer</code></p>
|
|
<p>Determines the maximum number of stars allowed in a star rating.</p>
|
|
</blockquote>
|
|
<h4>showText</h4>
|
|
<blockquote>
|
|
<p>Type: <code>Boolean</code></p>
|
|
<p>Determines whether or not the rating text is shown.</p>
|
|
</blockquote>
|
|
</section>
|
|
|
|
<section class="section">
|
|
<h2>Build</h2>
|
|
<p>star-rating.js uses <a href="https://www.npmjs.com/get-npm">npm</a> or <a href="https://yarnpkg.com/">yarn</a> to manage package dependencies and <a href="http://gulpjs.com/">gulp</a> to build from <code>src/</code>.</p>
|
|
<div class="highlight highlight-Bash"><pre><code>$ yarn
|
|
$ gulp</code></pre></div>
|
|
<p>The compiled files will be saved in the <code>dist/</code> folder.</p>
|
|
<h3>Style Customization</h3>
|
|
<p><a href="http://sass-lang.com/">Sass</a> is used to build the stylesheet so you can <code>@import</code> the <code>src/star-rating.scss</code> file to compile it directly into your Sass project.</p>
|
|
<p>Following are the default sass values for Star Rating, they are contained in a map variable.</p>
|
|
<pre><code>$star-rating-defaults: (
|
|
base-classname : 'gl-star-rating',
|
|
base-display : block,
|
|
base-height : 26px,
|
|
font-size : 0.8em,
|
|
font-weight : 600,
|
|
parent : '',
|
|
star-empty : url(../img/star-empty.svg),
|
|
star-full : url(../img/star-full.svg),
|
|
star-half : url(../img/star-half.svg),
|
|
star-size : 24px,
|
|
text-background: #1a1a1a,
|
|
text-color : #fff,
|
|
);</code></pre>
|
|
<p>To override any values with your own, simply create a new <code>$star-rating</code> map variable and include only the values you wish to change.</p>
|
|
<p><strong>Important:</strong> Make sure you define <code>$star-rating</code> before you import the <code>src/star-rating.scss</code> file:</p>
|
|
<pre><code>$star-rating: (
|
|
base-height: 32px,
|
|
star-size : 30px,
|
|
);
|
|
@import "../../node_modules/star-rating.js/src/star-rating"</code></pre>
|
|
<h3>How to change CSS style priority</h3>
|
|
<p>Sometimes an existing stylesheet rules will override the default CSS styles for Star Ratings. To solve this problem, you can specify a "parent" option in the <code>$star-rating</code> map variable. This option value should be a high priority/specificity property such as an id attribute or similar.</p>
|
|
<p>In the following example, all Star Rating css rules will begin with <code>[id^=stars]</code> which targets any id attributes that begin with "stars" (i.e. <code>#stars-1</code>):</p>
|
|
<pre><code>$star-rating: (
|
|
parent: '[id^=stars]',
|
|
);</code></pre>
|
|
<p>The CSS rule <code>.gl-star-rating { ... }</code> now becomes <code>[id^=stars] .gl-star-rating { ... }</code>.
|
|
</section>
|
|
|
|
<section class="section">
|
|
<h2>Compatibility</h2>
|
|
<ul>
|
|
<li>All modern browsers</li>
|
|
</ul>
|
|
<p>If you need to use the Star Rating library in a unsupported browser (i.e. Internet Explorer), use the <a href="https://polyfill.io">Polyfill service</a>.
|
|
</section>
|
|
|
|
<section class="section">
|
|
<h2>License</h2>
|
|
<p><a href="https://github.com/pryley/star-rating.js/blob/master/LICENSE">MIT</a></p>
|
|
</section>
|
|
|
|
</main>
|
|
|
|
<footer class="page-footer">
|
|
<p>This project is maintained by <a href="https://github.com/pryley">Paul Ryley</a></p>
|
|
</footer>
|
|
|
|
<script src="src/star-rating.js?ver=3.4.0"></script>
|
|
<script>
|
|
var destroyed = false;
|
|
var starratings = new StarRating( '.star-rating', {
|
|
onClick: function( el ) {
|
|
console.log( 'Selected: ' + el[el.selectedIndex].text );
|
|
},
|
|
});
|
|
document.querySelector( '.toggle-star-rating' ).addEventListener( 'click', function() {
|
|
if( !destroyed ) {
|
|
starratings.destroy();
|
|
destroyed = true;
|
|
}
|
|
else {
|
|
starratings.rebuild();
|
|
destroyed = false;
|
|
}
|
|
});
|
|
</script>
|
|
|
|
</body>
|
|
</html>
|