YOOtheme Pro is here! The best WordPress and Joomla theme. Learn more

Create a new Widget Style

Create a new Style

You're able to add your own individual styles for a widget, if you want to customize the appearance.

Lets say you want to add a custom style to the slideshow widget. Just go to the folder /widgets/slideshow/styles, copy an existing style you want to customize and give it a unique name.

In the Widgetkit manager you should be able to select your new created style.

Now we take a closer look at the template.php, style.css, rtl.css and config.xml in your new style folder.

Style Configuration

This config.xml extends the default configuration of the widget. It defines the name of the style, the available content fields for the style and all your custom style settings.

Define a Name

First give your new style a unique name. In this case we name it my_style.

<?xml version="1.0" encoding="utf-8"?>
<style name="my_style" label="My Style">
...
</style>
Please make sure that the style folder itself is also named the same like your style. In this case my_style.

Define Content Fields

You can define which content field should be available for each item of the widget style. In this case we have an item title, a description and a caption.

<?xml version="1.0" encoding="utf-8"?>
<style name="my_style" label="My Style">
<fields>
	<field type="title" name="title" label="Title" description="" />
	<field type="html" name="content" label="Content" description="" />
	<field type="textarea" name="caption" label="Caption" description="" class="small" />
</fields>
</style>

Each field is of a specific type like a text or textarea. Here is a list of the most useful types:

  • title - This is a special input field which should always used for the item title.
  • html - This is a textarea element which loads an WYSIWYG editor if available.
  • textarea - A simple textarea.
  • text - A simple input field.
  • location - Allows you to pick coordinates with Google Maps.

Define new Settings

Last but not least you can define settings which will be available in the widget administration in the settings box when using this style. In this case we define a radio button which allows to enable or disable the captions.

<?xml version="1.0" encoding="utf-8"?>
<style name="my_style" label="My Style">
<fields>
	<field type="title" name="title" label="Title" description="" />
	<field type="html" name="content" label="Content" description="" />
	<field type="textarea" name="caption" label="Caption" description="" class="small" /></fields>
</fields>
<settings>
<setting name="captions" label="Captions" type="radio" default="1">
	<option value="1">Show</option>
	<option value="0">Hide</option>
</setting>
</settings>
</style>

Again, settings are of a specific type like a lists or radio buttons. Here is a list of the most useful types:

  • list - A simple select box with options.
  • radio - Radio buttons with options.
  • text - A simple input field.

Templating

The template.php contains all the logic and generates the markup for your style. You can access all the fields and settings you defined in the the config.xml.

So how do we access our new content field and setting? Take a look at the following code example, this should make it clear.

<?php
	$widget_id  = $widget->id.'-'.uniqid();
	$settings   = $widget->settings;
?>

<div id="slideshow-<?php echo $widget_id; ?>" class="mystyle">

	<?php foreach ($widget->items as $key => $item) : ?>
	<article>

		<?php echo $item['content']; ?>
		
		<?php if($settings['captions']): ?>
			<div class="caption"><?php echo $item["caption"];?></div>
		<?php endif;?>

	</article>
	<?php endforeach; ?>
		
</div>

<script type="text/x-widgetkit" data-widget="slideshow" data-element="#slideshow-<?php echo $widget_id; ?>">
	<?php echo json_encode($settings); ?>
</script>

You'll get always access to the $widget object that contains all the needed information to generate your markup.

Style CSS

The style.css and rtl.css will be loaded by Widgetkit if they exist in the style directory. In the style.css you can define your custom CSS style for the HTML markup of your style. The rtl.css should contain all fallbacks for right to left languages.

You should always give your custom styles a unique class name, like in the example above.

<div class="mystyle">
	...
<div>

So you can redefine styles for widget elements exclusively for your custom widget style without getting a conflict with other styles of the same widget.

Documentation on Github

Help us out! If you are feeling that our documentation has errors or can be improved, fork it at Github and send us a pull request. Any contribution is much appreciated. Thank you!