Making a new card for Newton Names

By Ashish Mishra, Vice-President, Sine of the Times





(C) 1997-1998 Sine of the Times

Parts (C) 1995-1997 Apple Computer, Inc.

Parts (C) 1998 University of Waterloo





You may use the following documention and code with the following conditions:



1. You will not sell this code or documentation.

2. If you distribute the code, you must include the documentation unchanged.

3. You are not permitted to commercially or privately retail any products that originate from this source code, or ideas developed in this application.

4. Sine of the Times will not be held liable for usage of any card.

5. Sine of the Times will *not* provide support for this code or documentation.  This is an *as is* release and is freely distributed.

6. For any software that you create using the included documentation or code, you must make it clear that it is a descendant of Sine of the Times code & documentation.





Pre-Lab:

It's pretty easy to add a new card in concept.  In practice there's

alot of little details.  Here's a run-thru that should

make it considerably easier to make a new card.  (I still can't

promise success on the first compile - but you will be close!)





Procedure:



Setting up the files

1.  Duplicate a project file, and change it's name

2.  Duplicate a Components directory (like CD or Book) and change it's name

3.  Open a project in NTK, remove the three layout files

4.  Add the new layout files to the NTK Project from your new directory

5.  Make sure Stationery Project Data is the last file to compile



Changing the Project

1.  Project Settings...

2.  Change Name, and Symbol to be alphabetically after "Ca"

(they need to install after CardMedia in the case of restart)



Changing the Data Definition

1.  Open the data_def.layout

2.  Change the description

3.  Change the icon (this is for the New Menu)

4.  Change the Name to your object's Name

5.  Change the overviewicon (this is for the overview)

6.  Change StringExtract to output the string you want to see in

the overview.



.... else return ParamStr("^0",[entry.<your  slot>]);



<your slot> should typically be like  'name,  'title, 'item,

you get the idea - the actual "name" of what you're making



7.  Change ViewsToDisplay



These are the views and their order that will be displayed

in All Info. 



This is the first place you must identify EVERYTHING that will

be part of your card.  Each part of your card that you need to 

record, say like Length, will have a slot in the entry, and will

also be something a user wants to see in All Info.  Thus stick

it here.



(A) List all slots your user will need to see in All Info - here.

You must have as a minimum: 'default, 'current, 'released, 'purchased, 'custom, 'editNotes



For example, here's my video stuff:

['default,'stars,'producer,'story,'music,'studio,'category,'rating,'recording,'length,

'current,'released,'purchased,'custom,'editNotes]



You'll probably modify some of the symbols in here later after looking

at the Stationery Project Data file (next) so leave it open...





Changing the Stationery Project Data file

1.  Open the project data file

2.  In the installScript, and an else if kAppSymbol='|your symbol|

just like the rest

3.  Just copy the statement RegisterViewDefs for as many symbols

as you have added to your ViewsToDisplay.  You don't need to count

the 'default, 'current, 'released, 'purchased, 'custom, or 'editnotes

They're already handled for you.

4.  Wherever possible, if you can find a RegisterViewDef that

comes close to what you need, then use it!



For example, I need a "type" slot for Videos - ie. what kind of

movie is it?  Is it Action, romance, etc?



So I look through the RegisterViewDefs, and no "type" is found.

But, I found this:  CATEGORY



RegisterViewDef(GetViewDefs('|cardMedia:soft|).category,kAppSymbol);



So I use this instead.  Why?

For every unique new slot, we're going to have to create a new viewDef

for it.  So if we can re-use something else, we save ourselves

time, plus keep the package smaller.



For a list of all the views we've already got, close this project

and open the CardMEDIA project.  They're listed as layouts.  If

you can use one of these, then try to.



For example, here's my video stuff:



	else if kAppSymbol='Video:soft| then begin

			RegisterViewDef(GetViewDefs('|cardMedia:soft|).stars,kAppSymbol);

			RegisterViewDef(GetViewDefs('|cardMedia:soft|).producer,kAppSymbol);

			RegisterViewDef(GetViewDefs('|cardMedia:soft|).story,kAppSymbol);

			RegisterViewDef(GetViewDefs('|cardMedia:soft|).music,kAppSymbol);

			RegisterViewDef(GetViewDefs('|cardMedia:soft|).studio,kAppSymbol);

			RegisterViewDef(GetViewDefs('|cardMedia:soft|).category,kAppSymbol);

			RegisterViewDef(GetViewDefs('|cardMedia:soft|).rating,kAppSymbol);

			RegisterViewDef(GetViewDefs('|cardMedia:soft|).recording,kAppSymbol);

			RegisterViewDef(GetViewDefs('|cardMedia:soft|).length,kAppSymbol);

	end;

			

Now if you do find something close to what you need, make

sure to update the ViewsToDisplay symbols to match the same

symbols you are registering.



8.  Not done yet!



Now we have to ensure that we UnRegister the viewdef if the

user decides to remove the package.  (Why would they? :)



So go to the RemoveScript.  Again, you just need to UnRegister

your new slots.   Don't remove any that are already removed.



Just add your removals for UNIQUE viewDefs



If you're using some viewDefs defined elsewhere (which is likely)

then they'll already be removed for you - and you don't need to

do them.



So for the Video slots, I did:



	UnRegisterViewDef('stars,kAppSymbol);

	UnRegisterViewDef('producer,kAppSymbol);

	UnRegisterViewDef('story,kAppSymbol);

	UnRegisterViewDef('music,kAppSymbol);

	UnRegisterViewDef('studio,kAppSymbol);

	UnRegisterViewDef('length,kAppSymbol);

	

Category, Recording, Rating, Released, Purchased, Current,

Custom, EditNotes, etc.

were already removed for me.



(See this isn't as easy as it appears.  There's a couple of steps

involved!)



9.  Save and close the Stationery Project Data

(Don't close your project - you're going to be needing it still)





Creating the ViewDef Layouts for CardMedia

1.  For every new symbol you had to create, now you have to add

 a layout for it for CardMedia to retrieve and save as a viewDef

2.  Lets go to the ViewDefs Folder.

3.  We're going to make a layout for each new symbol

4.  Try to find the closest thing in functionality that matches

your symbol, and duplicate that file.



For example, for Stars, the closest thing I could find was



view_authors.layout



So I duplicated this, and changed it's name to view_stars.layout

5.  Next open the new layout in NTK

6.  In the InfoFrame, change the checkPaths, and FormatFunc

to the symbol you are using.



For example:



{checkpaths: '[stars],

checkPrefix: '[TRUE,nil],



	formatFunc: func(data) begin 

		ParamStr("Stars: ^0", data);				// return string to show in All Info view

	end,

}

7.  Change the Name slot to your symbol's name, eg. "Stars"

8.  Change the symbol slot to match your symbol, eg. 'stars

9.  Click on the NewtLabelInputLine or NewtNumberLine

10.  Change the Label to match your symbol's name, eg. "Stars:"

11.  If the data being recorded by this slot can be repitious,

you'll need a memory slot.  If it's already there, then just change

it.



For example, for stars, my memory slot has:

'|stars:soft|



12.  Lastly, change the path to be the same as your symbol

eg. 'stars



That's it.  Nasty huh?  You'll have to do steps 3-12 for every

new slot.  Now you know why we should try to re-use layouts!







Updating CardMedia Project Data

1.  So you survived the last step!  Excellent

2.  Finally, Close your new project and open the CardMedia project

3.  First thing we have to do, is add the layouts to CardMedia

So go to Add File and choose the ViewDefs folder

4.  Add every file that shows up in the folder

5.  Don't move the CardMEDIA project data file yet.  We're going

to use it as a pointer to the file we have to update.

6.  Instead, open the CardMedia Project Data file

7.  In the installScript, do a RegisterViewDef for all the new

layouts you've just added.

8.  In the removeScript, do a UnRegisterViewDef for each of

the new layouts you've added.  You'll need to specify their

symbol

9.  Now move the CardMedia Project Data file to the bottom of

the project

10.  Save, build, and download to your Newton

11.  If everything is successful, then reset your Newton

12.  Close the CardMEDIA Project





Making the Default layout for your Card

1. Open your project again

2. Open the default.layout

3. Let's take a look



The default layout is the first layout the user sees when they

try to make a new card.



At most your default editor should have 6 entries, just the one's

most likely to be used when a user creates a new card.  More than

6 congests the screen, and confuses them.



4.  the top level CLVIEW has:



infoframe:

In here you must specify the symbols (upto 6) you deem as most

important when creating a new card in the CheckPaths.



For example, for the Video card, I think users will want to

enter this information first above anything else



checkpaths: '[title,stars,producer,studio,category,rating]



All those other slots we added are secondary information that

will show up in the "Add" picker.



5.  Change the name slot of the top CLVIEW to "your editor"

6.  Okay, we're done with the top view.



7.  Next thing we need to do is change the names of the

NewtLabelInputLines



Let's just do a Template Info Command-I  on each, and 

change their names.



8.  Okay, after changing their names, let's change their contents.

9.  Click on the first NewtLabelInputLine



Change it's label, path, and memory to match those we specified

in the actual ViewDef for these



Note that for Title we never had a viewDef - that's because the

'default view we're working on right now, IS it's viewDef!



10.  That's it.  Close the layout.





Changing the Physical Card

1.  Okay, almost near the end!

2.  Open the card.layout

3.  Again, like the default view, we see a max of 6 elements

on and one big picture.  This is the card that the user sees.

You want to keep it as uncongested as possible.



4. in the top CLVIEW

increment the BizCardNumber (last I used was 2004)

you should use 2005 and so on...



5.  Change the Name to "your card"

6.  As we did before in the previous section, let's do a

Template Info on all the other slots, and change their names

to reflect our card



I recommend leaving release_year, category, and rating as they

are.



7.  Okay, now we have to go through each of the templates that

we changed the names for



8.  Each will have a ViewSetupFormScript - that's all we have to

change



9.  For example, for Stars, I would change the ViewSetupFormScript

to be:



func()

	begin

		self.text := target.stars;	// get data out of soup entry

		inherited:?viewSetupFormScript();

	end

	

10.  Do that for all the ones you've changed

11.  Last thing you'll want to do is create a big picture to stick

in the pictureView.  This is the fun part!







FINALLY!

1.  Build, and download to your Newton.

2.  If everything goes fine, you'll be able to add a new card to

your Newton Names.







Congratulations for Surviving "Cards 101"  !





(NOTE: Sine of the Times provides no support for this software,

nor will answer email regarding this application,

unless you are a registered user of CardMEDIA)