TinyMCE CSS Classes and IDs Plugin : bramus_cssextras

Overview



What is bramus_cssextras?

bramus_cssextras is a plugin for TinyMCE which enables the usage of CSS classes and CSS ids on any HTML element within TinyMCE. Together with an external CSS file, set via the TinyMCE content_css setting, bramus_cssextras bridges the (visual) gap between the content entered through TinyMCE and the actual output; as seen below.

Plain TinyMCE (1) vs. TinyMCE with content_css (2) vs. TinyMCE with content_css and bramus_cssextrast (3)
Plain TinyMCE vs. TinyMCE with content_css vs. TinyMCE with content_css and bramus_cssextras

Where content_css only lets you view the CSS styles applied on elements (and supports the setting of classes only on <a> elements), bramus_cssextras takes it to the next level by letting you set these CSS styles, based on CSS Class Selectors and CSS ID Selectors, on any element, giving the user more power on the visual representation then ever before (imagine one being able to choose 20 different classes or a handful of ids to apply on p elements with the ease of a click).

top



Screenshots & Demo

bramus_cssextras Demo (latest version)

bramus_cssextras demo - click to launch

bramus_cssextras Screenshots (outdated)

Screenshots might not say much at first, but take a peek at the status bar (bottom), the bramus_classeslist dropdown (2nd row, far left) and the block dropdown (1st row, right of the center)

Selected element : p, Class : none

Selected element : p, Class : articleStart

Selected element : li, Class (on parent!) : regular

Selected element : li, Class (on parent!) : regularLarge

Selected element : img, Class : links

Selected element : img, Class : rechts

Selected element : h3, Class : none (none available either)

A real live demo hasn't landed yet, but will rather soon ;)

top



Download

Latest Version (For use with TinyMCE 3.x)

Looking for a TinyMCE 2.x compatible version? Then download v 0.4.1 ;)

Old, archived versions

NOTE: it is suggested you use the latest version of bramus_cssextras!

Don't forget to read the License & usage and Installation/Configuration blocks on this page! ;)

top



Version History

Version 0.5.0- 2007.12.11

  • SYS : Rewrite for use with TinyMCE 3.x


Version 0.4.1 - 2007.11.22

  • FIX : When multiple CSS files are specified through content_css, load 'm all and don't break. (@see)
  • FIX : If for example p.test is defined multiple times, show “test” only once in the dropdown.


Version 0.4.0 - 2007.09.10

  • FIX : selection noclass returned "undefined" as class, now returns an empty string
  • ADD : automatic building of the bramus_cssextras_classesstring and bramus_cssextras_idsstring by parsing the content_css file


Version 0.3.3 - 2007.07.27

  • FIX : getInfo returned wrong version. Fixed + version increment.


Version 0.3.2 - 2007.07.23 - * first public release! *

  • FIX : minor change in HTML output


Version 0.3.1 - 2007.06.28 (Unreleased)

  • ADD : extra check and confirm built in to enforce uniqueness of id attributes


Version 0.3 - 2007.06.27 (Unreleased)

  • ADD : setting of ids now possible too
  • SYS : name changed from bramus_classeslist to bramus_cssextras


Version 0.2 - 2007.06.22 (Unreleased)

  • ADD : bramus_classeslist now supports “Undo Levels”
  • ADD : added a few extra comments (should be fully commented now)


Version 0.1 - 2007.06.19 (Unreleased)

  • Initial Build

top



License & usage

The script is now released under a creative commons Attribution-ShareAlike 2.5 license. Should you use the script within a commercial context please think about clicking the payPal donate button.

top



Installation/Configuration

Installation of bramus_cssextras is rather easy and can be split into 4 simple steps:

  1. Downloading and extracting the bramus_cssextras plugin
  2. Preparing your content_css file
  3. Building the bramus_cssextras_classesstring and bramus_cssextras_idsstring
    As of version 0.4.0 this step is optional!
  4. Adjusting the TinyMCE init to load the bramus_cssextras plugin

Downloading and extracting the bramus_cssextras plugin

bramus_cssextras_pathstruct.gif

  1. Go download the latest copy of bramus_cssextras
  2. Extract the contents of that archive (including the directory structure inside!) to the plugins/ directory of your TinyMCE installation
  3. You should end up with a path like this: tiny_mce/plugins/bramus_cssextras/editor_plugin.js, as seen on the right (click to enlarge)

Preparing your content_css file

Let's say we have a CSS file named mycontent.css with a few selectors in it:

CSS:
  1. a { /*...*/ }
  2. img { /*...*/ }
  3. img.floatLeft { /*...*/ }
  4. img.floatRight { /*...*/ }
  5. p { /*...*/ }
  6. p#introText { /*...*/ }
  7. h1 { /*...*/ }
  8. h2 { /*...*/ }
  9. ul { /*...*/ }
  10. ul.smallList { /*...*/ }
  11. ul.bigList { /*...*/ }

TIP: Don't forget to add !important after color declarations, as Firefox won't take them otherwise!

Now hook that CSS file to TinyMCE by using the content_css setting as described in the TinyMCE wiki, by adjusting your tinyMCE.init(); :

Make sure you link content_css to an absolute (or even full) path!

JavaScript:
  1. tinyMCE.init({
  2.     ...
  3.     // hook the content.css
  4.     content_css : "/mycontent.css",
  5.     ...
  6. });

 



Building the bramus_cssextras_classesstring and bramus_cssextras_idsstring

As of version 0.4.0 this step is not needed anymore, as bramus_cssextras automatically builds these strings by loading in the specified content_css file via an Ajax call! Leaving this section here though, in case the automatic generation should fail.

Should you however not wish to stress your server with an Ajax call on each page load (that is if a TinyMCE instance is to be started), or if the content_css file is no longer subject to change then it is suggested to settings these parameters to a manually generated value as the automatic generation (and Ajax call) then will be bypassed..

If no ids or classes need to be set, then you can either exclude the button references (see next step) or set any of these 2 parameters to an empty string (viz. "")

The hardest part of the installation/configuration is building these strings (both are built in the same manner), which tells the plugin which classes and/or which ids on which elements can be applied. Before going into details on these strings, imagine this situation:

When one is editing an unordered list (viz. an <ul>), he's actually editing the list items (<li>) contained within that <ul> and he'd probably not want to set class or id definitions on each list item separately (in case of ids this even is invalid!), but he'd want to target the <ul> itself.

Given this problem, the bramus_cssextras_classesstring and bramus_cssextras_idsstring not only tell the plugin which elements to a apply classes/ids on, but also which elements their parent element to apply certain classes/ids on.

Not wanting to rely on the CSS Descendant Selector - which is a space - and not wanting to depend on the CSS Child Selector bramus_cssextras uses a custom made system, as it works the other way around (instead of targetting children/descendants it targets parent elements) and they are no real selectors but logic structural xhtml sequences (an li always is inside an ul; why would you want to set the class of a p element to something special when you’ve got a strong element inside that p element selected?)

Don't worry if you can't follow right now, an example will make it clear:

CODE:
  1. li::ul[smallList,bigList];img::self[floatLeft,floatRight]

The string above tells bramus_cssextras that when an li is selected, the ul can have smallList or bigList applied on it as a class (when used as value for bramus_cssextras_classesstring of course)

For our CSS example file above, we'd define the bramus_cssextras_classesstring as so:

CODE:
  1. li::ul[smallList,bigList];img::self[floatLeft,floatRight]

 

The bramus_cssextras_idsstring would be defined as this:

CODE:
  1. p::self[introText]

 

After having built these string, one still has to inject them into TinyMCE by adjusting the tinyMCE.init();

JavaScript:
  1. tinyMCE.init({
  2.     ...
  3.     // hook the content.css
  4.     content_css : "/mycontent.css",
  5.    
  6.     // bramus_cssextras config
  7.     bramus_cssextras_classesstring : "li::ul[smallList,bigList];img::self[floatLeft,floatRight]",
  8.     bramus_cssextras_idsstring : "p::self[introText]",
  9.     ...
  10. });

 

top



Adjusting the TinyMCE init to load the bramus_cssextras plugin and setting the parameters

Hooking bramus_cssextras to TinyMCE is really simple and consists of 2 steps:

  1. load the plugin
  2. add the button reference

A complete (and typical) tinyMCE.init(); would look like this:

JavaScript:
  1. tinyMCE.init({
  2.  
  3.     // advanced theme, target all textareas
  4.     theme : "advanced",
  5.     mode : "textareas",
  6.  
  7.     // load the bramus_cssextras plugin
  8.     plugins : "bramus_cssextras", // note: of course you can still multiple plugins just as you're used to
  9.  
  10.     // add the bramus_cssextras dropdowns to the 2nd row of buttons
  11.     theme_advanced_buttons1_add : "separator,bramus_cssextras_classes,bramus_cssextras_ids",
  12.    
  13.     // hook the content.css
  14.     content_css : "/mycontent.css",
  15.    
  16.     // bramus_cssextras config
  17.     // NOT NEEDED IN bramus_cssextras 0.4.0+
  18.     // bramus_cssextras_classesstring : "li::ul[smallList,bigList];img::self[floatLeft,floatRight]",
  19.     // bramus_cssextras_idsstring : "p::self[introText]",
  20.  
  21.     // move the toolbar to top, left aligned
  22.     theme_advanced_toolbar_location : "top",
  23.     theme_advanced_toolbar_align : "left",
  24.     theme_advanced_statusbar_location : "bottom",
  25.  
  26.     debug : false
  27. });

top



Known Bugs

Not many :P :

  • bramus_cssextras 0.5.0+: When cancelling the setting of an id on an element when an element with that id already is present, the wrong value will remain selected in the dropdown.
  • bramus_cssextras 0.1+: Doesn't play nice with the PHP GZIP Compressor (src) - UNVERIFIED

top



Current Limitations

The only limitations in effect are those when using the nested elements (viz. li::ul) and when having elements nested inside those elements, a few examples:

  • When having an a-element (or a span-element, or a strong-element, or ...) selected, which lives inside an li, you won't be able to set the class on the ul; the selected node really must be the li (you can see which node is selected in the TinyMCE status bar!)
  • When having classes targeted on the ul (by using li::ul) and also providing classes to apply on the li's themselves (by using li::self), you'll only see the first one you've declared in the bramus_classeslist string.

top



Feedback/Help/Support

One can always leave a comment in case any questions should arise or if a bug were to be found; and one can always support me by donating me a tidbit to my paypal ;)

top



Make a donation

It certainly is no obligation but it would most certainly put a smile on my face ;) Alternatively you can support me by clicking one of the ads below.












Advertisements


About this Page

Best of Bram.us