How to use markItUp! on a text field for full WYSIWYG editing
This tutorial will show you how to use the Pogostick Yii Extension Library to make an HTML TEXTAREA input element into a full-fledged WYSIWYG editor pretty much with very little code.
This is done using a wrapper for the very excellent markItUp! jQuery widget.
I assume you have installed the Pogostick Yii Extension Library. If you haven't please do so before you run the code below. It won't work otherwise.
Configuration
There is no configuration necessary after you have installed the psYiiExtensions library and set your path alias in your main.php configuration file.
Step 1: Create a TEXTAREA
You must create a TEXTAREA somewhere in your HTML to use the markItUp! widget. Give your TEXTAREA a unique id:
<textarea id='myTextArea' class='html' rows='10' cols='50'></textarea>
Step 2: Create your widget
Now that your form contains a TEXTAREA with a unique id ('myTextArea'), we can create our widget. This can be placed anywhere within your view, but put it at the top somewhere for easy maintenance.
CPSMarkItUpWidget::create( array( 'id' => 'myTextArea' ) );
Step 3: Enjoy!
That's all there is to it! When you refresh your page, you should see a full WYSIWYG text editor where your TEXTAREA was!
Options
Aside from the 'id' and 'name' parameters (which are in the core CWidget class, there are a four additional options for this widget.
skinToUse
The skin to use for displaying the markItUp editor. You can download skins from the markItUp web site. I have included the markItUp and simple skins with the default installation. Just place your downloaded skins in the /external/jquery-plugins/markitup/skins directory under where you installed the psYiiExtensions.
multiUseClass
If this option is set with a valid CSS class name, all TEXTAREAs on your page that have this CSS class applied to them will be converted into markItUp areas. Pretty neat eh?
settingsToUse
The NAME of the JSON settings array included with the "set". Defaults to 'mySettings'. markItUp is quite configurable and can be used to edit a variety of markup languages. To tell it how to parse and display, a settings file is used. In this file is a JSON array (which is named) of configuration options. The default name for the array variable is 'mySettings'. You can download additional settings files from the markItUp web site.
setToUse
The parse set to use. Defaults to 'html'. Again, markItUp is quite flexible and can parse a variety of formats. You can download additional parse-sets files from the markItUp web site.
Roadmap
I'm not planning on doing to much with this unless the options change or something breaks. However, I am waiting for the author to update the widget to use the jQuery UI themes. I will update this page once that occurs.
Total 4 comments:
I agree with skyblaze. No matter what I set the id value to, its always generated as "#markItUp" in the generated javascript code. Anyone have a different experience, or better yet, a workaround?
Just in case anyone else runs into this, I also had an issue getting the psYiiExtensions working. After following the documentation in the psYiiExtensions download package, I tried to use a CPSMarkItUpWidget and the page I added it to underwent some sort of epic fail. No error messages. No completion of the page. Nothing. The whole page generation just stopped dead when it encountered the source for the widget.
I dug through the psYiiExtensions code a little, and noticed that I needed to add an additional import (in addition to the ones in the documentation) in order to have Yii recognize the superclass of CPSMarkItUpWidget. Specifically, adding this to my imports in config/main.php helped:
'pogostick.widgets.jqui.*'
Hope this helps someone out there.
After further review, it seems that in version 1.0.4 of the psYiiExtensions, the id is lost when doing something like this:
CPSMarkItUpWidget::create(array('id'=>'foo'));
However, one can still create the widget like so:
CPSjQueryWidget('foo', array(), CPSMarkItUpWidget);
It would be a little nicer to use the wrapper classes, but until they are fixed (or some light is shed on what skyblaze and I are doing wrong), this will have to suffice for now.
i tried : CPSMarkItUpWidget::create( array( 'id' => 'myTextArea' ) );
but even if i specify the 'id' in the options array thc ode that i see produced by the widget is always:
/*/ 3jQuery(document).ready(function() { 4$('#markItUp').markItUp(mySettings); 5}); 6/*/ 7