Metadot Forms Files

This is an alpha release of the Metadot Forms Gizmo. You should expect bugs.

Things are sure to change, and Forms and Cards you create with this version may not be compatible with future versions.

You can try this package without install at:
http://www.coolname.com/mgo/forms


v 3_1_2-0_1_3_1 adds support for perl 5.6

To UPGRADE see instructions following Installing.

-----------------------------------------------
 Installing
-----------------------------------------------

Requires Metadot 3.1.2 and no other version (download and install first)

1) Backup metadot as described in the Metadot documentation

2) move the tar file metadot_forms_xxx.tar to your metedot-user directory (metadot's INSTALL and README me should be files in this direcftory, and metadot and html should both be subdirectories) gunzip it, and untar with tar -tvf.

3) cd to the metadot directory and create the form defintions the forms editor itself uses with
perl form_import_sys<form_sys.out

4) restart Apache (we do not recommend -HUP with metadot)

5) Use your browser to look at your home metadot page.  You will see 3 Forms and 1 Deck of Cards under the main menu.
Move the Forms: ~TEMPLATE~ and ~FIELD~  to a safe place (and leave alone)

6) please fill in our survey at
http://sourceforge.net/survey/survey.php?group_id=29602&survey_id=11870

There are only 3 questions - come on, please fill it in.


-- you are done ---.


Gettig started:

"Creature" and "My Creatures" together are an example.  Use, abuse or delete them.


DO NOT START by editting ~TEMPLATE~ or ~FIELD~.  See the FAQ below if you must, but leave ~TEMPLATE~ and ~FIELD~ completely alone for the first hour.




-----------------------------------------------
 UPGRADE
-----------------------------------------------

For 0.1.2.0 -> 0.1.3.1 or  0.1.3.0 -> 0.1.3.1

1) un-gzip and untar the package
2) restart Apache



For All Other Upgrades

If you do NOT need to keep Forms and Cards you have created
1) Delete all card and deck, then delete all Forms
2) Install as described above



To keep Card and Forms you have already created:

1) Rename the Forms: ~TEMPLATE~ and ~FIELD~ to OLD~TEMPLATE~ and OLD~FIELD~
2) Install as described above

If you are happy with your pre-existing Forms not being able to use the nwe DisplayLooks, then you can stop.

3) Click into ~FIELD~ (the new one) so you see the table.  It's URL should have "index.pl?iid=5234&isa=Form" and some other stuff in it.
4) Note that number, and think of it as XXXX
5) In mysql type the follwing
update instance set i5 = XXX where isa in ('Form','Field_Definition');

6) Check that your old Forms now offer the new DisplayLooks, and then you can delete OLD~TEMPLATE~ and OLD~FIELD~ if you wish.


-----------------------------------------------
 De-Installing
-----------------------------------------------

1) BEFORE you remove the code, remove all Cards,Decks and Forms.
Do one of:
- use the UI to delete all Cards,Decks and Forms
- use mysql to delete these with:
  delete from instance where isa in ('Card','Form','Deck_of_Cards','Field_Definition');

2) The files that were installed are:
metadot/Form_README.txt
metadot/Form_Proto.pm
metadot/Form_Field_Proto.pm
metadot/Gizmo/Card.pm
metadot/Gizmo/Form.pm
metadot/Gizmo/Deck_of_Cards.pm
metadot/Gizmo/Form/Field_Definition.pm
metadot/form_dump_sys.pl
metadot/form_import_sys.pl
metadot/form_sys.out
html/images/form/off.gif



-----------------------------------------------
 Mini FAQ:
-----------------------------------------------


1) What do: Add New Card, Deck of Cards, FORM do?
2) If I set a field minimum to 10, why can someone save nothing?
3) How do I do money   $9,123.05  ?
4) Why do my popups sort wrong (or not appear in search results)?
5) What are ~TEMPLATE~ and ~FIELD~?
6) Why is it possible to change ~TEMPLATE~ and ~FIELD~?
7) Why can't I can't paste some cards into my deck of cards?
8) What do I do with cards_dump_sys.pl?


-------


1) What do: Add New Card, Deck of Cards, Card Definition do?

i) Add New Card: lets user add a new Card (like Add New Item) accoring to the FORM of his choice.

ii) Add New Deck of Cards: a place to group cards together (a bit like Add New Table, from which it derived).

iii) Add New Form: 
- You probably should not expect general user to understand this.
- Creating a new FORM is like creating a new kind of Item.  Not a new Item.  A whole new kind of Item.  
- After you create a FORM, its name will appear in the list when you select Add New Card.
- To help you not get confused Between Add New FORM and Add New Card the FORM's table appears in shades of YELLOW.


-------


3) How do I do money   $9,123.05  ?

If you want to only allow numbers with exactly 2 digits after the decimal
- start with a varchar or text field (yes that is odd)
- put  "^\d*\.\d{2}$"  in the verify field (without the quotes)

If you also want an optional minus sign, and to allow people to skip the "cents" use this:

^-?\d*(\.\d{2})?$


If you've never seen "regular expressions" before then this must seem very cryptic. You are right.  On unix "man regexp" may help.  There is lots of documentation about regular expressions the web.  You should also note that metadot-forms uses Perl regular expressions, which offer more than unix and 'C' regular expressions, but are close enough that unix or 'C' examples will get you started.


-------


2) If I set a field minimum to 10, why can some save nothing?

What you want is to set the field to manditory.

Think of "fax number".  If someone has one, it should probably be atleast 7 digits, ...but only if they have a fax.




-------


4) Why do my popups sort wrong (or not appear in search results)?

It depends how you setup the popup.  

If you setup the popup so what appears on the screen is the same as what is stored, then they will sort and search that way.

If however you setup "no problem/minor issue/big issue/crisis" to store as 1/2/5/10, then that is how it will sort.  FORMS always sorts and search based on the stored value , not the screen value.

As you can see this can be useful (an alpha sort of "no problem/minor issue/big issue/crisis" is not what you want).


-------


5) What are ~TEMPLATE~ and ~FIELD~?

You must first know that many screens in this package are written in the package itself, therefore use FORM.

i) ~TEMPLATE~ provides the list of available fields when, in FORM you select "Add a new ~FIELD~".  (Your new field is copied from ~TEMPALTE~).
- It's backround is shades of ORANGE to warn you to think twice before editting it.
- A particularly dangerous things to do is to change the "Max Privileges" for an item that is initially "Read Only".  It is probably "Read Only" because it is used by the system internally.


ii) ~FIELD~ defines the screen you see when editting a field of a FORM.
- There is little point in changing this because the code behind it will not understand your changes.
- It's backround is shades of RED to suugest you STOP if you are thinking of editting it.


------


6) Why is it possible to change ~TEMPLATE~ and ~FIELD~?

Ever have an applicance that has "No User Serviceable Parts" written on the outside, when on the inside is is an easy to replaced fuse?

It is your computer, and your decision.

There are reasons to change ~TEMPLATE~, especially now because it isn't setup very well.  There are even reason to edit ~FIELD~ (especially if English isn't your preferred language).  Just be careful, and don't call us if you break it.


------


7) Why can't I can't paste some cards into my deck of cards?

You can cut and paste card between decks (or as standalone cards)... but the card must use the same FORM.

If Bob's Creatures and Sally's Creatures are both decks based on the same FORM then you can cut and paste between them.  However if Bob's Creatures, and Bob CDs are decks based on different forms then you can't cut and paste between them (despite all the 1960's bands named after some creature of other).


------

8) What do I do with form_dump_sys.pl?

Probably nothing.

form_dump_sys.pl creates the file that form_import_sys.pl reads.
If importing didn't work for you, it helps to be able to look at the exporting code.

Besides, this way we don't accidently misplace it.