Integration • 49:07
Providing quick and clear assistance to Mac users is critical to a quality user experience. Be the first to hear about major upcoming features in Apple Help, the HTML-based help system for Mac OS X applications. You'll find out how to build Apple Help into your application and learn about topic lists, improved indexing, and integrated network search results. Additionally, get the details on the brand new format for Apple Help books, indexes, and metadata.
Speakers: Nick Kocharhook, Daniel Feldman
Unlisted on Apple Developer site
Downloads from Apple
Transcript
This transcript was generated using Whisper, it has known transcription errors. We are working on an improved version.
My name is Nick Kocharhook, and you are here to learn about Help, Apple Help specifically, Help Viewer, and everything associated with it. So I wanted to talk to you about what Apple Help is, first of all, how it exists today in Leopard and basically in Snow Leopard. And then what's new in Snow Leopard, what we've changed, we've actually made it much easier to add Help to your applications. It was pretty easy before, but even easier now. Then we're going to have a couple demos of how Help works and adding it to your app, and then we're going to do a Q&A afterwards.
So, Apple Help is really fantastic for your users. It's really about getting users able to use your app more easily-- or sorry, using your application. Not just novice users who want to learn more about your app, you know, want to even start, where do I go, but it's also good for average users who want to learn even more. They want to become experts. So I actually wanted to just start out with a demo and show you how Apple Help works now today. So if I can get a demo-- go to the demo. There we go. OK. Thank you very much.
So say we wanted to-- We're in iCal, and here we are today on the 11th of June, and we're going to have a party on Inauguration Day, say. Okay, so, but when is Inauguration Day? We don't really know, or I don't. Okay, so let's go to Wikipedia. Okay.
[Transcript missing]
When is that? Oh, that's January 20, 2009. Okay, so let's go into iCal. And now, as you know, we're on June 11th, but what we'd really like to do is jump ahead like six months. Well, we could go through this one week at a time, or we could go to, that's a little later on in the session, we could go to the Help menu and search for it.
Okay, so we're going to search for date, and it turns out there's a menu item called Go to Date. Now, this is the second way that Help can help your users, and, you know, this Help menu search of the menus is actually really great even for, you know, just average users or maybe even advanced users to speed things up.
If there's a menu that you need to go to all the time, but it doesn't have a keyboard shortcut, this is a really great way to use that. Okay, so we're going to go to the date. We're just going to click this, and it's going to execute the action for us. And so now, this is our current date, but actually, we'd like to go to January 20th, 2009. Okay, that's a Tuesday.
So we learned from Wikipedia that actually it takes place on noon, or at noon on January 20th, so that's when we're going to have, you know, Nick Kocharhook, Daniel Feldman time. Time zone. How do I do that? And if you look here, the second result is changing the time zone for an event. Now notice, this is not anywhere in the menus. There's no menu item that says change the time zone, set the time zone, none of that. But because iCal has help content, we're able to get this result because it's in the help documentation. Okay, so we click that.
And help here comes up and lets us know that there's some preamble here. And then there's a set of steps. How to change the time zone for an event. Well, the first thing is you have to turn on time zone support in the preferences. Okay, so let's do that. In the Preferences, we'd like to turn on time zone support in Advanced. Okay, great. Now notice we've got the time zone of the canvas here, and we also have a time zone field in the event. So let's go to Other.
choose Washington, D.C. The order of that list appears to change all the time. Interesting. Okay. And now, thank you, help viewer, 9:00 a.m. in Pacific Time. That's the actual time that you want -- that the inauguration is going to happen relative to you. So just to recap briefly, there are three ways that you can get to -- that your user can get to help content, you know.
One of them is with the contextual help buttons, which we saw in Safari. And the other two are through the help menu, either searching and finding something in the menus or searching and getting one of the help topics. Okay. So that's the demo. And if we could go back to slides.
That's the demo slide. OK, great. So Apple Help is all about help books. It's based around help books. And what is a help book? It's a list of HTML pages. We wanted to make it really easy for everyone to take the help and put it in their application. You might have help online somewhere. You probably have a FAQ.
You can spruce that up a little bit and put it in your application, just ship it as Apple Help. OK, so there's going to be-- there is one page that is designated as the access page. And that's the page that comes up when the user goes to the Help menu and selects Safari Help or Your App Help. And then there's a number of other pages that include things like troubleshooting or about a certain feature, things like this. You can split them up and you can call them whatever you like. And you can have five pages or you can have, you know, a thousand pages.
We have everything on the game. So you can have a lot of different things on the gamut there. There's also probably going to be images that are included in your help book and probably some style because it's HTML and you want it to look pretty. And then there's other things. We use WebKit. So if you would like to use XML and maybe XSLT, that works. If you'd like to use CSS3 transitions, that will work. If you want to use some of the advanced HTML4 or HTML5 stuff, all that will work as well.
So that's what Help looked like before. Help in Snow Leopard is slightly different. This isn't to say, by the way, I should mention that the old stuff doesn't work. Everything that worked before does now work in Snow Leopard, but we've added another way for you to add help to your application. And the main way that it's structured is with help bundles. So this is an entire help book, all the different localizations in one place.
There's a single bundle, and there's a single way to identify it. You're using something called--well, you actually use the bundle ID of the bundle, and in this case, we're calling it a book ID. Notice it's case sensitive, and it is not localized, which is great, because before, the name had to be localized, and it caused all sorts of badness. So this is unlocalized.
All right, so remember all those files we were talking about before? All those files plus the Info.plist, which every bundle needs to have. That's an XML file that includes information. So this is the application about the bundle. So in this case, it'll--well, we'll talk about that in a second. I don't want to get ahead of myself. All of those things go inside the help bundle. And then the help bundle, just the single help bundle, goes inside your application.
So this is what that actually looks like. You have the dot app here, and it's got a contents folder and the Info.plist. There's a couple extra keys, which if you've dealt with adding help to an application before, you will know about, and I'll talk about those in a second. There's a resources folder. And inside of that, at the same level as your localized content, you have your help bundle.
Okay, now these are the special keys that you need to include in your app's Info.plist file. And they're both required in order for Help to work. If you don't want Help to work, you don't have to have any of the keys. Okay, so the first one is the CFBundle helpbook folder, and that is going to be the same as the name of the bundle. Just loosen your resources folder.
and then there's the help book name. So that is the bundle ID of your help bundle. Now, both of those things are required to be included in the app's Info.plist file. Okay, now, inside of the help bundle itself, I showed you before that all of these files just go inside the help bundle. But where do they actually go? What does it actually look like? Well, you have the contents folder, and inside of that, again, the Info.plist metadata about your help book.
And then you have the resources folder, and inside of that is, as in any bundle, your localized project files, your L projects. This is where you put your localized content. If you're shipping help, or if you're shipping your application in 18 different languages, you're going to put 18 different L projects, and you're going to have your help for each of those languages. Okay, this is the French one. And now this is something that's new and kind of interesting.
In the shared folder, and actually you can call this folder whatever you'd like. But I call it shared in this case. You're going to put content that you don't need to localize. And this is great, because if you have a bunch of images, you've got a bunch of screenshots, you want to be able to include those without duplicating them.
If you have 18 different localizations, you don't want to have 100 kilobyte file times 18. You know, that gets really big really quickly. So you can just include it once in the shared folder. And in this case, we've put the icon there. The icon is another really good example of something that you probably don't want to duplicate, and you just need one of them.
All right, so we talked about the Info.plist for the application. Now let's talk about the Info.plist for the bundle. There are several required keys. One is the CFBundle identifier. Shouldn't come as a surprise. It is a bundle. And we recommend just including .help on the end of your application's name. So this is the reverse DNS sort of scheme. You can call it whatever you'd like, but we recommend you do this.
HPD book title. This is actually the only localized key. The only localized-- well, really, it's a value. But you have the book title, and this is going to be the same as the-- In your Help menu in your application, there's going to be an item, and it will probably say My App Help or Safari Help, and this will have the same name, and that is localized. So I'll show you how to localize that in just a second. Then the HPD book access path. This is relative to the lproj, and this is going to be the same for each of the localizations.
And then the HPDBookType, you don't need to worry too much about this. It's included. There are actually, if you would like to try this right now, in developer examples help, there's a help book-- sorry-- slash developer slash examples slash help. There is a help book called MyAppHelp. And it includes the Info.plist for the bundle, the help book. And so this includes all the things that you should need with default values. And in that place, it's HPDBookType is 3.
And you should just make sure that whenever you create a help book, you have it be 3. Now, there are a bunch of optional keys, but I'm only going to go over one of them right now. And that is the HPDBookIconPath. You probably want to include an icon.
It's going to be a 16 by 16 icon. And this is where it's used. In the place that you have a search, each of the search results includes the icon. Now, it's possible to search across multiple books at once, or at least it was in Leopard. It will ultimately be possible to search across multiple books at once. And in that case, when the results are interleaved, because they are relevance ordered, it's important to know which help book a result came from. So that's where this is used. You probably want to include that.
OK. So remember I told you I was going to tell you how to localize? In addition to localizing your content, which is the most complicated part, there's really only a few things to remember. First of all, shared files go-- in resources. Shared meaning non-localized. You are sharing them among your different localizations. All your other files go in the .lproj folders. Whichever .lproj folder. If it's a French file, it goes in French.lproj. And then there's the InfoPillars strings files. Those go inside the LPrij, just like in any other bundle, and this is what they look like.
This is the English one on the left, and on the right is the French one. Very simple, HPD book title equals, and then in quotes, the name, the localized name of your help book. And remember that file needs to be UTF-16, as with all strings files anywhere on the system.
So your HTML is largely just taken from something that you might have put online. Safari could read this with no problem. But there are a few things that Help Viewer calls out and looks at specifically. So I wanted to go over those with you. First of all, the title.
Now, the title's actually the most important element of your page, because if it's really long, then as you can see on the right here, it might get cut off. It could be elided at the end. Another place that that might be a problem is in the Help menu.
It's actually even shorter. You have even fewer characters. So you want to make sure that you use as few characters as possible and make it count. And if you can write in Chinese, then that would be great, because Chinese is much shorter. You probably don't have that option. But make sure that your titles are pithy.
OK, so in addition to the titles, maybe you've written something that's either poorly worded or there are several titles that are similar, two different pages that have the very similar titles. Your user might be wondering, well, which of these do I click on? And they could click on one and go back and click on the other.
Or they could use the tooltips. So that's what the description is for. And that provides a tooltip for them so they can get a little more information. Do I really want to look at this page? Do I want to waste the time of going forward and then coming back? So that also shouldn't be too long. This one is maybe even of questionable length, but a line and a half at most, probably.
Then there's the keywords. You include this at the top, and the purpose of this is if you want to have your users able to find something with your search results, but you don't want to actually include it in the text of your page. And you don't want to also make it white on a white background at the end, because that's lame. We don't like that. That's all 1996. So you include meta name keywords, and in the contents, you include several words. The place that we use this most in Apple's Help is for situations where there are different names for something based on whether it's Windows or Mac.
For example, desktop background. We call it desktop background, but the Windows people call it wallpaper. So if someone searches for wallpaper, we know they really want desktop background. And so you include wallpaper in the keywords string, and then that gets searched. And so when that comes up, people will assume, oh, OK, desktop background. That must be what it's called on the Mac. And then, of course, the rest of the content of your page gets indexed.
Speaking of indices, the way that indices work on Leopard and Prior is that there's something called the Help Indexer. This is in Developer Applications Utilities, and you use Help Indexer to create a Help Index file. And you would need to create one per localization. If you do that with the new help book format, the help bundle, then you need to include HPD book index path in the info.p list, and then you give that the name of the help index file, which is going to be the same for all your localizations.
However, You don't need to do that if you don't want to. And we actually have on-the-fly indexing. We added this to support the old IDX format. So--because actually, we don't use that anymore. So now your content gets indexed on-the-fly. But it's a great win for everyone else as well, even people that aren't using old index files, because your index just gets created, and Health Viewer just does it, so you don't have to worry about shipping anything like that. On-the-fly indexing, it's pretty fantastic. So we've talked all about the modern help bundle, and I wanted to bring Daniel Feldman up and have him show you how to add one to your application. Thank you, Nick.
So I'm going to walk you through adding help to your application from scratch. And I have a little bit application here. It's a little bit silly. Let me show it to you. Let's get some shoes. So this is just a little application I put together that lets you go through a bunch of pictures of shoes. And you can kind of say what you think about them. Like, let's say these are pretty hot. These shoes rule. And these not so much. These shoes suck.
Okay. Now, I know that this is based off of a popular YouTube video, but our users might be a little bit confused about what this app does. So let's check out the help. And of course, there's not going to be any help yet because we haven't made it. So let's go ahead and do that. I'm going to quit the application.
And head over to Finder. And this is my project folder. And I'm going to go ahead and make our help bundle in this folder just so it's with all the other resources that my project is going to use. I could make a new folder here and just make it into a help bundle. is the founder of Snow Leopard, a software development company that's been around for a long time. Developer, Examples, Help. OK, and it's myapp.help. So let's just bring it over. Ooh, not there, no.
All right? And we want to rename it so that it makes sense with our app. will right-click it to show the package contents. And now inside of our Help bundle, we can see the same directory structure that Nick was just talking about. So we have contents, resources, we have that Info.plist, and we have another version.plist for versioning information. And then we have our Lproj folders. In the template here, we just have English, but you would have one of these folders for each of your localizations. Inside of there is going to be your content. This is just a placeholder here, this HTML file.
There's an Info.plist.strings. That's going to be for localizing any of your values in the Info.plist. We'll get there. And then there's the shared folder that Nick was talking about. And you put anything in there that you want to share between your localizations. So let's go ahead and add our content. I've prepared some content for this demo. Let's just bring it over.
And this is how I chose to set it up with HTML in a separate folder, with my access page up front, and with some localized images. But of course, you could set this up any way that you like. I also have some shared content. Let's get rid of this icon that's in there. And I'm going to bring over the shared stuff.
Nick mentioned images, but CSS is another thing that's usually not going to be localized, and so you can go ahead and put that in your shared folder and save on a little bit of file space. I'd like to show you some of these HTML files. Let's go ahead and look at them in Xcode. It's just standard HTML. A couple things that I do want to point out to you are these relative URLs, so this is how I get to the CSS.
The file that we're looking at is in the lproj, and it's just like you would do on a web page. If you want to get back one folder, it's a couple of dots, and then we go inside the shared folder, inside CSS, and then we get to our file. Same thing if we're accessing a shared image. It's just a relative URL if we're accessing another HTML page, too, if you want to link to that. So it's basically plug and play with content that you would have on your website. Let me show you one more page.
[Transcript missing]
This is what's going to come up right here at the top, and also what's going to come up here in the menu. So that's why this is something that we want to be localized. And I'll show you how to localize that in just a minute. The book type is always going to be three. That's actually just the version number of the book format.
The icon path-- we actually named our icon lowercase, and it was actually a JPEG. Let me show you where that was. Back in Finder--
[Transcript missing]
So our access page is going to be shoeshelp.html, and that's right in here, and that's only relative to the Elk Barrage folder.
These next three keys are about a little bit more advanced features that we'll get to in a minute. For the purpose of this demo, I'm not going to be using them, so I'm going to delete them, and it's important that you do that in the seed. Help Viewer at the moment is having a little bit of trouble with empty strings in this file, so for the seed only, go ahead and delete these.
The identifier is going to be a unique way that Help Viewer and your application can refer to your help book. And we have the convention here that we suggest that you follow, which is com.yourcompany.myapp.help. So in this case, my fake company is called Kelly Soft, and my app is Shoes. The bundle name is going to be whatever we called our bundle. So it's shoes.help. And so the bundle name is just going to be this part. It's going to be shoes.
These next few values are just things that are standard in bundles, and we're just going to leave those as is. So let's skip over those. And versioning is important. If you're making changes to your help content and you want to keep track of which version is which, just like if you're making changes to your application, then you can use these versions to keep track of which version of your content you're talking about. And the development region is another one that you're probably going to want to keep as ENUS. So great, we've edited our Info.plist. We have our content. I just want to do one more thing in the bundle, And that's to come back here and edit the Info.plist.strings.
So HPD book title was that the one key in the Info.plist that I showed you that comes up at the top of Help Viewer. And this is how we're going to localize it. So for English, it's going to be shoes help. If I was editing the Info.plist.strings in the German Elproj, then this would be shoes hilfa. Of course, this is English, so we'll leave it as help.
So we've put our content in here, we made our info playlist, we localized the one key, it looks like our bundle is good to go so I'm going to go ahead and add it to our Xcode project. All I'm going to do is just drag it into Xcode to the resources.
I don't need to copy it because I already put it in that folder but I do want to make sure that I choose to create folder references that way if I add or remove any files on disk either in the finder or if I'm working on my HTML and some other HTML editor, Xcode will show you the new files in the left-hand side as opposed to if I chose groups then I would have to add the new files myself.
So let's do create folder references and add it. We're almost there. I'd like to edit the info playlist for the application now. This is not to be confused with the info playlist that was in the help bundle. There's a couple keys to add here. Again I'm going to right click and show the raw keys and values so we can see what we're talking about and I want to add two here. I want to add CFBundle help book folder And I want to add CFBundle Help Book Name. The folder is going to be the whole name of the bundle that we just made, shoes.help.
And the book name is going to be that identifier that we made in the last Info.plist. And that needs to be exact, and it is case sensitive. So com.kellisoft.shoes.help. All right, we've done that. Now one more thing. You'll notice that when we opened Help the last time, the menu actually said New Application Help. Well, that's no good. The way that we're going to change that is in the ZIP. So I double clicked it to open it in Interface Builder.
My menu is down here. And what I want to do is just double click in here and edit this and make this shoes help so that our users know that it's not a new application. It is, in fact, shoes. So now we have made our bundle, we put it in the project, we edited our ZIP in the application info P list so it knows which book to call, and let's go ahead and clean our project and run it again.
Let's get some shoes. All right, so... These shoes suck. Obviously, those shoes are no good, but let's see if we have some help content now. So it does say Shoes Help, which is what we wanted, and when we choose that, there it is. There's our help content, just HTML that came up. Our users can now see that this ridiculous app is based on a popular YouTube video. Our URLs take us right to another page, and without having done any additional work, we can actually already search our content.
So if I go ahead and search for shoes, I can do it here, I can do it in Help Viewer. I can also go up here to the Help menu, and I can search for parents, let's say. Learn how to deal with them, it's a tricky issue. And we didn't have to do any of that in our content or in our bundle. Help Viewer, behind the scenes, is indexing all of our content and putting it there so we can search it quickly and easily. And that's all that it takes to add help to your application. Let's go back to slides. Thanks.
Thank you very much, Daniel. All right, so in Help Viewer, there are a number of things that make Help Viewer better than just using Safari for all of your HTML help. One of them is remote updating. You can put your content, which you have locally, you've shipped with your application, you can put that online, and when the date changes, as you can see here, this one is from January and that one is from today, when you have that situation, Help Viewer will recognize it, and if the user's connected to the Internet, they will download the stuff actually in the background, actually on the fly is the right way to say that.
The way that it does that is it uses the HPDbook remote URL. Now, this is included in the Info.plist for the book. And you get to choose what that URL is, obviously. You will put your help bundle on a server somewhere. And then HelpViewer will take that and concatenate the path on disk to the file that you're talking about. You are loading index.html, or you're loading pages2 slash file.html. And in that case, it will append it to the URL, and then you'll get-- The result, assuming you're connected to the internet. So let me show you how that might actually work.
If you have both local and remote content, and the remote content is newer, then Help Viewer is going to obviously know that the local content is there. It's version 1.0. And it's going to look in the cache to see if there's anything newer. There isn't. And so it's going to check remotely and say, hey, has this been modified since January 1st? Well, in this case, it has. So the cache is actually going to get filled up with a version, the newest version. and then that's the one that we're going to use.
A different case, local only. You don't have any remote content, but you've included a URL in the remote URL version, or key in your Info.plist. So in this case, Help viewer knows about the local version. looks in the cache, finds nothing. If you're connected to the internet, it will look remotely. But since it finds nothing, it will go ahead and use the local version.
and I will be presenting a series of videos on the new format. For more information, please visit www.apple.com/help. Thank you. All right. So in that situation, there's nothing locally, but we've clicked a link or something. So Help Viewer knows the page should be there and knows where it's supposed to be.
So in this case, it looks in the cache, and it finds something, but it wants to make sure that it's the newest one. In this case, it is. So it doesn't need to download anything new. It just uses the one that's in the cache. Check mark, good to go.
So the way that you set this up, it's really simple. There's actually just three simple steps. The first one, put your help online. Figure out where the URL is, and then include that in the book's Info.plist in HPDbook Remote URL. And the third step, well, there is no third step. Yeah, that's old. OK.
I'd also like to talk about anchors. This is one of the other advantages of Help Viewer over using just Safari. So when you have a page, you can include an anchor in it. And it's just a name equals and then the text of your anchor. There's the anchor right there. And then from another page, you can use a help:anchor link. So you include the same text as the anchor. And then you also include the book ID, which we've been talking about a bunch here. I used kellysoft.shoes.help as this example.
So now you can click on the second link on page two and go to page one. But you don't need to know what page one is called. And this is also useful for going from an application into your help content. Your application developers don't need to have to know-- or yeah, they don't need to know what's going on in your help content. They're probably done by different people. And so if there's just a single token that goes one to the other and maps, then your help content can figure it all out and not even worry about interacting with the application.
So notice the anchor. This says it's not localized. It's a good idea not to localize them. But it is in the localized section of your folder. So if you wanted to localize them, you could. But that would be crazy. Don't do that. Multiple results behave like a search. You don't have to include just one anchor per page. You can include an anchor on four different pages. And so now you have a link-- now you have an anchor.
And you can see that on, say, an index page, you might want your user to have information. But there's four different pages that are all relevant. So they just click the single link. And then they get search results. Now they can see, oh, these are four different pages that are all relevant to my request. And then the last thing, the reason that this is beneficial is you don't need to know the path. You don't have to know what the file name is. And actually, we have definitely found it at Apple.
If you use paths directly to links-- if you use paths to a specific file name, it's likely to change. The help content gets revved just like the application does. So the fewest number of changes that you need to make, the better. Daniel will show you about anchors in just a second.
So now I wanted to talk about the way that we've changed Help Viewer in Snow Leopard. It used to be that there was Help Viewer, and Help Viewer was just this monolithic application. There was Help Viewer, and there was a framework, and that was it. Well, we had to make some changes in order for the Help menu to work and to have the same results in Help Viewer and in the Help menu. So now there's Help Viewer.
it looks the same, but it is slightly different. HelpView is responsible for launching three things. Launching in the case that you are on a website, say, and you get a help colon link, and now you've brought your users into your help content, or an application and you pass a help URL to NSWorkspace.
In either of those cases, HelpViewer will open. It will handle the URL. It will figure out what needs to happen. The second is HTML display. The web view, which is what displays all the content, that's included in HelpViewer. And everything to do with that is handled by the HelpViewer process. And then fetching remote pages. All the previous slides we talked about fetching, that all happens in HelpViewer.
Now in Snow Leopard, there is a help daemon. We call it helpD. Pretty self-explanatory, as far as names go anyway. It's responsible for indices, making the indices, or dealing with them if you provide them yourself. And with these indices it does the searching. So all of your search queries, all of your anchor searches, all of those happen in helpD. Help Viewer understands that they need to happen and then passes them over. And it also deals with book registration, which has become less and less relevant because it's done for you automatically in NS Help Manager.
But that's where it's handled. OK. Now there's a couple of things that we've added to Snow Leopard specifically for you, not just in general, but specifically for developers. And the first one is a developer mode. It disables the floating window, and it provides for Help Viewer to be an application with a dock icon and a menu bar. The way that you turn this on is you can say defaults write, com.apple.helpviewer, dev mode yes, just like in Safari. And yeah, did I mention that it doesn't float? OK.
I don't want to encourage that necessarily, but we understand that there's two different types of people using Help Viewer. There's your mother and possibly your grandmother, if she's savvy. And there's you, and you use Help Viewer all day. So we understand that having a window that doesn't layer when you're developing help content can be really annoying, so we added this feature for you.
Okay. And then there's also a whole bunch of logging that we've added. It certainly can happen that there's a problem somewhere, either with the network or your help book isn't set up quite right, and we want you to be able to diagnose that. And so the way that we have done that is we added a whole bunch of logging, and you can choose either 0 to 3 in the HelpD case, 0 to 4.
Play around with this. I keep mine on three and three. Four on Help, they actually list all of the search results for each search, which gets really verbose if you're doing a lot of searching. So I found that a little too much. All right, now Daniel's going to come up and show you how to add help buttons to your application, contextual help buttons.
[Transcript missing]
Let's get them! That's one option. The other place that we maybe want to put this button is here in the preferences. So we allow our users to actually choose what they think is expensive, and let's just link them to the same page here and give them some idea of what to do as far as setting what price they think is expensive.
So let's quit our application and go ahead and do that. And I actually want to add those buttons in two different ways. I'm going to add the one in the preferences window first. I'm going to double click the zip file, and that's going to take us back to interface builder. And so here's our preferences window.
[Transcript missing]
So here's the methods that we're interested in. Open Help Anchor in a particular book. That's what we're going to be using. You could also use Find String if you want to have Help Viewer open and immediately search for something. And then there's some pretty cool stuff down here about context-sensitive help. So if you're interested in that, I definitely encourage you to take a look at NS Help Manager.
So we're going to be using Open Help Anchor in book, but what anchor are we going to be using? Well, it needs to be in our content. Let's go ahead and put it there. So I'm going to delve down into our content. And I want to edit expensive.html. And just right inside the body, I'm going to add an anchor tag.
Close it up. And I'm going to use this exact string in my application to refer to this particular anchor. So I'm going to put it right in here. And then the book is going to be referred to by that same identifier that we used in the Info.plist in the last demo. So that's com.kellysoft.shoes.help. And again, it is case sensitive. So now we've added our anchor. Let's go back to IB. And we're going to wire it up.
[Transcript missing]
and here's what we're concerned with displaying help. There's an alert show help delegate method. If you're new to the system, delegates work like this. A lot of Cocoa classes allow you to set a delegate object and later on when they're doing certain things, they call specific selectors on the object you said was the delegate and your delegate is supposed to respond to them. In this case, we're going to do alert show help. So here's a little bit of information about it. Our delegate method needs to look exactly like this and actually I've already gone ahead and implemented it right down here.
So that means when the button in NSAlert is clicked, it knows who the delegate is and it's going to call this method on it. I set the delegate right here. Let's uncomment that. So the delegate's going to be this object and I also want to set show's help to yes and that's going to tell it to display the button. Let's go ahead and clean it out.
And run it again. Let's get some shoes. And let's look at our preferences again. Great, now our button is there. And if we-- These shoes suck. If we find another one of these dialogs-- These shoes-- these shoes-- these shoes rule. There it is again. Now when I click it, it should take me right to the page where I added that anchor. But in this case, it's not going to work. And I'm going to tell you why.
So I guess it did work, actually. But it shouldn't have. One thing that I want you to be aware of is that because we're indexing on the fly and you're not making your own index, Help Viewer in the seed is not currently aware of any changes that you might make in your HTML. It's not going to know to reindex. It might change this in the future.
We invite your feedback if you'd like to give it to us after in the lab. But if you run into a case where you changed something in your content and it's not showing up, your searches aren't working exactly right, I want to show you how you can get rid of the cache. An easy way to do that is in terminal. We're going to just remove the folder that's at tilde slash libraries library caches com.apple.helpd. And it's not there. But if it was there, that would get rid of it.
Oh, yeah. Thank you. It was there. It's called helpd. So that got rid of everything inside of it, included the generated indices. And now you'd be able to refresh and see your latest content. The other thing that you want to do is to make sure that you kill helpd because it's already started. It has some state. And you need to get rid of that.
And if you ran into the situation where this wasn't coming up-- The issues are $300. Then that would clear out the cache and allow you to properly search and get to the content that you want. So that's how you add help buttons in two different ways to your application. And it's also how you use-- use anchors. Thank you. Let's go back to slides.
Can you hear me? Oh, there we go. Okay. All right, so we've mentioned this a couple times now. Help Viewer is not done for Snow Leopard. There are a few things that still need work, and so we wanted to let you know so that you don't bang your head against a wall. First of all, you need to make sure that you pull out empty values in the info.p list for a book.
[Transcript missing]
So that's pretty much it. Help is fantastic. We want you to use it, and your users want you to use it. It makes your app more professional, and it makes your users better able to use your app and to become expert users of it, which breeds love, I think, of your application. So help bundles rock, and they are Snow Leopard only. So if you're going to be releasing a Snow Leopard only app when Snow Leopard is released, then you can use help bundles.
Going forward, we'll be using help bundles in the future, and we will be deprecating the old--in fact, consider them deprecated now--the help folders. Obviously, if you need to release an application that works on Tiger and Leopard, then you're going to need to use help folders for the time being. And lastly, indexing is so 2007. You can--as long as your app is shipping on Snow Leopard only, whether or not you use help bundles, you don't need to put indexes in there. Because we'll make them for you.
There is a lab if you have any questions, or if something isn't working, or if you would just like to come chat with us, because we might be lonely. I don't know. We don't tend to be lonely. Usually the labs have a few people in them. But you're welcome to come. Please come talk to us. We'd love to see you.