Creating A Theme

Caffeinated uses a very simple and understandable themeing system. Themes area created using HTML and CSS.

What do I need to know?

In order to create a theme, you will need to know basic HTML and CSS and basic XML knowledge to be able to create and edit a plist xml file.

Create the folder / theme

To get started, create a new folder with the name of your theme and give it an extension of .caftheme. For example:
MyAwesomeTheme.caftheme

Create the basics

In order for Caffeinated to be able to use your theme, it requires two files by default, these are:

• info.plist
• index.html
• default.html (optional)

go ahead and create these files inside your theme folder. The info.plist will tell Caffeinated about our theme, and the index.html is what the style will be.

Modify the info.plist

Caffeinated needs to know the name of your theme and various other pieces of information in order to be able to used. Copy and paste the following block of XML into your info.plst:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>ThemeName</key>
    <string>Your Theme Name Here</string>
    <key>ThemeVersion</key>
    <real>1</real>
    <key>ThemeAuthor</key>
    <string>Your Name Here</string>
    <key>ThemeIdentifier</key>
   <string>com.yourcompany.themename</string>
</dict>
</plist>

then change the appropriate string tags to your information, the format of this plist file key and then string which is the value for the key.

The ThemeIdentifier should be unique to that one theme - this is why we use the format com.yourcompany.yourthemename.

The look and feel

Caffeinated renders its content using WebKit ( same engine as Safari / Chrome ). The easiest way to create the theme is to create an HTML page that you wish the theme to look like and then add the extra attributes on afterwards which will tell Caffeinated where to place certain content. The index.html is where we customise this.

Once you are happy with the look and feel you can then add the extra attributes in to tell Caffeinated what to do. To do this we add a render attribute to any tag that you wish to add content into. For instance you may have:

<h1>My Title Here</h1>

which you would want to be the articles title, so we add the render attribute to this tag:

<h1 render="">My Title Here</h1>

This will tell Caffeinated you want to add something inside this tag - Caffeinated will empty the contents of this tag so any child tags will be removed!

To tell Caffeinated to place content inside these tags we use predefined built in methods, here is a list of them:

item

• link
• author
• content

date

• mixed

site

• icon
• name

To get Caffeinated to display the title of the article within our tag we simple use the item method and use the link as an attribute:

<h1 render="item(link)">My Title Here</h1>

which when parsed will end up being:

<h1 render="item(link)"><a href="urlhere">The Title Of Article Here</a></h1>

This format is the same for the item and site functions. The date function is a little different, the date function requires a date format for instance:

<span render="date(d MMMM Y)"></span>

which will be parsed as:

<span render="date(d MMMM Y)">28 April 2012</span>

Caffeinated is not fussy about white space so you can do date( d MMMM Y ). You can also use more then one method inside the render attribute.

For a full list of what formats can be used, please see this list - the format is parsed with NSDateFormatter.

By default, Caffeinated will use the build in splash screen when no item is selected ( the page with the icon and the unread count over the top ). You can customise this if you wish, to do so, you create a default.html and this will be used instead of the built in one.

The default page does not allow any parsing - but it does allow you to display the unread count. To do this, we can hook into the Caffeinated JS library.

Here is an example:

try
{
    window.addEventListener( 'caffeinatedReady', function() {
        caffeinated.bind( 'unreadCountChange', function( a )
        {       
            console.log( a.count );
        });
        if( window.caffeinated.updateCount )
        {
            window.caffeinated.updateCount();
        }
    });
} catch( e ) {}

You can listen for certain events, the main one exposed to you is the unread count change. Which will parse in an object with the count.

Notice the try / catch around this, we suppress errors as the caffeinated window attribute may not be available instantly. The event will be fired after the page has loaded / when the counts change. To fire it manually so it picks up instantly, we can call

window.caffeinated.updateCount();

Which will force Caffeinated to grab the count and fire the event.

Please note, all CSS and JS includes are relative to the themes folders, there is no need prefix the include URL with a /.

Allowing user customisation

Caffeinated also allows users to customise your themes, for instance, they may want to change the font of the content within your theme for ease of reading. To do this is fairly straight forward. On the tags we added the render attribute to, we can also add a configure attribute. This will tell Caffeinated that it can modify styles of those certain tags.

Only adding the configure attribute will not work. We also need to add a min, default and max attribute aswell. The min will tell Caffeinated what its smallest values are, the default is what its currently set to and the max is what the maximum values are. Here is a list of what can be added to each attribute:

min

• -webkit-column-gap
• -webkit-column-count
• line-height
• font-size
• letter-spacing

default

• -webkit-column-gap
• -webkit-column-count
• line-height
• font-size
• font-family
• letter-spacing
• -webkit-font-smoothing

max

• -webkit-column-gap
• -webkit-column-count
• line-height
• font-size
• letter-spacing

Notice that these are CSS rules, so when we use these, we write them exactly how we would write the style attribute on a tag.

For example, if you wanted to allow users to customise the font size of our title / link, we would do the following:

<h1 render="item(link)" configure="true" min="font-size:12px;" default="font-size:16px;" max="font-size:30px;"><a href="urlhere">The Title Of Article Here</a></h1>

This will tell Caffeinated that you can set the font size of the tag to be between 12 and 30. You have to set a min and a max for sizes as these are ranges. You also have to set a default for each rule you use, this is so users can reset the changes they have made.

Testing and installing

Once your theme is created, you can just simply double click the theme at it Caffeinated will move it into the appropriate directory. Caffeinated will automatically pick up the change and allow you to select it from within preferences without having to restart the application.

Testing

For ease of development, you can go to Preferences - Article and then check Developer Tools, this will turn on WebKits inspector inside Caffeinated and allow you to debug and errors or parsing issues you may have.

Help

Having trouble? Something was not explained to well? Head over to the Developers section and we can help you out.