<wmmeta name="Title" value="The &lt;content&gt; Tag" />
<wmmeta name="Section" value="02-tags_attrs" />
<wmmeta name="Score" value="30" />
<wmmeta name="Abstract">
one chunk of textual content
</wmmeta>

The &lt;content&gt; tag, along with the other similar content-defining tags
like &lt;contents&gt;, &lt;template&gt; etc., is used as one of the basic
building blocks of a WebMake file.

Essentially, you use it to wrap input, and give them a name, so that you can
refer to them later in &lt;out&gt; blocks or other content items.

This tag has one required attribute: its name, which is used to substitute in
that section's text, by inserting it in other sections or out tags in a
"curly-bracket reference" [content_refs], like so:

	&wmdollar;{foo}

If you wish to define a number of content sections at once, they can be
searched for and loaded en masse using the "&lt;contents&gt;" [1] tag.

Every content item can have "metadata" associated with it.  See the
"metadata documentation" [metadata] for details.

The following attributes are supported.  These can also be set using the
"&lt;attrdefault&gt;" [attrdefault] tag.

	__format__:	This allows the user to define what format the content
	is in.  This allows markup languages other than HTML to be used;
	webmake will convert to HTML format, or other output formats, as
	required using the HTML::WebMake::FormatConvert module.  The default
	value is ''__text/html__''.  

	__asis__:	This will block any interpretation of content or URL
	references in the content item, until after it has been converted into
	HTML format.  This is useful for POD documentation, which may be
	embedded inside a file containing other text; without ''asis'', the
	text would be scanned for content references before the POD converter
	stripped out the extraneous bits.  The default value is ''__false__''.

	__map__:	Whether the content item should be mapped in a "site
	map" [sitemap], or not. The default value is ''__true__''.

	__up__:	The name of the content item which is this content item's
	parent, in the "site map" [sitemap].

	__preproc__:	Pre-process content items using a Perl function.

	__isroot__:	Whether or not this content item is the root of the
	"site map" [sitemap]. The default value is ''__false__''.  (This
	cannot be used as a parameter to a tag that loads multiple content
	items, like the &lt;contents&gt; tag.)

	__src__:	Allows the text of the content item to be loaded from
	a given URL (remote content) or file in the filesystem. (Again,
	this is not usable from a tag that loads multiple items.)

	__updatefreq__:	How long a remote content item should be cached.
	(Again, this is not usable from a tag that loads multiple items.)

Using Remote Content
--------------------

Content items can be loaded remotely, ie. via HTTP or FTP, by using a URL in
the __src__ attribute.  These will be cached for as long as the update
frequency __updatefreq__ dictates, by default 1 hour.  The update frequency is
a string in this format:

	##&etsqi;n days&etsqo; &etsqi;n hours&etsqo; &etsqi;n mins&etsqo; &etsqi;n secs&etsqo;##

So, for, example, ##1 hour 20 seconds## converts to 3620 seconds.

Pre-Processing
--------------

Using the __preproc__ attribute, you can specify a block of perl code
to execute over each content item's text.  The content item's text is
provided in the ##&wmdollar;_## variable.  (Since the XML attribute
format doesn't provide much room for perl code, your best bet is to
call a function to do the work.)

This can be very handy.  Here's some suggested uses:

    - multiple templates can be loaded from one HTML file; for example, if
      your designer has created a template for a ''list page'', with HTML for
      the page layout, a table, odd list lines, and even list lines, you can
      use just one template file as a __src__, and define multiple content
      items from it using different __preproc__ functions and the
      ##scrape_xml()## Perl code library function.  The <a
      href=$(scraping)>Scraped Templates</a> page goes into more detail
      on how to use this.

    - If you combine this with an agreed format for ''filler'' text or
      variable references, then you can replace filler with valid content
      references on-the-fly, and avoid having to persuade the designer to
      understand how content refs work.   For example, your designer
      could use the __lorem ipsum__ text to indicate ''main body text'';
      using a sub like this

<safe>
		s/lorem\s+ipsum[^<]+/\${main_body}/gs;
</safe>

      you can convert that text into a reference to a content item
      called **main_body**.

    - you can convert raw formats to more friendly-looking presentation on the
      fly; for example, my blog at <a href="http://taint.org/">taint.org</a>
      (<a href=http://taint.org/main.wmk/>view source</a>) is updated through
      email, and those mails are stored as raw mails to the filesystem.
      WebMake converts them to HTML using EtText and a short __preproc__
      function which strips out email addresses for spam protection.  (See
      example below)

    - sections of text can be loaded from third-party websites or files,
      regardless of the markup surrounding it.  By using a perl sub like 

<safe>
		s/^.*?<!-- start of text table -->//gs;
		s/<!-- end of text table -->.*?$//gs;
</safe>

      you can strip off the unwanted parts of the file; in other words,
      HTML screen scraping.  Again, the ##scrape_xml()## 
      Perl code library function is handy here.

Defining Content Items On-The-Fly
---------------------------------

The "&lt;{set}&gt; processing instruction" [3] can be used to define small
pieces of content on the fly, from within other content or "&lt;out&gt;
sections" [4].

In addition, Perl code can create content items using the "set_content()" [2]
function.

Using Content From Perl Code
----------------------------

Perl code can obtain the text of content items using the "get_content()" [2]
function, and can treat content items as whitespace-separated lists using
"get_list()" [2].

In addition, each content item has a range of properties and associated
"metadata"; the "get_content_object()" [2] method allows Perl code to retrieve
an object of type "HTML::WebMake::Content" [contobj] representing the content
item.

	[1]: $(contents)
	[2]: $(PerlCodeLibrary.pm.html)
	[3]: $(set)
	[4]: $(out)
	Auto: [content_refs]: $(content_refs)
	[contobj]: $(Content.pm.html)
	Auto: [metadata]: $(metadata)
	Auto: [sitemap]: $(sitemap)
	Auto: [metadefault]: $(metadefault)
	[attrdefault]: $(attrdefault)

Example
=======

<safe>
  <content name="foo" format="text/html">
  <em>This is a test.</em>
  </content>

  <content name="bar" format="text/et">
  Still Testing
  -------------

  So is this!
  </content>

  <content name="remote" format="image/png"
	  src="http://webmake.taint.org/BuiltWithWebMakeBigger.png">
  </content>

  <{perl sub mail_fmt {
      local ($_) = shift;
      s/\S+\@\S+/\(spam-protected\)/gs;		# remove email addrs
      $_;
    }
  ''; }>
  <contents src="raw" format="text/et"
	   name=".../*.mail" preproc="mail_fmt($_)" />

</safe>
