============================================================HyperNewt 2.0 Developer APILast Update: September 1, 1997Copyright (c) 1997. Foundation Systems. All Rights Reserved.=============================================================================TABLE OF CONTENTS=================  1. Developer API      A. The HyperLink Manager    B. Creating a HyperLink Manager    C. SaveHyperLink Function Overview    D. ShowHyperLink Function Overview    E. Sample HyperLink Manager Soup Entry    F. Soup Definitions and Soup Names    G. Sample Code And Submitting HLM's -------==============================================================----------===                       1. DEVELOPER API                         ===----------==============================================================-------The following information is for developers who are interested in creatingHyperLink Managers for their own applications. Any application that supports2.x routing of data can use HyperLinks. A developer need only to create aHyperLink Manager (HLM) that handles the saving of and display of HyperLinkeddata.    ======================================    ---=== A. THE HYPERLINK MANAGER ===---    ======================================    There are two types of HyperLink Managers, differentiated only by the type ofdata that they support:1. Soup data: Data being HyperLinked are soup entries2. Non-soup data: Data being HyperLinked do not belong to a soup.Among the default HLM's installed with HyperNewt, the following applicationsuse (1) HLM's to store HyperLinks:        Calls        Cigar Box        Dates        Gulliver        Home Inventory        In/Out Box        MORGAN        Names        NewtWorks        NotesAmong the default HLM's installed with HyperNewt, the following applicationsuse (2) HLM's to store HyperLinks:        Dates        Extras Drawer        Copperfield (Newton Books) As you can see, some applications have both a Soup HLM and a Non-Soup HLM tohandle all the types of data that they deal with.    =============================================    ---=== B. CREATING A HYPERLINK MANAGER ===---    =============================================HLM's are store in the HyperLink Manager soup on a Newton device. Each HLM mustcontain 3 required slots:======================Soup HLM required slot======================  a. soupname: The name of the soup where the data being HyperLinked is     stored.==========================Non-Soup HLM required slot==========================  a. appsymbol: The symbol for the application from which the HyperLinked     data belongs.  ========================================================HLM required slots -- ALL HLM'S MUST CONTAIN THESE SLOTS========================================================  a. SaveHyperLink: Function that creates the HyperLink information frame for     HyperNewt.  b. ShowHyperLink: Function that takes a HyperLink information frame and     displays the found entry, if there is one, to the user.The SaveHyperLink and the ShowHyperLink methods are outlined in more detailbelow:    ================================================    ---=== C. SaveHyperLink FUNCTION OVERVIEW ===---    ================================================This function takes the soup entry or data that is being HyperLinked andreturns a frame containing a HyperLink Information Frame and a displayable texttitle and icon to HyperNewt. The HyperLink Information Frame must contain thefollowing slots for each type of HyperLink Manager being created:        // For Soup HLM's    DefConst('kDefaultSoupHyperLinkInfoFrame,	    {            soupname: nil,            timestamp: nil,                        shortTitle: nil, // Optional string        }    );          // For Non-Soup HLM's      DefConst('kDefaultNonSoupHyperLinkInfoFrame,        {            appsymbol: nil,            timestamp: nil,                        shortTitle: nil, // Optional string        }    );The SaveHyperLink functions takes one parameter, the soup entry or data beinghyperlinked. It is the responsibility for the developer to decide, beyond therequired slots, what information she wants to add to the HyperLink InformationFrame that can locate a HyperLinked entry at a later date.Many people will choose to store an EntryAlias, for soup entries, in theHyperLink Information Frame. Remember that if an entry is moved to anothercard, then that entry will be unresolvable from a HyperLink.    ================================================    ---=== D. ShowHyperLink FUNCTION OVERVIEW ===---    ================================================This function takes a HyperLink Information Frame to some data that has beenHyperLinked and displays the entry, if it exists, to the user. Since thedeveloper has written the SaveHyperLink method, she would know how to retrievethe data and display it to the user.If your application saves data to soups, you may want to try using HyperNewt'sdefault method for displaying a HyperLinked entry. Call the root method withthe following syntax:	constant kAppSymbol := '|HyperNewt:ATOW|;    GetRoot().(kAppSymbol).DefaultShowHyperLink with (entry, appSymbol);where appsymbol is your application symbol and entry is your soup entry.HyperNewt will automatically open your application and call the methodShowFoundItem with (entry, {}) as its parameters:    GetRoot().(appSymbol):ShowFoundItem(entry, {});If you cannot find the entry that has been HyperLinked, return nil andHyperNewt will alert the user that the original item could not be found.    ====================================================    ---=== E. SAMPLE HYPERLINK MANAGER SOUP ENTRY ===---    ====================================================The following code snippet details a sample HLM for the Notes application. Anynote that is HyperLinked will use the following HLM:	/* kPaperRollSaveHyperLinkFunc	 * ---------------------------	 * This function extracts the title string and icon from the stationery's	 * dataDef. It saves in the HyperLink Information frame the shortTitle	 * (taken simply from the entry's title slot), an EntryAlias for the	 * entry being HyperLinked, its class symbol, the soup name (required),	 * and the entry's timestamp (required).	 *	 * This function returns a standard information frame back to HyperNewt	 * to continue creating the HyperLink.	 *	 */DefConst('kPaperRollSaveHyperLinkFunc, func(entry) begin	local entryDataDef := GetEntryDataDef(entry);	local hyperlinkinfo := Clone(kDefaultSoupHyperLinkInfoFrame);	local title, icon;			if entryDataDef then begin		title := entryDataDef:StringExtract(entry, 1);		icon := entryDataDef.icon;	end;	hyperlinkinfo.shortTitle := entry.title;	hyperlinkinfo._alias := MakeEntryAlias(entry);	hyperlinkinfo.class := ClassOf(entry);	hyperlinkinfo.soupName := ROM_paperRollSoupName;	hyperlinkinfo.timestamp := entry.timestamp;			return { title: title, icon: icon, hyperlinkinfo: hyperlinkinfo };end);	/* kPaperRollShowHyperLinkFunc	 * ---------------------------	 * This function tries to first resolve the entry alias	 * for the note stored in the hyperlink. If present, the function	 * calls a default method of HyperNewt to display the entry,	 * otherwise nil is returned (and HyperNewt will alert the	 * user that the original item could not be found).	 *	 */DefConst('kPaperRollShowHyperLinkFunc, func(hyperlinkInfo) begin	local entry := EntryFromObj(hyperlinkinfo);	local app := GetRoot().('|HyperNewt:ATOW|);		if entry and app then begin		if app:PrefsLookup('displayWithNotepad) then			return call app.DefaultShowHyperLink with (entry, 'paperroll);		else return call app.DefaultShowHyperLink with (entry, kAppSymbol);	end;	return nil;end);The complete HyperLink Manager soup entry frame for the Notepad HLM is shownbelow. Add this entry to the HLM soup to support the use of HyperLinks in theNotepad application:  {    soupname: ROM_paperRollSoupName,    SaveHyperLink: kPaperRollSaveHyperLinkFunc,    ShowHyperLink: kPaperRollShowHyperLinkFunc,  }    ====================================================    ---=== F. SOUP DEFINITIONS AND SOUPNAMES ===---    ====================================================The following are the soup definition and soup name for the HyperLink ManagerSoup. When creating a HyperLink Manager, be sure to check for the presence ofthe HyperLink Manager soup before hand. To ensure proper operation, *DO NOT*create the HyperLink Manager Soup if it is not present. HyperNewt installs the default HLM Soup only if it is not currently installed.If you create and add one entry to the HLM soup, new users will not be able touse HyperLinks in any application other than your own.DefConst('kHyperLinkManagerSoupName, "HyperLink Manager");DefConst('kHyperLinkManagerSoupDef,	{			name: kHyperLinkManagerSoupName,		userName: kHyperLinkManagerSoupName,		ownerApp: kAppSymbol,		ownerAppName: kAppName,		userDescr: "This soup is used by" && kAppName,											indexes: [					{ structure: 'slot, path: 'appsymbol, type: 'symbol }, 					{ structure: 'slot, path: 'soupname, type: 'string },				 ],	});    =================================================    ---=== G. SAMPLE CODE AND SUBMITTING HLM'S ===---    =================================================The code for all the default HLMs that ship with HyperNewt is available fromthe HyperNewt web page at:    http://www.tow.com/newton/hypernewt/    If you come up with a better HLM for any of the default HLM's, email yoursolution to Foundation Systems and we will consider it for inclusion in thenext release of HyperNewt. If you have an application that supports HyperLinksand would like your application's HLM to be included among the default HLM'sthat ship with HyperNewt, again, email us and your HLM will be considered forinclusion.