initial import

raoul2000 · Jul 6, 2014 · 574791e · 574791e
commit 574791e
Show file tree

Hide file tree

Showing 13 changed files with 1,241 additions and 0 deletions.
diff --git a/CHANGE.md b/CHANGE.md
@@ -0,0 +1,3 @@
+version 1.0.0
+=============
+- Initial release
diff --git a/Guiders.php b/Guiders.php
@@ -0,0 +1,46 @@
+<?php
+
+namespace raoul2000\widget\guiders;
+
+use Yii;
+use yii\base\Widget;
+use yii\base\InvalidConfigException;
+use yii\helpers\Json;
+use yii\web\JsExpression;
+/**
+ * Guiders is a wrapper for the [Guiders-JS Jquery Plugin ](https://github.com/jeff-optimizely/Guiders-JS).
+ * For documentation on plugin option, please refer to https://github.com/jeff-optimizely/Guiders-JS
+ *
+ */
+class Guiders extends Widget
+{
+	/**
+	 * @var boolean show the guider after creating it.
+	 */
+	public $show = false;
+	/**
+	 * @var array options for the Guiders plugin (see https://github.com/jeff-optimizely/Guiders-JS)
+	 */
+	public $pluginOptions = [];
+
+	/**
+	 * (non-PHPdoc)
+	 * @see \yii\base\Widget::run()
+	 */
+    public function run()
+    {
+        $this->registerClientScript();
+    }
+    /**
+     * Registers the needed JavaScript and inject the JS initialization code
+     */
+    public function registerClientScript()
+    {
+    	$view = $this->getView();
+    	GuidersAsset::register($view);
+
+    	$options = empty($this->pluginOptions) ? '' : Json::encode($this->pluginOptions);
+    	$js = "guiders.createGuider($options)" .	($this->show?'.show()':'') . ';';
+    	$view->registerJs($js);
+    }
+}
diff --git a/GuidersAsset.php b/GuidersAsset.php
@@ -0,0 +1,24 @@
+<?php
+namespace raoul2000\widget\guiders;
+
+use yii\web\AssetBundle;
+
+/**
+ * @author Raoul <raoul.boulard@gmail.com>
+ */
+class GuidersAsset extends AssetBundle
+{
+	public $js = [
+		'guiders.js'
+	];
+	public $css = [
+		'guiders.css'
+	];
+	public $depends = [
+		'yii\web\JqueryAsset',
+	];
+	public function init() {
+		$this->sourcePath = __DIR__.'/assets';
+		return parent::init();
+	}
+}
diff --git a/LICENSE.md b/LICENSE.md
@@ -0,0 +1,12 @@
+Copyright (c) 2014, Raoul
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/README.md b/README.md
@@ -0,0 +1,115 @@
+yii2-guiders-widget
+==========================
+Wrapper around "Guiders JS" jQuery plugin, "*a user experience design pattern for introducing users to a web application*". 
+
+Check out the  [Home page](http://www.jeffpickhardt.com/guiders/) of the Plugin.
+
+> Please note that this extension does not provide any aditionnal feature than the one available in the wrapped plugin. 
+> It has no other dependency than the [Yii2 Framework](http://www.yiiframework.com/)
+
+Installation
+------------
+
+The preferred way to install this extension is through [composer](http://getcomposer.org/download/).
+
+Either run
+
+```
+php composer.phar require --prefer-dist raoul2000/yii2-guiders-widget "*"
+```
+
+or add
+
+```
+"raoul2000/yii2-guiders-widget": "*"
+```
+
+to the require section of your `composer.json` file.
+
+
+Usage
+-----
+This is an example no how to use this extension once it is installed. Let's create a 3 steps tour :
+
+```php
+<?php 
+
+// creates the first guider
+
+raoul2000\widget\guiders\Guiders::widget([
+	'show' => true,
+	'pluginOptions' => [
+		'buttons' => [['name' => "Next"]],
+		'description' => "<b>Guiders</b> are a user interface design pattern for introducing features " 
+			. " of software. This dialog box, for example, is the first in a series of guiders " 
+			. " that together make up a guide.",
+		'id' => "first",
+		'next' => "second",
+		'overlay' => true,
+		'title' => "Welcome to Guiders.js!",
+		'closeOnEscape' => true,
+		'xButton' => true,
+		'width' => 500
+	]
+]);
+
+
+// creates the second guider. Note that 'show' is false by default.
+
+raoul2000\widget\guiders\Guiders::widget([
+	'pluginOptions' => [
+		'buttons' => [['name' => "Next"]],
+		'description' => "This is an intresting lorem ipsum colomn or what !",
+		'id' => 'second',
+		'next' => 'third',
+		'overlay' => true,
+		'title' => "Focus",
+		'closeOnEscape' => true,
+		'xButton' => true,
+		'width' => 500,
+		'attachTo'  => '#focusHere',
+		'autoFocus' => true,
+		'highlight' => '#focusHere',
+		'position' => 6
+	]
+]);
+
+
+// creates the third guider. 
+
+raoul2000\widget\guiders\Guiders::widget([
+	'pluginOptions' => [
+		'buttons' => [
+			[
+				'name' => "Done",
+				'onclick' => new yii\web\JsExpression('function(){guiders.hideAll();}')
+			],
+			[
+				// if name is "close", "next", or "back", 
+				// onclick defaults to guiders.hideAll, guiders.next, or guiders.prev respectively)
+				'name' => 'back' 
+			],
+			[
+				'name' => 'before you leave!',
+				'onclick' => new yii\web\JsExpression('function(){alert("thanks for joining our Guiders Tour !");}')
+			]
+		],
+		'description' => "That's all folks...well not exactly. There are <b>plenty</b> of nice options to play with"
+			." so to create a nice tour. <h4>Check the Guiders-JS page</h4>",
+		'id' => "third",
+		'title' => "Welcome to Guiders.js!",
+		'closeOnEscape' => true,
+		'xButton' => true,
+		'width' => 400
+	]
+]);
+
+?>
+```
+
+For more information on the plugin options and usage, please refer to [guiders-JS@github](https://github.com/jeff-optimizely/Guiders-JS).
+
+License
+-------
+
+**yii2-guiders-widget** is released under the BSD 3-Clause License. See the bundled `LICENSE.md` for details.
diff --git a/assets/README.md b/assets/README.md
@@ -0,0 +1,125 @@
+Guiders.js (version 2.0.0)
+==========================
+
+Guiders are a user experience design pattern for introducing users to a web application.  
+
+Live Examples
+-------------
+
+Here are a couple examples hosted online.  You can also check out `README.html` for guiders in action!
+
+[http://jeffpickhardt.com/guiders/](http://jeffpickhardt.com/guiders/)
+
+[https://optimizely.appspot.com/edit#url=www.google.com](https://optimizely.appspot.com/edit#url=www.google.com)
+
+
+Set Up
+------
+
+Here is sample code for initializing a couple of guiders.  Guiders are hidden when created, unless `.show()` is method chained immediately after `.createGuider`.
+
+~~~ javascript
+guiders.createGuider({
+  buttons: [{name: "Next"}],
+  description: "Guiders are a user interface design pattern for introducing features of software. This dialog box, for example, is the first in a series of guiders that together make up a guide.",
+  id: "first",
+  next: "second",
+  overlay: true,
+  title: "Welcome to Guiders.js!"
+}).show();
+/* .show() means that this guider will get shown immediately after creation. */
+
+guiders.createGuider({
+  attachTo: "#clock",
+  buttons: [{name: "Close, then click on the clock.", onclick: guiders.hideAll}],
+  description: "Custom event handlers can be used to hide and show guiders. This allows you to interactively show the user how to use your software by having them complete steps. To try it, click on the clock.",
+  id: "third",
+  next: "fourth",
+  position: 2,
+  title: "You can also advance guiders from custom event handlers.",
+  width: 450
+});
+~~~~
+
+The parameters for creating guiders are:
+
+~~~
+attachTo: (optional) selector of the html element you want to attach the guider to
+autoFocus: (optional) if you want the browser to scroll to the position of the guider, set this to true
+buttons: array of button objects
+  {
+    name: "Close",
+    classString: "primary-button",
+    onclick: callback function for when the button is clicked
+      (if name is "close", "next", or "back", onclick defaults to guiders.hideAll, guiders.next, or guiders.prev respectively)
+   }
+buttonCustomHTML: (optional) custom HTML that gets appended to the buttons div
+classString: (optional) custom class name that the guider should additionally have
+closeOnEscape: (optional) if true, the escape key will close the currently open guider
+description: text description that shows up inside the guider
+highlight: (optional) selector of the html element you want to highlight (will cause element to be above the overlay)
+isHashable: (defaults to true) the guider will be shown auto-shown when a page is loaded with a url hash parameter #guider=guider_name
+offset: fine tune the position of the guider, e.g. { left:0, top: -10 }
+onClose: (optional) additional function to call if a guider is closed by the x button, close button, or escape key
+onHide: (optional) additional function to call when the guider is hidden
+onShow: (optional) additional function to call before the guider is shown
+overlay: (optional) if true, an overlay will pop up between the guider and the rest of the page
+position: (optional / required if using attachTo) clock position at which the guider should be attached to the html element. Can also use a description keyword (such as "topLeft" for 11 or "bottom" for 6)
+shouldSkip: (optional) if this function evaluates to true, the guider will be skipped
+title: title of the guider
+width: (optional) custom width of the guider (it defaults to 400px)
+xButton: (optional) if true, a X will appear in the top right corner of the guider, as another way to close the guider
+~~~
+
+
+Integration
+-----------
+
+Besides creating guiders, here is sample code you can use in your application to work with guiders:
+
+~~~ javascript
+guiders.hideAll(); // hides all guiders
+guiders.next();    // hides the last shown guider, if shown, and advances to the next guider
+guiders.show(id);  // shows the guider, given the id used at creation
+guiders.prev();    // shows the previous guider
+~~~
+
+You'll likely want to change the default values, such as the width (set to 400px).  These can be found at the top of `guiders.js` in the `_defaultSettings` object.  You'll also want to modify the css file to match your application's branding.
+
+Creating a multi-page tour?  If the URL of the current window is of the form `http://www.myurl.com/mypage.html#guider=foo`, then the guider with id equal to `foo` will be shown automatically.  To use this, you can set the onHide of the last guider to an anonymous function: function() { window.location.href=`http://www.myurl.com/mypage.html#guider=foo`; }
+
+
+Contributing
+------------
+Contributions are welcome! If you would like to contribute, please issue a pull request against the dev branch, not the master branch.
+
+
+Versioning
+----------
+As of version 2.0.0, Guiders.js will follow the Semantic Versioning guidelines as much as possible.
+
+Releases will follow the following format:
+
+`<major>.<minor>.<patch>`
+
+Updates will occur according to the following guidelines:
+
+* Breaking backward compatibility bumps the major (and resets the minor and patch)
+* New additions without breaking backward compatibility bumps the minor (and resets the patch)
+* Bug fixes and misc changes bumps the patch
+
+For more information on SemVer, visit [http://semver.org/](http://semver.org/).
+
+
+In Closing
+----------
+
+Guiders are a great way to improve the user experience of your web application.  If you're interested in optimizing user experience through A/B testing, check out [Optimizely](http://www.optimizely.com).  We're the people who built Guiders in the first place.
+
+If you have questions about Guiders, you can email me (Jeff Pickhardt) at `jeff+pickhardt@optimizely.com`.  Optimizely inquiries should be directed to `support@optimizely.com` or `sales@optimizely.com`.
+
+
+License
+-------
+
+Released under the [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0.html).
diff --git a/assets/changelog.txt b/assets/changelog.txt
@@ -0,0 +1,26 @@
+CHANGELOG
+
+2.0.0
+-----
+
+- Started keeping a changelog in changelog.txt. (You're reading it!)
+
+- Since this is a major change, I am incrementing the version number to 2.0.0. (Following Semantic Versioning, http://semver.org/)
+
+- Created a dev branch on GitHub. (https://github.com/jeff-optimizely/Guiders-JS/tree/dev) Contributors, issue pull requests to the dev branch so I can safely pull them without worrying about screwing up master code.
+
+- Changed the file names from guiders-(version).js and guiders-(version).css to simply guiders.js and guiders.css, so that it's easier to track changes in GitHub. If you want to know what version you have, just open the file or check guiders.version.
+
+- Upgraded jQuery from 1.51 to 1.90. It should still work with older versions of jQuery.
+
+- Use var guiders = this.guiders = {}; instead of var guiders = (function() { ... }) in order for guiders to attach to the window object more reliably. (Thanks @spmason https://github.com/spmason/Guiders-JS/commit/7229f66870701b980e98d80d1ac79cbb0016b92d#commitcomment-2506855)
+
+- Added bower support in component.json (Thanks rajkissu https://github.com/jeff-optimizely/Guiders-JS/pull/78)
+
+- Added a method: guiders.getCurrentGuider, to get the current guider. This can be useful for analytics tracking, for example.
+
+- guiders.next and guiders.prev return the value of guiders.getCurrent()
+
+- Allow creating guiders in the HTML, then creating guiders via $("#guider2").guider(options).  The options can be passed in through options or set as data-attrs on the object in the HTML. (Thanks @tarr11 https://github.com/jeff-optimizely/Guiders-JS/issues/85)
+
+- jQuery Mask support! If you include the jQuery Mask library in your site, Guiders.js will use jQuery Mask instead of the default overlay.