head	1.7;
access;
symbols;
locks
	nobody:1.7; strict;
comment	@# @;


1.7
date	2001.09.07.12.43.03;	author MikeMannix;	state Exp;
branches;
next	1.6;

1.6
date	2001.09.07.10.09.54;	author MikeMannix;	state Exp;
branches;
next	1.5;

1.5
date	2001.08.31.23.10.48;	author MikeMannix;	state Exp;
branches;
next	1.4;

1.4
date	2001.08.30.19.55.36;	author MikeMannix;	state Exp;
branches;
next	1.3;

1.3
date	2001.08.30.16.13.36;	author MikeMannix;	state Exp;
branches;
next	1.2;

1.2
date	2001.08.29.16.14.11;	author JohnTalintyre;	state Exp;
branches;
next	1.1;

1.1
date	2001.08.16.17.09.21;	author JohnTalintyre;	state Exp;
branches;
next	;


desc
@none
@


1.7
log
@none
@
text
@%META:TOPICINFO{author="MikeMannix" date="999866583" format="1.0" version="1.7"}%
%META:TOPICPARENT{name="WebHome"}%
---++++ Merged into TWikiMetaData - this topic to be rolled back.
@


1.6
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="MikeMannix" date="999857394" format="1.0" version="1.6"}%
d3 1
a3 155
%TOC%
%STARTINCLUDE%
#MetaDataDefinition
---# TWiki Meta Data

---++ What is Meta Data in TWiki?

__What, indeed!__

---+++ Defining Meta Data Variables

See [[#MetaDataRendering][Meta Data Rendering]] for variables used to display meta data.

Current version: *1.0*

---+++ Syntax

	* Format is as for [[TWikiDocumentation#TWiki_Variables, except all fields have a key.
		* %<nop>META:&lt;type&gt;{key1="value1" [key2="value2" [...]]}%
	* Order of fields within the meta variables is not defined, except that if there is a field with key =name=, this appears first for easier searching (note the order of the variables themselves is defined)
	* Each meta variable is on one line
	* '\n' is represented in values by ==%<nop>_<nop>N_<nop>== and '"' by ==%<nop>_Q_%==

<blockquote style="background-color:#f0f0f0">
*Example of Format*
<verbatim>
%<nop>META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
	text of the topic
%<nop>META:TOPICMOVED{from="Codev.OldName" to="CoDev.NewName"
	by="JohnTalintyre" date="976762680"}%
%<nop>META:TOPICPARENT{name="NavigationByTopicContext"}%
%<nop>META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
%<nop>META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
%<nop>META:FORM{name="WebFormTemplate"}%
%<nop>META:FIELD{name="OperatingSystem" value="OsWin"}%
%<nop>META:FIELD{name="TopicClassification" value="PublicFAQ"}%
</verbatim>
</blockquote>

---+++ Specifications

---++++ TOPICINFO

	|  *Key*  |  *Comment*			 |
	| version	| Same as RCS version |
	| date		| integer, unx time, seconds since start 1970 |
	| author	 | last to change topic, is the REMOTE_USER |
	| format	 | Format of this topic, will be used for automatic format conversion |

---++++ TOPICMOVED

This is optional, exists if topic has ever been moved.  If a topic is moved more than once, only the most recent TOPICMOVED meta variable exists in the topic, older ones are to be found in the rcs history.

%<nop>META:TOPICMOVED{from="Codev.OldName" to="CoDev.NewName" by="talintj" date="976762680"}%

	|  *Key*  |  *Comment*			 |
	| from		| Full name i.e. web.topic |
	| to		  | Full name i.e. web.topic |
	| by		  | Who did it, is the REMOTE_USER, not <nop>WikiName |
	| date		| integer, unx time, seconds since start 1970 |

Notes: 
	* at present version number is not supported directly, it can be inferred from the RCS history.
	* there is only one META:TOPICMOVED in a topic, older move information can be found in the RCS history.
 
---++++ TOPICPARENT

	| *Key*	| *Comment* |
	| name	 | The topic from which this was created, WebHome if done from =Go=, othewise topic where =?= or form used.  Normally just topic, but is full web.topic format if parent is in a different Web.  Renaming a Web will then only break a few of these references or they can be scanned and fixed. |

---++++ FILEATTACHMENT

	| *Key*	| *Comment* |
	| name	 | Name of file, no path.  Must be unique within topic |
	| version | Same as RCS revision  |
	| path	 | Full path file was loaded from |
	| size	 | In bytes |
	| date	 | integer, unx time, seconds since start 1970 |
	| user	 | the REMOTE_USER, not <nop>WikiName |
	| comment | As supplied when file uploaded |
	| attr	 | =h= if hidden, optional |

Extra field that are added if an attachment is moved:

	| movedfrom | full topic name - web.topic |
	| movedby	| the REMOTE_USER, not <nop>WikiName |
	| movedto	| full topic name - web.topic |
	| moveddate | integer, unx time, seconds since start 1970 |

---++++ FORM

	| *Key*	| *Comment* |
	| name	 | A topic name - the topic is a [[TWikiDocumentation#Form_Template][Form Template]].  Can optionally include the web name i.e. web.topic, but doesn't normally |

---++++ FIELD

Should only be present if there is a FORM entry.  Note that this data is used when viewing a topic, the form template definition is not read.

	| *Key*	| *Name*	|
	| name	 | Ties to entry in [[TWikiDocumentation#Form_Template][Form Template]], is title with all bar alphanumerics and . removed |
	| title	| Full text from [[TWikiDocumentation#Form_Template][Form Template]] |
	| value	| Value user has supplied via form |

---+++ Recommended Sequence

There no absolute need for meta data variables to be in a specific order, however, it does for the following reasons:
	* Keep (form) fields in the order they are defined
	* Allow diff command to give output in a logically sensible order

These could be done in other ways, but this adds complexity
	* Order fields - definition could be read on each rendering (expensive)
	* Diff - render data before doing diff, has something to offer, but not likely to be available for next TWiki release

So the order is:
	* TOPICINFO
	* text of topic
	* TOPICMOVED - optional
	* TOPICPARENT - optional
	* FILEATTACHMENT - 0 or more entries
	* FORM - optional
	* FIELD - 0 or more entries (FORM required)

---+++ Viewing Meta Data in Page Source

When viewing a topic the ==Raw Text== link can be clicked to show the text of a topic (ie: as seen when editing).  This is done by adding <code>raw=on</code> to URL.  <code>raw=debug</code> shows the meta data as well as the topic data, ex: <a href="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%?raw=debug">debug view for this topic</a>

---+++ Future Support for Plugins 

There is currently no support for meta data for Plugins.  However, the format is readily extendable and the =Meta.pm= code that supports the format needs only minor alteration.

#MetaDataRendering
---++ Rendering Meta Data

Various types of meta data can be [[#MetaDataDefinition][stored in topics]]. The data is rendered using the %<nop>META% variable. This is mostly used in the ==view==, ==preview== and ==edit== scripts.

Current support is fairly basic:

  | *Variable usage:*	| *Comment:*  |
  | %<nop>META{"form"}% | Show form data, see [[TWikiDocumentation#Form_Templates][Form Templates]] |
  | %<nop>META{"attachments"}% | Show attachments, exclude hidden |
  | options for attachments: |
  | all="on" | Show ALL attachments (including hidden) |
  | %<nop>META{"moved"}% | Details of any topic moves |
  | %<nop>META{"parent [options]"}% | Show topic parent |
  | options for parent: |
  | dontrecurse="on" | By default recurses up tree, at some cost |
  | prefix="..." | Prefix for parents, only if there are parents; default "" |
  | suffix="..." | Suffix, only appears if there are parents; default "" |
  | seperator="..." | Separator between parents, default is " > " |

	* *Future Development:* There are numerous development directions and specific features to consider. A couple of obvious possibilities:	
		* Rendering to formats other than tables: bullet lists, formatted body text; 
		* Specifying templates to be used for rendering.

-- JohnTalintyre - 29 Aug 2001 <br />
@


1.5
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="MikeMannix" date="999300220" format="1.0" version="1.5"}%
d6 1
a6 1
---## TWiki Meta Data
d8 1
a8 1
---+++ What is Meta Data in TWiki?
d18 1
a18 1
---++++ Syntax
d42 1
a42 1
---++++ Specifications
d44 1
a44 1
---+++++ TOPICINFO
d52 1
a52 1
---+++++ TOPICMOVED
d68 1
a68 1
---+++++ TOPICPARENT
d73 1
a73 1
---+++++ FILEATTACHMENT
d92 1
a92 1
---+++++ FORM
d97 1
a97 1
---+++++ FIELD
d106 1
a106 1
---++++ Recommended Sequence
d125 1
a125 1
---++++ Viewing Meta Data in Page Source
d129 1
a129 1
---++++ Future Support for Plugins 
d134 1
a134 1
---+++ Rendering Meta Data
@


1.4
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="MikeMannix" date="999201406" format="1.0" version="1.4"}%
d8 5
a12 1
---+++ Meta Data Definition
d18 1
a18 1
---++++ Example of format
d20 8
d31 2
a32 1
%<nop>META:TOPICMOVED{from="Codev.OldName" to="CoDev.NewName" by="JohnTalintyre" date="976762680"}%
d40 1
d42 1
a42 28
---++++ General notes

	* Format is as for [[TWikiDocumentation#TWiki_Variables, except all fields have a key.
		* %<nop>META:&lt;type&gt;{key1="value1" [key2="value2" [...]]}%
	* Order of fields within the meta variables is not defined, except that if there is a field with key =name=, this appears first for easier searching (note the order of the variables themselves is defined)
	* Each meta variable is on one line
	* '\n' is represented in values by ==%<nop>_<nop>N_<nop>== and '"' by ==%<nop>_Q_%==

---++++ Logical order

There no absolute need for meta data to be in a specific order, however, it does for the following reasons:
	* Keep (form) fields in the order they are defined
	* Allow diff command to give output in a logically sensible order

These could be done in other ways, but this adds complexity
	* Order fields - definition could be read on each rendering (expensive)
	* Diff - render data before doing diff, has something to offer, but not likely to be available for next TWiki release

So the order is:
	* TOPICINFO
	* text of topic
	* TOPICMOVED - optional
	* TOPICPARENT - optional
	* FILEATTACHMENT - 0 or more entries
	* FORM - optional
	* FIELD - 0 or more entries (FORM required)

---++++ Specification
d106 20
a125 1
---++++ Viewing meta data
d129 1
a129 1
---++++ Future Plugins support
d134 1
a134 1
---+++ Meta Data Rendering
d136 1
a136 1
Various meta data can be [[#MetaDataDefinition][stored in topics]]. The data is rendered using the %<nop>META% variable. This is mostly used in the =view=, =preview= and =edit= scripts.
d153 3
a155 3
	* *Possible future additions:*
		* Rendering of form data to alternate formats, ex: bullet lists
		* Specify a template to be used for rendering
@


1.3
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="MikeMannix" date="999188016" format="1.0" version="1.3"}%
d5 2
a6 1
---## Meta Data Definition
d8 3
a10 1
See [[TWikiDocumentation#Meta_Data_Rendering][Meta Data Rendering]] for variables used to display meta data.
d14 1
a14 1
---+++ Example of format
d28 1
a28 1
---+++ General notes
d36 1
a36 1
---+++ Logical order
d55 1
a55 1
---+++ Specification
d57 1
a57 1
---++++ TOPICINFO
d65 1
a65 1
---++++ TOPICMOVED
d81 1
a81 1
---++++ TOPICPARENT
d86 1
a86 1
---++++ FILEATTACHMENT
d105 1
a105 1
---++++ FORM
d110 1
a110 1
---++++ FIELD
d119 10
a128 1
---+++ Viewing meta data
d130 1
a130 1
When viewing a topic the =Raw Text= link can be clicked to show the text of a topic (i.e. as is seen when editing).  This is done by adding <code>raw=on</code> to URL.  <code>raw=debug</code> shows the meta data as well as the topic data e.g. <a href="%SCRIPTURLPATH%/view%SCRIPTSUFFIX%/%WEB%/%TOPIC%?raw=debug">for this topic</a>
d132 1
a132 1
---+++ Other
d134 12
a145 1
There is currently no support for meta data for Plugins.  However, the format is readily extendable and the =Meta.pm= code that supports the format only needs minor alteration.
d147 3
a149 1
%INCLUDE{"%TWIKIWEB%.MetaDataRendering"}%
d151 1
a151 1
-- JohnTalintyre - 16 Aug 2001 <br>
@


1.2
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="JohnTalintyre" date="999103330" format="1.0" version="1.2"}%
d123 2
@


1.1
log
@none
@
text
@d1 1
a1 1
%META:TOPICINFO{author="JohnTalintyre" date="997982189" format="1.0beta2" version="1.1"}%
d3 2
d7 1
a7 1
See MetaDataRendering for display of meta data
a10 3
Table of contents:
%TOC%

d13 1
a13 1
<pre>
d23 1
a23 1
</pre>
d27 1
a27 1
	* Format is as for %TWIKIWEB%.TWikiVariables, except all fields have a key.
d105 1
a105 1
	| name	 | A topic name - the topic is a TWikiFormTemplate.  Can optionally include the web name i.e. web.topic, but doesn't normally |
d112 2
a113 2
	| name	 | Ties to entry in TWikiFormTemplate, is title with all bar alphanumerics and . removed |
	| title	| Full text from TWikiFormTemplate |
d124 1
a124 1
-- Main.JohnTalintyre - 16 Aug 2001 <br>
@
