Masuga Design, LLC

“MD MarkItUp […] is for people with professional, complex needs and is extremely up to the task. It's worth every penny!”– Matt Weinberg. President, Vector Media Group

Overview

Add an MD Markitup (MDMIU) custom field type so you can make use of some of the great features of Markitup! by adding custom buttons to your textareas in the ExpressionEngine control panel.

Set the default height and default text formatting of your field right on the custom field screen, just as you would with a default EE textarea.

Requirements

The scripts and files required for MDMIU to work are:

• The extension and language files (Included)
• The Markitup! script. (Included)
• The jQuery JavaScript library. (Separate download)
• The sets that you want to utilize (default, Textile, Markdown), and the basic EE skin (Included)
• If using Textile or Markdown, make sure you have the correct EE plugins installed. (Separate downloads)

Using Textile and Markdown in ExpressionEngine

In order to use either Textile or Markdown with MD Markitup, you first have to have those plugins installed. Grab the Textile plugin and the Markdown plugins and drop either or both of those in your system/plugins/ folder.

After installing the plugins, you will need to enable the plugins for each custom field for which you want them to appear. This is an easy, yet somewhat tedious process. Here is the process, assuming just the Textile plugin for now:

1. Install the Textile plugin into your system/plugins/ folder
2. Create and Submit a new custom field. It doesn’t matter if it is MDMIU or a textarea off the bat. When you create a field, the only options available under “Default Text Formatting for This Field” are None, Auto <br />, and XHTML.
3. Back at the Custom Fields screen, click on your new field to go back in and edit it.
4. You will now notice an “Edit List” link to the right of the Default Text Formatting dropdown. Click this, and click OK at the prompt (as long as you haven’t made other changes, because they will be lost).
5. You will now see a list of all your plugins. Select “Yes” next to Textile and click “Update”.
6. You will now be able to select Textile from the Text Formatting dropdown. When you do, you will see a red warning message appear above the field’s Update button.
7. If you have previous entries you would like to apply your new formatting to, check the “Update all existing weblog entries” box. If not, skip the box and just click “Update”.
8. You now have a field whose default text formatting is set to textile. When you are on a Publish or Edit page, you will be able to see Textile (as well as all the default formatting settings) in the Field Formatting dropdowns below your custom fields.

Pretty tedious, right? If you’re not averse to some basic EE core hackery, there is an article at devot:ee explaining a small hack you can do to your EE install so that (as long as you have the plugin(s) installed), you don’t have to add them manually to every field’s text formatting list. You can read the article at devot-ee.com.

There is also now a third, cleaner option if you want to install an extra extension. Stephen Lewis wrote an extension called SL Field Formatting. This extension will allow you to add Textile, Markdown, etc. to the dropdown list of field formatting types without hacking the core files or having to follow the eight-point instructions above.

Features

Markitup helps make the textareas in your ExpressionEngine control panel much more powerful and flexible.

1. Per-field buttons: Control what buttons show on what fields to help guide the user to what can and can’t be done in a field.
2. Advanced Functionality: Mark something as ‘Bold’, drop in whole chunks of HTML, make a TinyUrl with AJAX, or use Markitup! callback functions (or plugins) to do other advanced things. Create your own buttons that can do almost anything you can think of using the power of Markitup!.
3. Resize handle: Ability to easily increase the height of the viewing area while editing
4. Spellchecking: Most all the features of the regular EE textareas are available
5. Field Formatting: Change the field formatting from the default setting on a per-entry basis on your MDMIU fields.

Also:

• Nested Buttons: Nest buttons to group similar functions (such as 5 different ways to insert an image, for example), and leave more room for other buttons or a clean look above your textareas
• Moxiecode: Tie an MD Markitup field to Moxiecode’s Image and File managers for very robust image and file placement

Markitup is not a WYSIWTF WYSIWYG editor, but works much like the native EE textareas do, showing the markup itself.

Download and Installation

The following section outlines MD Markitup usage from download through configuration.

Download

After purchasing and downloading the latest version of the MDMIU package and extracting the zip file, you will have the following files:

• system/
  • extensions/
    • ext.md_markitup.php
  • language/
    • lang.md_markitup.php
• tools/
  • markitup/
    • jquery.markitup.js
    • jquery.markitup.pack.js
    • sets/
      • _shared_images/
        • (30 icon files)
      • default/
        • set.js
        • style.css
      • markdown/
        • set_markdown.js
        • style_markdown.css
      • textile/
        • set_textile.js
        • style_textile.css
    • skins/
      • simple_ee/
        • images/
          • (3 image files)
        • simple_ee.css
• README_changelog.txt

Installation

Installation is relatively straightforward. The default installation setup is shown above.

1. Copy /extensions/ext.md_markitup.php file to your /extensions/ directory in the system folder
2. Copy /language/english/lang.md_markitup.php file to your /languages/english/ directory (also in system folder)
3. Place /tools/ at the root of your site. This is the default, and it’s useful to place it there in case you’d like to use Markitup on the front end of your site as well, eg. for comments. You can change the location of this folder (or omit it altogether) – just make sure to update the path to your Markitup scripts in the extension settings
4. Open the Extension Manager (Admin → Utilities → Extensions Manager)
5. Enable Extensions if not already enabled (the global setting)
6. Enable MD Markitup
7. Click “Settings” to modify the settings (see below)

You do not need to place your markitup in a ‘tools’ folder – but this becomes very handy later on if you decide to work with Moxicode Image and File managers. You can put the support scripts for those into the ‘tools’ folder as well. More info on Moxiecode below.

Settings: Configure MD Markitup

The default settings are inserted as a convenience to you. You can modify them as you see fit. If you have your ExpressionEngine install under version control (Git, SVN, etc.) you may want to make sure all the paths are relative. If you don’t keep your MD Markitup installation in a ‘tools’ folder, modify that as needed.

Also note that the three default sets that are included in the download are different from one another in what buttons are showing. This is to give you a concrete example of how the buttons can change from set to set, as well as field to field. You have a lot of flexibility.

Extension Access

Enable MD Markitup for this site?

Yes/No

MD Markitup is MSM aware (EE’s Multiple Site Manager). Set whether MD Markitup can be used on the current site.

Scripts

jQuery Core (v1.3.x)

http://ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js

By default, this is pointed to the Google AJAX Libraries API version of jQuery. If you are using ExpressionEngine 1.6.5+ this setting will be ignored if you have activated the CP jQuery extension – which would already load jQuery for use in the control panel.

Markitup JS

/tools/markitup/jquery.markitup.pack.js

Set the path to the Markitup! script here. It will default to the ‘tools’ path you see above. If you find you are having issues with Javascript, you may want to try a non-packed version of Markitup!.

Markitup Skin

Path to the Skin Directory

/tools/markitup/skins/simple_ee/

The Simple EE skin is a modified version of the default Markitup! Simple skin, modified to better fit with the EE control panel. There are certain CSS settings included in the simple_ee skin that ensure the Publish menu flyout menu stays above any MDMIU toolbars, among other things. If you prefer to use your own skin, just direct the extension to it here.

Name of the skin’s CSS File

simple_ee.css

This is here to allow you some flexibility with what you name the CSS file for your skin, in case you don’t like the “style.css” name that is the usual name in Markitup! skins.

Markitup Sets

There are three sets included with MD Markitup.

Default Set

The Default set will be used for fields whose formatting is set to “None”, “XHTML”, and Auto <br />. The Default set is always enabled.

Path to Default Set

/tools/markitup/sets/default/

Name of Default CSS File

style.css

Name of Default JS File

style.js

Textile Set

This is only enabled for fields whose formatting is set to “Textile”.

Enable Markitup Textile?

Yes/No

Textile is enabled by default. Setting this to “No” will remove the lines from the control panel header that include the Textile set and CSS file.

Path to Textile Set

/tools/markitup/sets/textile/

Name of Textile CSS File

style_textile.css

This allows you the flexibility to rename this file, which is named “style_textile.css” by default.

Name of Textile JS File

set_textile.js

This allows you the flexibility to rename this file, which is named “set_textile.js” by default.

Show documentation link for Textile Set?

Yes/No

This will show or hide a visible link to Textile documentation.

URL for Textile styling documentation

http://thresholdstate.com/articles/4312/the-textile-reference-manual

If there is certain documentation you would rather point to, change the URL here.

Markdown Set

This is only enabled for fields whose formatting is set to “Markdown”.

Enable Markitup Markdown?

Yes/No

Markdown is turned off by default. Setting this to “Yes” will put the proper lines in the control panel header to include the Markdown set and CSS file.

Path to Markdown Set

/tools/markitup/sets/markdown/

Name of Markdown CSS File

style_markdown.css

This allows you the flexibility to rename this file, which is named “style_markdown.css” by default.

Name of Markdown JS File

set_markdown.js

This allows you the flexibility to rename this file, which is named “set_markdown.js” by default.

Show documentation link for Markdown Set?

Yes/No

This will show or hide a visible link to Markdown documentation.

URL for Markdown styling documentation

http://daringfireball.net/projects/markdown/basics

If there is certain documentation you would rather point to, change the URL here.

Misc Settings

Enable Spellchecking?

Yes/No

This will show or hide the “Check Spelling” link that shows below the MDMIU field, next to the field formatting. If you have elected to hide field formatting on a field, the “Check Spelling” link will still show if you have this setting set to “Yes”.

Check for Updates

Would you like this extension to check for updates and display them on your CP homepage?

Yes/No

MD Markitup can call home (http://masugadesign.com) and check for recent updates. For this to work, you need to install the LG Addon Updater Extension.

MD Markitup Usage

General

MDMIU fields work just like default EE textareas, except that the MIU buttons are appended to the top of the textarea and a resize handle appears at the bottom (the resize handle does not appear in Safari). Usage is as simple as setting a custom field to be an MD Markitup field.

The included sets include some basic buttons, as well as a sample nested button. You may wish to remove or hide (there are two different things) some of these buttons.

A quick Note About Multi-Line List Creation and Markitup!
Contrary to what has been mentioned in the EE forums regarding Markitup! and its failure to support multi-line list creation, you can make multiple lines into list items all at once. Select all the lines, hold Control-Shift, and click either the Ordered or Unordered list buttons. All of your line items will become list items. This is also documented on the Markitup! Documentation page, under “Keys”.

Hide and Seek with CSS, or Per-Field Buttons with Ease

It’s easy to apply only certain buttons to certain fields. See the included CSS files in the sets for examples. You will need to know the field_id of your custom field in order to target it properly.

Advanced CSS Tricks

You can also change things such as the font family, font size, background, and more on a per-field basis. It’s just a matter of further modifying the CSS file for your set(s), and targeting the correct field by its field_id. (See the example CSS included in the download.)

Utilizing Moxiecode’s Image and File Managers

MD Markitup works with Moxiecode’s Image Manager and File Manager scripts. There is some information in this post from the MD Markitup thread in the ExpressionEngine forums on making some buttons that work with the JS functions that tie MD Markitup to Moxiecode. Due to Moxiecode’s general flakiness (especially with any version of Internet Explorer), I do not officially support or endorse tying it into MD Markitup, but the helper functions are included, as well as sample buttons if you need a head start.

You will probably need to make use of the additional Moxiecode Authentication extension (separate download) written to help you stay logged in to the Moxiecode scripts while you’re in the ExpressionEngine control panel. You can download the Moxiecode Authentication extension from GitHub. Note that this is a fork of the original by Jamie Pittock that checks for the presence of any Leevi Graham extensions that also make use of Moxiecode so that no scripts get loaded twice, which would result in broken functionality in the control panel.

Support requests relating specifically to Moxiecode issues will be put at the bottom of the queue!

Troubleshooting and Support

No one likes it when something doesn’t work out of the box. I’ll be happy to help you get MD Markitup working for you on your site. The best way to get help is to .(JavaScript must be enabled to view this email address). You may want to look over the following questions first – or better yet, copy them into your email and answer them for me. That will give me the best head start to help you out. Not all of these may apply to you, but they are a collection of my most common questions to people looking for help:

1. What version and build of EE are you using?
2. Is this an MSM site, or a single site?
3. What other extensions do you have installed?
4. You have created a custom field, and selected MD Markitup as the field type?
5. Per the default install, you have a tools folder at the root of your site, with a markitup folder in it, which includes the jquery.markitup.js script? If you have deviated at all, can you explain where your files reside and what our setup is?
6. The path settings are correct for the extension if you have elected to put your Markitup script elsewhere?
7. If you’re interested in Textile or Markdown, you have downloaded those plugins and installed them?
8. Can you check to see (through Firebug or just viewing source) if jQuery is being loaded more than once on your edit tab?
9. Do you have any Solspace add-ons installed?

Release Notes

Included in the download is a file called README_changelog.txt that contains all changes per release. They are also listed here for easy reference:

Version 1.6.2 (Aug 28, 2009)

• Included the Markitup JS script in the download to eliminate the extra download step
• Helped eliminate some confusion by updating the script settings area to disable the jQuery field if the CP jQuery extension is installed
• Remove the .gitignore file from the download package.
• Simplified Activate extension by removing $PREFS global variable and making the default paths relative.
• Updated default jQuery preference to v1.3.2
• Language file updates
• Changed file structure in the download

Version 1.6.1 (Feb 27, 2009)

• Fixed a jQuery conflict that arose when installed along with some other add-ons (particularly others that also use jQuery but may be in “noconflict” mode)
• Incorporated some changes from Jay Salvat that helped fix inconsistencies when inserting images using Moxiecode’s Image editor with IE. Not 100% fixed, but that’s IE for you. (Thanks, Jay.)
• Reformatted the README.
• Removed jQuery version number when checking or setting $SESS->cache[‘scripts’][‘jquery’] = TRUE

Version 1.6.0 (Dec 29, 2008)

• Removed “Remove Toolbar” link and text explaining field formatting
• Added “simple_ee” skin to the download and altered styles for it
• Updated set JavaScript files for default, Textile, and Markdown
• Some code cleanup in the extension file
• Added settings to allow custom filenames for each set.js file, and the main skin.css file
• Changed default CSS file names, and default CP skin to ‘simple_ee’

Version 1.5.8 (Nov 19, 2008)

• Added ‘textarea’ class to the markitup textareas
• Fixed names in text_formatting_buttons function
• Added “/tools/” to the default script paths
• Put the JS/CSS for the default set before Textile, Markdown lines
• General cleanup (deleting comments, changing some “\n”‘s to NL’s)

Version 1.5.7 (Nov 19, 2008)

• Fixed typo in JS
• Added htmlspecialcharacters to textarea
• Removed version number from language file
• Added the README_changelog.txt file

Version 1.5.6

• Spellchecking is independent of show formatting
• Unobtrusively open documentation links in new window

Version 1.5.5

• Disable quicksave if field formatting changes on any of the fields
• Made spellchecking optional

Version 1.5.4

• Ability to change formatting on field-by-field basis
• Added spellcheck

Version 1.5.3

• Added hidden field for explicitly setting field formatting (EE 1.6.5 issue)

Version 1.5.2

• Added settings for more flexibility on placement
• Added check for CP jQuery.

Version 1.5.1

• Fixed a conflict with other extensions calling jQuery (i.e. LG Live Look)

Version 1.5.0

• Added LG Addon Updater compatibility
• MSM aware
• Added namespaces for multiple different instances
• System folder path fix
• Added ‘skin’ setting and updated settings page

Version 1.1.0

• Changed name to MD Markitup

Version 1.0.0

• Initial release. Sort of Beta.

License

MD Markitup is a commercial script for use with the ExpressionEngine CMS and is subject to the Commercial License Agreement.

Copyrights and Credits

Markitup! was authored by Jay Salvat and is released under a MIT/GPL license.

Fam Fam Fam Silk Icons (some of which I’ve included as default images in the download package) were created by Mark James, a web developer from Birmingham, UK.

Moxicode Image Manager and File Manager are copyright Moxiecode Systems AB.

Thanks to Jay Salvat, creator of Markitup!, for his help tweaking custom functions to help Internet Explorer suck less when inserting items into a textarea.

Thanks to Leevi Graham for creating the jQuery plugin for creating a Table of Contents, nsm-TOC (used on this page).

Miscellaneous

Further Development
There are some things this extension lacks, I’m sure. I am open to suggestions, help, snippets of code that will help make it better, and any awesome examples of how you got MDMIU to do excellent things in the ExpressionEngine Control Panel. You can leave comments on the forum thread (see below) or email me at .(JavaScript must be enabled to view this email address) with suggestions.

ExpressionEngine Forum Thread
The related EE Forum thread for MD Markitup is here.

Anything Missing?
Is there something that wasn’t covered here, or wasn’t explained well enough? Have suggestions? Please .(JavaScript must be enabled to view this email address) me and let me know what’s missing or what could be improved.