Good morning. My name is Adam Roben. I'm an engineer on the Safari and WebKit team and I've been working on extensions in Safari for a while and I'm really excited to talk to you about them. So if you were at the Safari Internet and Web State of the Union on Monday you heard about how Safari 5 includes support for building extensions for new developers; and if you were in the last session just before this one you heard a lot about what extensions were and what they can do and how you can get started building them. So let's start with a brief overview of what we saw in the last session and then we'll move into the topics for this one.

So over the last hour you heard about how Safari is made up of multiple windows and each window can have multiple tabs in it and each tab has a web page. And Safari's user interface also has bars and toolbar items like the bookmarks bar and the back and forward buttons. So extensions can add into this experience in Safari. An extension can include in it other toolbar items that can be added to Safari as well as context menu items that Safari will show, and one or more bars that will be included in Safari's user interface.

Also if you want to modify web pages with your extension your extension can include content style sheets and content scripts that will be run in the web pages that the user browses to. And finally your extension can include a global page that's kind of the control unit that you use to tie all these pieces of your extension together. Now in the last session Tim also talked about how extensions and Safari are both split into an application layer and a web content layer; and how there's a separation of communication between these two that can be bridged using message passing.

So Tim gave you an overview of all of these things and he also went into a lot of detail on the application layer. Now we're going to mostly focus on the web content layer and then how to tie the two together. So specifically, we're going to be talking about three things; how to modify web pages behavior and appearance; how to add items to Safari's context menus and how to publish new versions of your extensions so that your users can get the latest versions.

So first we're going to talk about how to modify web pages and maybe the best way to start by talking about it is with a demo to show you what's possible. So here we are at vimeo.com. The folks at Vimeo have made a great HTML5 video player that's all built using standards technology. And if you were at the Delivering Audio and Video Using Web Standards talk yesterday morning you learned a lot about how you can do this on a website as well.

So I've made an extension that modifies this website to add a new feature to it. So I'll install it here; I'll just double-click on the extension and Safari will ask if I want to install it and now if I reload this page you'll see that we're going to add a new button over here on the side. We have a new lights button here. And if I click on it, the rest of the page dims out so that you can really focus on the video itself.

So this is just one simple example of what you can do with an extension. So let's talk about how this is possible. Again, we're going to be focusing on the web content layer. That's the layer that can actually interact with web pages directly and so specifically we're talking about content style sheets and content scripts.

Now as Tim told you in the last session content style sheets are added to the web pages that the user browses to. If you're familiar with Safari's user style sheet preference in the Advanced preference pane you already kind of have an idea of what these can do. A style sheet can be applied to a page to modify the size of the text, the colors on the page or the images or to hide certain elements. Now the style sheets are called user style sheets and that has a very specific meaning in the CSS specification.

But all that you really need to know is if you want to override rules that are already in the page with rules in your style sheet, you just need to mark them with the !important keyword and that will overrule any rules that the page has. So there are two important differences from Safari's user style sheet preference. You can have more than one content style sheet where Safari can only have one user style sheet, and you can apply your style sheets to specific pages while Safari's user style sheet is applied to all pages.

And we'll be talking more about how to do that in a moment. Now content scripts are very similar to content style sheets. They also run in the page. Content scripts can run at two specific points while the page is loading. We call them "start" and "end". The start time is roughly equivalent to when the DOMContentLoaded event is fired.

This is right after the main document of your page has finished loading and if DOM is available to you. But the sub resources of that page have not finished loading yet so images on the page and sub-frames and scripts may not have finished at that point. Now the end time is roughly equivalent to when the load event fires and that is after all those sub resources have finished.

These content scripts have access to special APIs that are only available to extensions, and the APIs are similar to the ones that are available in the application layer. But the content layer APIs are a little more limited and this is to enhance the security of your extension. These content scripts are interacting directly with the page and we want to provide a minimal interface so that if your extension is compromised the web page won't really be able to cause any harm. Now just as in the application layer all of these APIs are available through the Safari namespace object so it's very easy to find them.

And just as with content style sheets you can have more than one content script and you can apply them to specific pages. So let's talk about how you would modify only specific web pages instead of all web pages. Well they're really two settings that are important here-- one is the website access setting and one is the whitelist and blacklist and you can configure both of these in the Extension Builder.

Now both of these settings are based around URLs so it might be a good idea to just talk about what a URL is as far as extensions are concerned. So here's an example URL; you've all seen them before but as far as extensions care there are really only three important parts to a URL.

First on the left before the first colon is the scheme in this case http; between the double slashes and the first slash after that is the host often also called the domain, so here it's www.apple.com; and then from the first slash after the host to the end of the URL is the path; so here it's /Safari/what-snew.html.

Now you may know that URLs can also have other parts such as user names and passwords and ports and queries and fragments, but as far as we are concerned in the extension for setting what pages your extension is going to modify these three parts are all you need to worry about. So now that we've talked about what a URL is let's talk about these settings. Website access is the top level setting that affects what web pages your extension can run on.

So it controls both where you content style sheets and scripts are injected, and it also controls what websites and servers you can send XMLHttpRequests to. Tim mentioned in the last session how content scripts are running in the security context of the webpage itself and so are subject to all the same restrictions of that page which means that from a content script you can't send an XMLHttpRequest to another server.

But in the application layer we do allow that and this website access setting is how you specify which servers you need to send those requests to. Now the website access setting only cares about the host or the domain part of the URL. And we actually allow you to specify patterns so let's take a look at what some of the potential patterns are that you could list.

So this first one here is just the host or domain that we had in that last URL www.apple.com; and this will match just that single host. Another one is apple.com and that will match just apple.com; it won't match www.apple.com. But if you wanted to have your extension to be able to access both www.apple.com and apple.com and maybe also trailers.apple.com and any other subdomains that exist, you can write *.apple.com and this will match all of those hosts so you don't have to list them separately. Now there's also one more part of the website access setting which is the Include Secure Pages checkbox. If you have that checked, then you could access for example the https version of www.apple.com and the http version.

If you don't have it checked, you won't have access to the https version. So the whitelist and blacklist is the other setting that I mentioned and this controls just where your content scripts and style sheets are injected. And the control is more fine grained than the website access level. You can actually target specific paths on a particular domain instead of just targeting a whole domain. And for that you have to use something that we call URL patterns so let's take a look at some.

So here's a very simple URL pattern-- it's just that same URL that we looked at before, and so this will match that particular page and no other ones. But if you want to start matching more than a single page you can start using stars to act as wild cards.

So in this case we've replaced the "www." with "*." just like we did in the domain pattern and so this will match this scheme and path on any apple.com or apple.com subdomain. So here are some examples-- it will match it on www.apple.com; or on just apple.com or on any other subdomain. It can even be more than a single level of subdomains.

So here's another example where we've put the * in the path. This will match sites that are only on www.apple.com but anything could come before the "what-s new.html" part of the path. So this would match Safari's What's New page or iTunes' What's New page or again you could even have multiple parts of the path in there that the * will stand in for.

So a very common thing you might want to do is to match any page on any subdomain of apple.com or any other server. And so this is the form that that pattern would take. We have *.apple.com as the host which will match apple.com or any subdomain; and just /* as the path which will match any path on any of those hosts.

And so all of the URL's that we've seen so far would match this pattern and many others that I haven't gone over. Now I should also note that in all of these examples I've used http as the scheme but you could also have https to match the secure versions. So let's look at now we could actually put together this Lights Out Demo now that you've kind of learned the basics.

So here we are back on Vimeo-- I'll turn the lights back on and actually I'm going to uninstall the extension so that we can start from scratch. So I'll go to Safari's preferences and uninstall it and now we're back to a clean slate. If we reload Vimeo you'll be able to see that our button is gone because we've uninstalled that extension.

So before we actually build the extension I think it might be good to look at the code so we get an idea of what this extension is actually doing. There are two main parts to it-- there's the button that we add and then the overlay that dims out the page. And so let's take a look at the code for that. First we have a content style sheet and this style is the overlay.

Now we actually don't need to style the button at all because Vimeo has set up their style sheets in a way that we could just take advantage of their built in styles since they built their player using HTML and CSS. But here we have a rule that is for our overlay div.

It's a fixed position div that covers up the whole viewport and it starts out as transparent so that then we could fade it in. It has a black background color and we've set a WebKit transition on it to give that nice fading effect instead of having it just pop in immediately.

Now we also have a z-index property here to put it in front of all the elements on the page. But of course we want the video to be in front of the overlay and so we also have a rule that we apply to the video that increases it's c-index so it isn't in front of the overlay and doesn't get covered up.

So here's the content script that we actually run in the page. You'll notice that at the beginning of the script we start running code immediately. We don't add any event listeners of wait for a load event or anything like that; and that's because as I said you can specify that your content script run at either the start or the end part of loading. And so this is an end script here and so we're running when the load event has fired so we don't need to listen for the event explicitly-- Safari will just run us at the right time.

So as soon as the script is run we call the Add Lights Button function and you can see that function here. It just is using normal down calls to create a button element, to add an image into that element and then to add all of these into this side doc element that's built into Vimeo's HTML5 player. You'll notice here that we're using the Safari.extension.base URI API so that we can reference an image that's actually inside our extension.

So once this is in the page we also set up a click event listener for it to call this toggle lights button whenever the button is clicked. And toggle lights you'll see right down here is very simple. If the lights are on then we turn the lights off; and if they are off then we turn them on. So the way that we turn the lights on and off, here's the turn lights off function and we just create that overlay if we haven't created it before; we set its opacity to be our maximum opacity value so it will fade it from transparent to opaque.

And we also apply a class name to the video that's built into the player so that we can add that c-index property to it to pull it in front of the overlay. You'll notice that the class attribute that I've used here and the ID that we're using for the overlay itself are all prefixed based on my extensions bundle identifier and that's a good way to isolate your rules from those in the page. So finally when we turn the lights off we just update the image that we're using for the light button so I guess those nice rays coming out of the side; and we set our global lights on variable to false.

So turning the lights back on is very similar, we find the overlay, we make it transparent, we switch the button back to the old image, and then we wait for the fading animation to end by using the webkitTransitionEnd event and when that happens we remove the overlay from the page entirely and remove that class name that we added to the video to put the page back in the state that it was before we had done anything. And again just to show you that there isn't any special magic going on here, here is that create overlay if needed function.

It's just using normal DOM calls to create a div and to give it our overlays ID so that it will get the right styles, and adding another click event listener so that the lights will turn on when you click anywhere on it. So now that we've seen these, let's see how to actually put it together into an extension using the Extension Builder. So I'll come up here to the Develop Menu and go to the Extension Builder and I'll click on the + button to make a new extension. And we will call it Lights Out and let's put it on the desktop.

So here it is as Tim showed you the Extension Builder fills in some things for you automatically. Now the first thing we have to do is set that website access level that I mentioned. So it starts out as none meaning that you can't access any web pages at all but we'll change it to some since we want to access Vimeo.

So I'll add a new domain pattern and I'll do *.vimeo.com. So now we need to add some of these files to our extension. So I'll open up the extension folder here that the Builder created for us and I'll find those files that I already prepared and they're right here. We just have the style sheet and the script they already saw and then the two images for the light button.

So let's add those to our extension. And the Builder will automatically detect that these have been added so we just have to come back to the Builder and tell it about our end script which is right here in the popup menu and the style sheet that we added.

Now down below here we can specify whitelist and blacklist. But Safari actually makes this a little bit easier for you. If you want to access every web page on all the sub-domains of vimeo.com, Safari will actually add that whitelist pattern for you-- the one that I showed before that *.apple.com/*. It's done the same thing here for *.vimeo.com based on the website access level. All right so let's install this and see what happens.

So I'll click Install and we'll reload Vimeo and you can see that the lights button has been added and if we click it, [Laughter] I guess it doesn't have as much power as we thought. It only turned off the lights on the page but it does seem to be working so you can see how the Extension Builder makes it very easy to put these pieces together and get your extension working right away. So we've written this extension and it works pretty well and we sent it out to our users and people are loving it.

Well one thing that we've heard from some users is they really don't like that exact shade of gray that we chose for that overlay and they'd really like to customize it. So an obvious way to do this would be to add some settings to our extension. Tim showed how your extension can have settings that are right in Safari's preferences just alongside all the other preferences that Safari contains. So we'd like to do this for our extension.

But as Tim also mentioned in the last sessions settings are something that are up in the application layer and of course our content script is down in the web content layer. And so we're going to need some way to get the information about the settings from the application down into the content script and into the page. So the way to do this is through messages.

Messages are implemented as events in Safari and they're very simple. They really just have two parts; there's a name and there's some optional data that comes along with it. So here is some examples. We could have a message where the name is "get-setting" and the name of the data of that message is "opacity" to say what setting value we want to retrieve; or we could have a message where the name is "show-bar". You know if you only had one bar in your extension you might not need to say anything other than show that one bar that we have and so here we don't have any data.

Here's another message called "send-xhr" and you can see that we're sending an object as the data of the message telling it what server and what method to use for this XMLHttpRequest. And again this is useful if you need to be sending an XMLHtdpRequest to another server. The content script can't do that directly but the application layer can do it for you and so this message will let that happen.

So these messages are sent using two proxy objects. There's one to go in each direction from the web content layer up to the application; and from the application back down. So going from the content back to the application you would do it like this with safari.self.tab.dispatchMessage. Now this tab object while it looks like the tabs that you see up in the application layer, it's actually just a tab proxy and mostly the only thing that it can do is send a message up into the application.

Going in the reverse is very similar; from the application to content you'll find any tab object so here we're getting the active tab in the front most browser window and you use its page property. Now this isn't the actual web page; it's a page proxy and you can use it to send a message using dispatchMessage again down to the real web page.

So an illustration of what we're going to do in our extension to implement these settings, when the page loads we need to find out the current setting value so as soon as the user clicks on the light button the lights will go out to the right level. And so to do that when the content script runs it will send a message up to the application and in this case the global page is going to receive it. Now you could also send a message and have a bar receive it.

So once the global page gets that message it's going to retrieve the opacity value out of settings and make a new message and send it back down to the script where the script will act on it. So let's see how to do that. So the first thing that we need to do is in that content script we need to send that message up as soon as the page loads to find out the preference value.

So let's go back to our content script and if you'll scroll down a little bit farther you'll see that I've already written that code. So as soon as the script runs we'll send a message that we're calling get maximum opacity and we also add an event listener for the message event so we can receive messages back from the application.

When we receive a message event we first check its name, and if that name is the set maximum opacity message that we are expecting back, then we update our maximum opacity global variable. And we also update the overlay in case it's already showing. These messages are sent asynchronously and so it's possible although unlikely that the user could have already interacted with the page.

So an update overlay was needed. Here we just have normal DOM calls to find that overlay element and update its opacity value so it's all very simple. Now I mention that we are going to be using a global page to receive these messages so let's look at that.

This is our global page it's just a normal HTML page and it adds an event listener for the message event to receive that message from the content, and when we get that message it's that get maximum opacity message that we are expecting, then we send a message back down to that content script and tell it the maximum opacity by retrieving out of the settings object. Now you'll notice that we're using event.target.page here to send the message back down into the particular page that sent us the message; event.target is the tab that contains the page that sent the message.

So there's actually one other time that we would like to be able to update the opacity of this overlay and that's if the user changes their preferences while the overlay is already visible. And so there's actually a way to do that. Every time a preference changes we send a change event to the settings object and so the global page listens for that event here.

And when we get that change event the event will have a couple of different properties on it that help us determine what has happened. So the first one is the key property. This tells you which setting actually changed so in this case if it's our maximum opacity setting that we're going to loop over all of the windows that are open and all the tabs in all of those windows and send a message down to each one of them telling them about the new opacity value.

And we'll just use that same set maximum opacity message that we used before. And the way that we get that new value is it's right here on the event-- event.newvalue gives you the new value of the preference. So let's see how to put this together into our extension. We'll come back to the Extension Builder and really the first thing that we need to do is to get this global page into our extension folder so the Extension Builder can find it.

So let's open up our extension and we'll copy that global page over that I've already written. And so now that it's in our folder the Builder will find it and if we open up this menu it says global.html that's the one that we want. And now we also have to add the setting.

If we were to go into Preferences right now, you could see that we don't have any UI here for setting up what the opacity of that overlay is. So I'd like to add a slider so that users can really tweak it to their exact liking. So we'll come down here to the bottom of the Builder and click on the New Setting item button.

And now the first thing we have to choose is the type; you can see there are a lot of different controls here like text fields and checkboxes and popup buttons but we're going to go with the slider. We'll give it a title which is what is shown in the UI to the user so we'll call it Overlay Opacity.

The key is the settings key that we use in the API to retrieve the value so I'll call that Maximum Opacity; the default value we'll set to 0.8 which is the same one that we had in our content script before; the minimum and maximum value, we'll have the slider go from 0 to 1 because those are the values that the CSS opacity property accepts; and then we'll set the set value to .01 so users can really tweak to exactly the way they want.

So now if I click reload and we go back to Safari's preferences and click on our extension you can see that we have a slider already. I didn't have to write any code; the Extension Builder did it all for me. And if I reload Vimeo so that our content script will be updated, if we turn off the lights and then come back to Preferences here we can actually slide that slider around and see the opacity changing live because of that change event.

So let's go over what we've learned in this section. We talked about how to use injected content meaning style sheets and scripts to modify web pages; how you can use URL patterns and domain patterns to specify what web pages you modify; and how you can use messages to tie together the web content layer and the application layer of your extension. So next up is adding context menu items and again we're just going to start out with a demo.

So I'm going to uninstall our Lights Out extension here and install that same Twitter extension that Tim was showing you so I'll just double-click on it and choose to install it. So again we have that Twitter bar here that Tim already showed you but I'll hide that for now because we don't actually need it.

So the basic idea of this context menu item is that I am a new Twitter user and I don't have a lot of content on my Twitter page yet and I would like to get some so this extension has made it really easy for me. If I'm browsing around the web and find something interesting that I really think people should know about like WebKit is an open source browser engine; that sounds pretty important so I'll just right click on that text and you can see in the Context Menu we have this new item that's been added by the extension that's called "Tweet This Text". And so if I click on that the extension will send that text off to Twitter using Twitter's API and post it to my page. There it is and we even have a link back to the original page so this makes it really easy to add new tweets.

So let's talk a little bit about how you could do this in your extension. So in order to add context menus in your extension first you need to know how they work in Safari. So the idea is very simple when the user right clicks on a web page, WebKit itself makes a context menu; but before that context menu is shown to the user it's sends the context menu up to Safari and gives Safari a chance to customize it. And Safari in fact does this; it adds Safari-specific context menu items such as open link in new tab.

Now extensions do something very similar; in fact the beginning of the process is identical. The user right clicks and WebKit creates a context menu, it sends it off to Safari and Safari gets to customize it. But then before the context menu is shown to the user, Safari gives the context menu to each extension that is installed and the extensions can add their own items. So the context menu items before we go any further are very simple. They're very similar to the toolbar items that you saw in detail in Tim's talk. They are made up of four parts.

There's an Identifier which is how you refer to the item in your own code; there's a Title which is shown to the user in the context menu; there's a Command string which is just a string that you use internally to represent the action that this context menu item performs; and then they have a Disabled state.

Now we never show disabled items to the user they would just clutter up the menu and so if you have a disabled item it's actually hidden from the menu entirely. So the way that you get to add your items to the context menu before it is shown is by listening for the contextmenu event. This is sent up in the application layer.

Specifically it's sent to the tab and so that's the target of the event and then it bubbles up to the window and then to the application object. On this event is a context menu property and that context menu is how you interact with the context menu that will be shown and it has a few methods that you can use. There's appendContextMenuItem, insertContextMenuItem, and there's a contextMenuItems array that gives you access to the items that you've added so far. Now this array will only include the items that your extension adds.

You won't be able to see WebKits' items or Safari's items or items from other extensions, and this prevents extensions from interfering with each other or with the default behavior of the browser. Now you can also specify these items in the Builder. If you find that you're adding the same item every time it might be easier just to specify it once in the Builder and Safari will add it to the context menu for you without you having to listen to the contextmenu event. Now the other events that come along with context menu items are the "validate:" and "command:" events that you also use for toolbar items.

Now the validate event is sent for each item just before the menu is shown and this is your chance to disable or hide those items. This is particularly useful when you've added those items in the Extension Builder. Safari will put them in the context menu for you automatically but maybe you don't want to show them right now and so the validate event is your chance to hide them before they're shown.

And then the command event is sent when a particular item is clicked and that will tell you which action to perform. So of course with context menu's the real point is that they're contextual. What is in the menu and what happens when you click on it depends on what the user right clicked in the first place.

And so you need to find this out to really provide a good contextual menu. Now of course as I said the contextmenu event and the validate and command events are all sent up in the application. But the user is right clicking down into the right content layer and so you need to find out what was clicked on. Now you could just do this using messages but there's actually an easier way and a better way. The way to do it is in the content meaning a content script, you can listen for the contextmenu event in the web page.

This is something that's part of the DOM, it's been in WebKit for a long time and in the past really the only useful thing you could do in this case was to prevent a context menu from showing at all say if you had some custom menus to show in your page. But with extensions you can do something new. We have an API on that tab proxy object, safari.self.tab.setContextMenuEventUserInfo. And this is your way to associate some bit of information with this particular contextmenu event.

So after you've called this in the content script, then up in the application when you receive that context menu or validate or command event, this UserInfo will be available to you as a property on the event itself; and so you can use that context to determine whether to hide or show a particular item or exactly what action to perform.

So let's look at how we do this or to tweet this text item. So I'm going to go back to the Builder and I'm actually going to add the Twitter extension which we've already written so instead of choosing New Extension I'll choose Add Extension and I'll navigate to where we have it saved.

And so now here it is in the Builder just like you saw it from Tim. Now if we scroll down you'll see that under Context Menu Items we've added an item here. So the name of it is "Tweet This Text" and the identifier and command are also both "Tweet This Text".

So Safari will add this item for us so now let's look at the code that handles the item. First we have a contents script that listens for that contextmenu event in that web page again this is the DOM contextmenu event; not the one that we send up in the application layer.

When we get that event we call that setContextMenuEventUserInfo API we pass the contentmenu event and then we get the selected text on the page. Now if there's no text selected this will just be an empty string and we'll be using that information shortly. So now up in the global page that's where we listen for the validate and command events.

You've already seen some of this code in Tim's demo so here's our command event listener and here's our validate event listener. So first let's look at validation. Here we are in validate command now if the command that we're validating is "Tweet This Text" command meaning that this is for that context menu item, we choose to disable the item in some cases and remember disabling really means that it will be hidden. So the case where we disable it is when the user info which is the selected text in the page is empty. When the length is zero we hide the item because there's nothing to tweet in that case.

Now when we receive a command event that code is right up here in Perform Command. So we have another command that we use for a toolbar item but here is the one for our context menu item-- again it's just "Tweet This Text". So all that we do is take that same user info which is the selected text, we surround it in some curly quotes and then we append the URL of the front most tab which is where this context menu is being shown.

And so that is the Tweet Text and all we do is sent that off to Twitter using their normal API and a cross-domain XMLHttpRequest. And because in the Builder we've specified that we need to be able to access-- well in this case we've actually changed the access level to all pages, so that will let us both send the XMLHttpRequest to Twitter and it will also let us show the Context Menu on any page on any server.

So that's all that it takes to put this together-- it's very little code and very easy. So just a quick recap to add context menus into Safari the best way to do it is to first listen for the contextmenu event in the web page and that's your chance to provide context to your application so that it knows which items to add. Then you can listen for the contextmenu event up in the application layer and that's your chance to add items. Now you can also add the items using the Extension Builder.

Then the validate event is sent before the menu is shown and that's your chance to disable or hide items; and the command event is when you should perform the selected action that's sent when the user clicks on one of your items. So that's everything for context menus. Now let's talk about publishing updates. So say you've written this great extension and a lot of people are using it and they all really like it and now you've made a better version that you want people to install.

So what are your options? Well you could of course post it on your web page and hope that people go to your web page frequently enough and decide to install it; or if you are a really kind of naggy web developer you could make a mailing list and send e-mails to all of your users and hope that they don't filed as SPAM and hope people actually read them and don't hate you forever because of it; or there's actually a better way and that's to have your updates listed right in Safari's preferences. Safari will automatically discover updates for the extensions that are installed and present them to the user in this UI and the user can install them individually or install them all at once or even check a checkbox to install all the updates automatically as Safari discovers them.

So this is an opt-in feature that you have to opt-in to each extension that you write. And the way you do it is very simple it's through a file that we call the update manifest. This is just a simple XML file that you host on your web server and Safari downloads it periodically. And what the file contains is a list of all the extensions that you develop.

Now for each extension you just need to list a little bit of information. First you need two different identifiers-- one of them is the extension's bundle identifier that you enter into the Extension Builder, and the other is the identifier that's associated with your developer certificate. These two identifiers together uniquely identify your extension.

Now next you need two version numbers. The first is the internal version number that Safari uses to decide whether one version is newer than another. And the other is the display version that's actually shown to the user in the UI. And then finally all you need to list is the URL where Safari can download this particular version of your extension.

So if you make this file and put it on your web server Safari will download it periodically, and any versions or extensions that the user has installed that are newer in the update manifest will be presented in Safari's preferences making it very easy for users to discover and install your updates.

So you've seen a lot of demos in the last session and in this one that have shown you little bits of each part of the API, the extensions and how to use them and implement them. But also in the State of the Union on Monday you saw some great demos of some really awesome extensions that kind of pull all these topics together. And you might be wondering how can I write one of those. So to show you that we actually have Cabel Sasser here from Panic to show you how Code of Notes was constructed.

All right after listening to all these super smart Safari people I think you guys know probably 90% of what you need to do to develop an extension. I'm going to talk a little bit about the remaining 10%, the stuff that we learned through developing the code of notes extensions that we didn't expect, some tips, some tricks, little things like that.

Code of Notes is a website annotation tool which provides a new toolbar in Safari and allows the user to basically scribble directly on a web page. We have a highlighter and we have sticky notes and things like that. So this was kind of an interesting thing to build and there are a lot of pieces going on here.

First of all we have the toolbar item that we install; we also have our custom toolbar which you can see here. And one thing that we did with that toolbar that's kind of cool is that the bulk of that with the exception of the glyphs on the buttons it's all CSS style; so those buttons are all border radius, gradients, so they can scale well and they're super flexible so I would encourage you guys to use CSS styling as much as possible. Let's see if I can show you that actually. Here's what the bar looks like.

If I zoom that up you see that everything sort of scales appropriately; so that allowed us to really quickly develop this toolbar without having to do a lot of graphics work in Photoshop. So we've got the bar; we've got a global HTML page which I know has been already talked about; and then we've got some JavaScript that we're injecting into every page. The global HTML page mostly controls whether or not this bar should be displayed.

One thing that we learned that was a surprise for us of course we're injecting our JavaScript into every page because we never know when a user is going to want to start drawing. So one thing we learned that a lot of pages imbed a lot of iirames in their pages and your injected JavaScript will also be injected into all of those iirames so we were seeing a lot of duplicate events and surprisingly weird stuff happening until we finally realized that oh it's that little ad in the corner.

So beware of that if you're injecting JavaScript that it will go everywhere. And what we did as a suggestion from these guys we're checking if window top equals window just to make sure that we're only injecting into the top most element. So how are we doing this drawing? Basically, when you activate this tool, actually open the bar, there's a giant canvas element transparent on top of the entire page.

And the canvass is-- if you guys have ever done any work with canvas it's basically-- gives you drawing context and we're just drawing, we're capturing the mouse event and we're scribbling on that canvas. Now one thing that's kind of interesting is if we've got a canvass over that entire page, how are we allowing you to do this text tool? The text tool allows you to actually edit the text on the page directly. If the canvas is covering everything you would think that the pointer wouldn't be able to click through it to get those text events and edit the text.

We're actually setting a CSS style which is pointer-events: none. We set that on the canvas which basically means that the pointer events have been passed through. The canvas no longer gets the pointer events so that was a cool solution to a problem that kind of had us scratching our heads for a little bit. Now there's a couple of interesting things-- the sticky notes that we're doing here are actually dragging around using the actual drag and drop events.

We set the body to the drop zone so of course you can drag them around, then things get really hairy with the notes button we've implemented; because what happens here is we have our style of our postcard and we know what we want our text to look like. But the page that we're injecting this into might have styles that override that; they might have body text set to a huge font, or do things that might mess up the appearance of our postcard.

So we have a crazy little trick where we walk through all the style sheets and essentially disable them, but while we're walking through them we're also storing them and making a note of them so that if a user were to hit cancel and wants to see the page as it looked originally, we now reset all those styles back to what they were before.

So an earlier version of this plug-in actually put the postcard in a new tab and that was certainly a lot easier from a developer perspective because we didn't have to do these tricks. But having it be in the window not opening a new tab is much better; but just something to think about that you're in an environment where there are a lot of styles and things to consider that might surprise you. Some people have asked me how we are doing the screenshot thing-- how we actually get an image of the tab and shrink it down.

If you're looking for the documentation and you're searching for screenshot, you probably won't find it. It's actually called visibleContentsAs DataURL and what that does is take the image contents of the tab and basically give you a standard data URL, base64 encoded I believe, of a PNG version of the tab so look for that visibleContentsAsDataURL. And last but not least you've probably seen in the demo that we do a little animation at the end that people seem to love where a stamp comes down here and everything flies off.

I'm sure you've been hearing this a lot this week but it's all CSS animation; it's all a class that we make called Fly Out that sets the WebKit transform and when the user hits the button we just apply that class to that stamp image, it flies down on the page, it's off and it's running.

So I think that covers most of the stuff that kind of surprised us but we did do this in a short period of time and we're super happy with the results and we think that when you guys dig in-- like I said you've got 90% of what you need and the remaining 10% is pretty easy to solve. So I look forward to seeing what you build.

Thanks Cabel that was really great. I should also mention that we're very excited to be hearing from Cabel and the other guys at Panic and from all of you about what things about extensions you find surprising. Extensions are a developer-only feature at the moment and so we're looking for a lot of feedback in ways that we can improve it. So let's go over a quick summary of what you've seen today.

We've talked about how to modify web pages using content style sheet and scripts; we've talked about how to add context menu items in Safari using the Context Menu and validate and command events; and we've talked about how to publish new versions of your extension by opting into Safari's autoupdate discovery mechanism by posting an update manifest on your server and putting that update manifest's URL into the Builder so it will be embedded into your extension.

Now if you want to find out more information about all of this you can contact Vicki Murley, our Safari Technologies Evangelist; you can also go to the Safari Dev Center where you'll find a lot of documentation. That's also where you sign up for the free Safari Developer Program and get your free signing certificate. And you can also use the Apple Development Forums and we have Apple engineers looking through those forums and trying to answer people's questions all the time.