Advertisement
Theme Development

Adding a Custom CSS Editor to Your Theme Using ACE

by

Whenever someone downloads your theme and decides that some of the CSS isn't working for them, they usually go into style.css and manually modify the stylesheet to their liking. This isn't too hard to do, but it does present an issue when the next release of your theme is available and they decide to update.

All of their changes will then be overwritten. A great work-around is to offer a Custom CSS editor so that all the changes they make will be safely stored in the database and keeping up to date in the future will not be an issue.


The ACE Editor

ACE Editor

Anyone familiar with using a desktop IDE such as Coda, Sublime and Kimodo will be right at home within the ACE editor's interface. ACE is a web-based code editor that can easily be embedded into any web page or online app. It features syntax highlighting for over 40 languages and also includes a live code checker to help improve your code as you write.

In this tutorial, I plan on guiding you through the steps needed to get ACE installed in your theme so you can offer this great feature to your users.


Step 1: Installing ACE

The ACE editor is hosted on GitHub, but if you take a look at what you get when you download the project, you might be overwhelmed by the number of files. There are really only three files that we need and you can find them in the download package I provided through the Download link above.

  • ace.js
  • mode-css.js
  • worker-css.js

These three files need to be included in a folder named "ace". Place this folder in the root of your theme.


Step 2: The Helper File

In order to insert ACE into your theme, you need to create a helper JavaScript file that will set everything up on your page to make the ACE editor work correctly. Create a new file called "custom-css.js" with the following code and add it to the root of your theme as well.

( function( global, $ ) {
	var editor,
		syncCSS = function() {
			$( '#custom_css_textarea' ).val( editor.getSession().getValue() );
		},
		loadAce = function() {
			editor = ace.edit( 'custom_css' );
			global.safecss_editor = editor;
			editor.getSession().setUseWrapMode( true );
			editor.setShowPrintMargin( false );
			editor.getSession().setValue( $( '#custom_css_textarea' ).val() );
			editor.getSession().setMode( "ace/mode/css" );
			jQuery.fn.spin&&$( '#custom_css_container' ).spin( false );
			$( '#custom_css_form' ).submit( syncCSS );
		};
	if ( $.browser.msie&&parseInt( $.browser.version, 10 ) <= 7 ) {
		$( '#custom_css_container' ).hide();
		$( '#custom_css_textarea' ).show();
		return false;
	} else {
		$( global ).load( loadAce );
	}
	global.aceSyncCSS = syncCSS;
} )( this, jQuery );

The code above inserts the ACE editor into the page and makes sure that the CSS your users enter is also entered into the textarea field so that it can be stored in the WordPress database. There is also a check in there for IE7, which is incompatible with ACE so it will just load the basic textarea.


Step 3: Enqueueing the Files

With all the appropriate JavaScript files added, you have to hook into admin_enqueue_scripts to make sure your scripts appear on your Custom CSS editor admin page.

add_action( 'admin_enqueue_scripts', 'custom_css_scripts' );

function custom_css_scripts( $hook ) {
	if ( 'appearance_page_custom_css_admin_page_content' == $hook ) {
		wp_enqueue_script( 'ace_code_highlighter_js', get_template_directory_uri() . '/ace/ace.js', '', '1.0.0', true );
		wp_enqueue_script( 'ace_mode_js', get_template_directory_uri() . '/ace/mode-css.js', array( 'ace_code_highlighter_js' ), '1.0.0', true );
		wp_enqueue_script( 'custom_css_js', get_template_directory_uri() . '/custom-css.js', array( 'jquery', 'ace_code_highlighter_js' ), '1.0.0', true );
	}
}

Step 4: The Custom CSS Editor

Now you need to create your theme option page in the wp-admin where the Custom CSS editor will be displayed. To add a theme option page, you need to hook into the admin_menu action.

Add the following to functions.php:

add_action( 'admin_menu', 'custom_css_admin_page' );

function custom_css_admin_page() {
	add_theme_page( 'Custom CSS',  __( 'Custom CSS' ), 'edit_theme_options', 'custom_css_admin_page_content', 'custom_css_admin_page_content' );
}

You also need to register a Custom CSS settings field so you can store it in the WordPress database. To do that you need to hook into the admin_init action and use the register_settings() function.

add_action( 'admin_init', 'register_custom_css_setting' );

function register_custom_css_setting() {
	register_setting( 'custom_css', 'custom_css',  'custom_css_validation');
}

Since you've already added the option page and registered the settings, you can now create the content of your page:

function custom_css_admin_page_content() {
	// The default message that will appear
	$custom_css_default = __( '/*
Welcome to the Custom CSS editor!

Please add all your custom CSS here and avoid modifying the core theme files, since that\'ll make upgrading the theme problematic. Your custom CSS will be loaded after the theme\'s stylesheets, which means that your rules will take precedence. Just add your CSS here for what you want to change, you don\'t need to copy all the theme\'s style.css content.
*/' );
	$custom_css = get_option( 'custom_css', $custom_css_default );
	?>
	<div class="wrap">
		<div id="icon-themes" class="icon32"></div>
		<h2><?php _e( 'Custom CSS' ); ?></h2>
		<?php if ( ! empty( $_GET['settings-updated'] ) ) echo '<div id="message" class="updated"><p><strong>' . __( 'Custom CSS updated.' ) . '</strong></p></div>'; ?>

		<form id="custom_css_form" method="post" action="options.php" style="margin-top: 15px;">

			<?php settings_fields( 'custom_css' ); ?>

			<div id="custom_css_container">
				<div name="custom_css" id="custom_css" style="border: 1px solid #DFDFDF; -moz-border-radius: 3px; -webkit-border-radius: 3px; border-radius: 3px; width: 100%; height: 400px; position: relative;"></div>
			</div>

			<textarea id="custom_css_textarea" name="custom_css" style="display: none;"><?php echo $custom_css; ?></textarea>
			<p><input type="submit" class="button-primary" value="<?php _e( 'Save Changes' ) ?>" /></p>
		</form>
	</div>
<?php
}

The only thing missing is some code validation. Since you're allowing the user to insert CSS, there isn't much validation you can do but it's still smart to have this little function in place:

function custom_css_validation( $input ) {
	if ( ! empty( $input['custom_css'] ) )
		$input['custom_css'] = trim( $input['custom_css'] );
	return $input;
}

Step 5: The Front End

Adding the Custom CSS editor to the wp-admin is now taken care of, but the CSS isn't being displayed on the front end, so it isn't actually doing anything other than being stored in the database. In order to actually display the CSS on the front end, you need to hook into the wp_head action.

add_action( 'wp_head', 'display_custom_css' );

function display_custom_css() {
	?>
<style>
<?php
$custom_css = get_option( 'tango_custom_css' );
if ( ! empty( $custom_css ) ) { ?>
<style type="text/css">
	<?php
	echo '/* Custom CSS */' . "\n";
	echo $custom_css . "\n";
	?>
</style>
	<?php
}
?>

Conclusion

Many of my customers find the Custom CSS editor to be one of the best features offered in my themes. Taking the time to go through this tutorial to learn how to set one up in your own theme will benefit anyone who uses it. It's an amazing tool to help users customize your theme without having to worry about compromising their changes when future updates are released.

If you have any comments or feedback on anything you read above, please feel free to discuss it below.

Related Posts
  • Code
    Creative Coding
    Advanced Use of Attachments in WordPress: Creating Custom Queries for AttachmentsAdvanced use of attachments in wordpress 400
    This tutorial is the second in a four part series in which you'll learn some techniques for working with images in attachments in WordPress which give you advanced options.Read More…
  • Code
    Theme Development
    Custom Controls in the Theme CustomizerTheme customizer custom control 400
    In the last article, we explored the advanced controls available in the Theme Customizer, and how to implement them. We’re going to look at how to create our own custom control, allowing you to choose which Category of Posts are displayed on the home page. To get started, download version 0.6.0 of our Theme Customizer Example.Read More…
  • Code
    Theme Development
    Creating a WordPress Theme from Static HTML: Creating an Archive TemplateCreating wordpress theme from html 400
    If you've been working your way through this series, you now have a functioning theme with two page templates. The steps I've demonstrated to this point are: preparing your markup for WordPress converting your HTML to PHP and splitting your file into template files editing the stylesheet and uploading your theme to WordPress adding a loop to your index file adding meta tags, the wp_head hook and the site title and description to your header file adding a navigation menu adding widget areas to the header and sidebar adding widget areas, a colophon and the wp_footer hook to the footer file creating template files for static pages. Read More…
  • Code
    Theme Development
    Creating a WordPress Theme from Static HTML - Adding WidgetsCreating wordpress theme from html 400
    In this series, you've learned how to convert a static HTML file to a WordPress theme and edit the header file. So far you've: prepared your markup for WordPress converted your HTML to PHP and split your file into template files edited the stylesheet and uploaded your theme to WordPress added a loop to your index file added meta tags, the wp_head hook and the site title and description to your header file added a navigation menu. Read More…
  • Code
    Creative Coding
    Using WordPress for Web Application Development: Understanding Events, Actions, and FiltersApplication foundation 400
    Throughout this series, we've been taking a look at how WordPress can be used for building web applications. Up to this point, we've established that WordPress is a foundation - rather than a framework - and we've talked a bit about how we need to avoid trying to shoehorn WordPress into another type of design pattern than that of its native type.Read More…
  • Code
    Theme Development
    A Guide to the WordPress Theme Customizer: Adding a New SettingTheme customizer 400
    By now, we've taken a look at what the Theme Customizer is, how it works, and the components that are unique to it. We've even discussed how options are serialized into the database so that we may retrieve them later when using our theme. To that end, it's time for us to begin doing our own work with the Theme Customizer. In this article, we're going to take a look at transports, how they work, and the difference in their two primary methods. Additionally, we're going to introduce our own control into one of WordPress' existing sections and see how it works with the various transport models.Read More…