Enhanced Personas

In explaining exactly what a Persona was in my last post, I mentioned that a Persona contains two images - a header and a footer. I also indicated that these images are very large - 3000 pixels wide. You may wonder why that is. Personas is designed to do one thing; take an image and put it in the upper right corner of the browser. It doesn't resize or scale the image. If you resize your browser very wide, you just see more of the image on the left hand side. That 3000 pixels number is a completely arbitrary number that is designed to be the maximum you will resize your browser.

This architecture creates problems.

  • The file sizes of the images can be very large.
  • If you have a repetitive image, you have to cut and paste it to make it 3000 pixels wide.
  • If you want to use an existing image, you'll have to do something to convert it to 3000 pixels wide.
  • You can't guarantee that anything appears in the upper left corner.
  • You can't have more than one background image.

All of these problems have already been solved by CSS, but none of the CSS to do anything to background images is available in Personas. That's where the Enhanced Personas feature of Personas Interactive comes in.

Enhanced Personas adds additional attributes to the Personas JSON that gives you all the things that CSS backgrounds have to offer. This includes multiple background images! Here are the attributes we've added:

backgroundImage
Specifies the URL of an image or multiple images that will be used for the background. Multiple images are separated by a comma. The images are drawn from right to left, so the left most image appears on top. We aren't using the actual CSS syntax here, so don't put url('...') around the images.
backgroundPosition
Specifies the position of the images in backgroundImage using standard CSS rules. These rules are separated by a comma.

backgroundRepeat
Specifies the repeat of the images in backgroundImage using standard CSS rules. These rules are separated by a comma.

backgroundSize
Dpecifies the size of the images in backgroundImage using standard CSS rules. These rules are separated by a comma.

backgroundColor
Whereas accentcolor in the original Personas specification is used for both the titlebar and the background of the browser, we allow you to specify just the background color. It is never used for the titlebar. If you specify both a backgroundColor and an accentcolor, accentcolor is used for the titlebar, and backgroundColor is used for the background of the browser.

textShadow
One of the other areas that causes problems with Personas is the area of text shadows. We've provided an additional attribute to let you control the text shadow. Personas determines the color of the text shadow to use for your Persona by computing the luminance of the textcolor specified in your Persona.

let luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b;

If the luminance is less than or equal to 110, it makes your text shadow light, otherwise it makes your text shadow dark. We've made textShadow an attribute that you can specify, and you can give it three values: dark, bright or none. You can experiment with these three values to see which one makes your text look good on your Persona.

Summing it all up

So what does all this give us? The ability to create a Persona that takes full advantage of CSS. If you hover over the preview images below with Personas Interactive installed, you'll see examples of Enhanced Personas in action. Each of these Enhanced Personas has an image on the left, an image on the right and a repeating image for the background. If you install them, you can resize the browser and see that the images stay in both corners of the browser. I've deliberately placed breaks in the background image so you can see the repeat. You'll also notice that I've used a different text shadow option for each of the Personas. See if you can figure out which value I used.

Enhanced Persona Demo 1attachPersona(document.getElementById("enhancedpersonademo1-preview"));Enhanced Persona Demo 2attachPersona(document.getElementById("enhancedpersonademo2-preview"));Enhanced Persona Demo 3attachPersona(document.getElementById("enhancedpersonademo3-preview"));Enhanced Persona Demo 4attachPersona(document.getElementById("enhancedpersonademo4-preview"));

Enhanced Persona Demo 5attachPersona(document.getElementById("enhancedpersonademo5-preview"));Enhanced Persona Demo 6attachPersona(document.getElementById("enhancedpersonademo6-preview"));Enhanced Persona Demo 7attachPersona(document.getElementById("enhancedpersonademo7-preview"));Enhanced Persona Demo 8attachPersona(document.getElementById("enhancedpersonademo8-preview"));

Here are some other things to keep in mind with Enhanced Personas.

backgroundImage is a required attribute. This means that even if you use the other attributes, if backgroundImage isn't specified, they won't be honored. The only exception to this is textShadow.

You can create an Enhanced Persona that works with Firefox out of the box. Just specify both a headerURL and a backgroundImage. Personas Interactive users will get the Enhanced Persona.

For our next installment, we're going to talk about the hallmark of Personas Interactive, Interactive Themes and Interactive Personas.

This is part three in my series about Personas Interactive from Brand Thunder. If you missed the first two, they are Introduction to Personas Interactive and What is a Persona?

What is a Persona?

After I introduced Personas Interactive, I indicated that my next topic was going to be Enhanced Personas. As I was writing that post, though, I realized that I was putting the cart before the horse. Before I explain how we've enhanced Personas, I need to give more detail as to how you can put Personas on your website. Then we can talk about the enhancements we've made and how you can use them in your Personas. Remember that to really see these things in action, you need Personas Interactive. You can download it from here.

So what exactly is a Persona? You probably think of a Persona as just an image that goes in the background of your web browser. But Personas are not just the images. They are also a JSON file that gives a little bit of information. Here's what a bare bones Persona looks like:

{"id":"mypersona@kaply.com",
 "name": "My Persona",
 "headerURL": "http://kaply.com/images/mypersona.png"
}

To use this Persona in a web page, Firefox introduced an attribute called data-browsertheme. To designate that an element on a web page defines a persona, you add that attribute to any element (usually an image):

<img alt="My Persona"
     data-browsertheme='{"id":"mypersona@kaply.com",
                         "name": "My Persona",
                         "headerURL": "http://kaply.com/mypersona.png",
                        }'
     src="mypersona.png"
     id="mypersona-preview">

Having the data as an attribute on the image isn't enough, though. We need to have some JavaScript that hooks everything together. Personas works by using custom DOM events to indicate when an image is previewed, installed and reset. Here's what preview looks like:

var event = document.createEvent("Events");,
event.initEvent("PreviewBrowserTheme", true, false);
document.getElementById('mypersona-preview').dispatchEvent(event);

Writing this code every time would be tedious, so I've created helper functions that do this for you. You can download them here. Attaching all the appropriate Persona events to a node is matter of calling attachPersona and passing it the node that you want to use for your Persona preview.

Now you may be thinking that it would be difficult to maintain JSON embedded in a web page, and you would be correct. What we need is an automated process to generate a Personas gallery. At the beginning of this article, I mentioned that Personas are described in a JSON file. What we want to do is store JSON files directly on our server and generate web pages that use the data contained in those JSON files. The reason for this is three fold. First, because it makes it easier to maintain, second because Personas can be updated by pointing to the JSON file directly, and third because we will use those JSON files for site specific Personas which we talked about in the previous post.

I'm a PHP developer, so the example I am going to provide is how to generate a Personas gallery using PHP. For my basic example, I'm using a top level directory with an index.php that will be my gallery and subdirectories that represent each Persona. Those directories are named for the Persona and contains a persona.json file, a PNG file used for preview that is named the same as the directory, and any other supporting images, like the background or icon. To generate a gallery item, you call the function generateGalleryItem passing it the name of the directory. Here's some PHP code that does this:

<?php
function generateGalleryItem($name) {
  $handle = fopen("$name/persona.json", "rb");
  $contents = stream_get_contents($handle);
  fclose($handle);
  $persona = json_decode($contents);
?>
 <img alt='<?php echo $persona->name; ?>'
      data-browsertheme='<?php echo $contents; ?>'
      src='<?php echo $name; ?>/<?php echo $name; ?>.png'
      id='<?php echo $name; ?>-preview'>
<script type="text/javascript">
  attachPersona(document.getElementById("<?php echo $name; ?>-preview"));
</script>

With these code examples, you should be able to get a Personas gallery working on your website.

Earlier I talked about the fact that I was giving an example of a bare bones Persona. Now would probably be a good time to talk about what else you can specify in a Persona JSON file. Personas support the following attributes which are all strings:

id
The ID of the Persona. It does not have to be of the form persona@example.com, but it is recommended.
name
The name of the Persona, as displayed in Add-ons-Themes
headerURL
The URL of the image for the header. Per the Personas specifications, this image is 3000px wide x 200px high.
footerURL
The URL of the image for the footer. Per the Personas specifications, this image is 3000px wide x 100px high.
textcolor
The color of text in the browser.
accentcolor
The color used for the background of the browser, as well as the titlebar on Mac.
iconURL
The URL of an icon to be displayed in Add-ons->Themes
previewURL
The URL of a preview image to be displayed in Addons->Themes
author
Your Name. This is displayed in Add-ons->Themes
description
The description of your Persona. Normally this is only displayed when you right click a theme and select "About", but for Personas Interactive, we've replaced the default display of "Created by" with the description.
homepageURL
A home page URL for your Persona. This is accessed by right clicking on a Persona in Add-ons->Themes
updateURL
The URL for your Personas JSON file. Firefox requires https, but for Personas Interactive, we allow http as well.
version
The version is used only when you need to update your Persona. If a version is added or is greater than the previous version, Firefox updates your Persona. This update check happens every 24 hours, similar to update checks for add-ons.

Site Specific Personas

I mentioned site specific Personas, so I might as well give you that information as well. To enable a site specific Persona, add the following code to the header of your website:

<link rel="persona" type="application/json" href="https://mydomain.com/mypersona/persona.json" />

The href points to the JSON file that describes your Persona. If you want to use a Persona from getpersonas.com, navigate to the Persona and then look at the URL. You'll see a number at the end of the URL. The format for Persona update URLs is https://www.getpersonas.com/en-US/update_check/%ID%. Just replace %ID% with the number at the end of the URL.

One other thing before I close this out. I find the site JSONLint.com invaluable for debugging my JSON. Not only can you paste JSON there, but if you put a URL to your JSON file, it will read it and check it. I can't recommend it enough.

I hope this has helped you get started adding Personas to your site. Next post - Enhanced Personas. I promise.