<html>
<!--AD_DND-->
<head>
<title>The Chunks Module</title>
</head>
<body bgcolor=#ffffff text=#000000>
<h2>Chunks</h2>
<P>
part of the <A href="/doc/index.html">ArsDigita Community System</A>
by <a href="http://photo.net/philg/">Philip Greenspun</a><BR>
<br>
this module is maintained separately from the rest of OpenACS by <a href="http://www.jamesshannon.com">James Shannon</a>. Go there for more help and bugs and features and whatnot. </P>
<hr>
<ul>
<li>User-accessible directory: none
<li>Administrator directory: <A href="/admin/chunks/">/admin/chunks/</A>
<li>data model : none
<li>Tcl procs: /tcl/chunks.tcl</li>
</ul>
<h3>What's the dilly, yo?</h3>
<p>
Often times, an organization will want to display dynamic information on the home page or section landing pages. This dynamic information needs to be abbreviated into a chunk of information to fit into specific space-confined sections of the page. Chunks will do that.
<h3>Say what?</h3>
<p>
Chunks is a fairly simple 'module' of sorts that offers functions that one can call to obtain a list of relatively up to date and concise information perfect for working into a section of another page. A function is also offered that allows for reiterative templating of specific chunks of html.
<p>
Since many of these pieces of information are actually collections of other pieces of information(date, title, etc), the functions return a list of lists. The main list holds a predetermined number of sublists, each holding the required information. Alternatively, the <b>reiterate_through_chunk</b> function returns straight html similar to what has been passed in.
<p>
Memoize is used to substantially reduce the load placed upon the servers generated by the exact same SQL call every time a page is hit. As such, some information could be up to 2 hours(the default) old. This time limit can be changed and the admin pages offer a way to refresh the cached data.
<p>
<h3>Up close and personal</h3>
<p>
Chunks does not use any of it's own SQL tables as all information that it uses is grabbed from tables owned by other modules.
<p>
When one of the functions is called, it uses memoize to store or retrieve the results (depending on how recent the cached information is) of an internal function that is responsible for generating the actual data.
<h3>Using Chunks</h3>
A variety of functions are offered depending on exactly which module's information is desired.
<p>
The most efficient and easy to use function to print formatted content onto a page is <b>reiterate_through_chunk</b>.
<p>
<b>reiterate_through_chunk</b> <i>{db_handle, which_chunk, template}</i> -<br>
Synopsis: returns a templatized and formatted html string for each item gathered by a chunk function<br><br>
<font size="-1">Configuration: <i>there is no configuration for <b>reiterate_through_chunk</b></i></font><br>
<font size="-1">Arguments: <br>
<u>db_handle</u> - a valid database handle<br>
<u>which_chunk</u> - a single word specifying which set of data from which module should be used. the choice here will make a difference in which variables are available in the template.<br>
<i>news</i> :: uses the <b>most_recent_news</b> function; sets the variables: news_item_id, title, release_date, body, news_link, and pretty_release_date <br>
<i>threads</i> :: uses the <b>most_active_threads</b> function; sets the variables: msg_id, count, topic, one_line, body, and msg_link <br>
<i>calendar</i> :: uses the <b>current_calendar_events</b> function; sets the variables: calendar_id, category, title, body, start_date, end_date, calendar_link, pretty_start_date, pretty_end_date<br>
<i>classifieds</i> :: uses the <b>most_recent_classifieds</b> function; sets the variables: classified_ad_id, domain, one_line, posted, manufacturer, classified_ad_link, pretty_posted<br>
<i>active_auctions</i> :: uses the <b>most_active_classified_auctions</b> function; sets the variables: classified_ad_id, domain, one_line, posted, manufacturer, count, classified_ad_link, pretty_posted<br>
<u>template</u> - the text that will be repeated for each individual item and parsed for the above available variables. Keep in mind to escape quotes and dollar signs passed into <u>template</u><br>
</font>
<br>
<font size="-1">Returns: <i>a string formatted as specified in the template argument(see arguments)</i><br>
</font>
<br>
<font size="-1">Example: try calling [reiterate_through_chunk $db news "<a href=\"\$news_link\">\$title</a> (\$pretty_release_date) - \$title<br>"]<br>
</font>
<br>
<br>
Alternatively, you can use the more detailed functions and then reiterate through the output lists yourself with a for loop.<br><br><br>
<b>most_recent_news</b> <i>{db_handle}</i> -<br>
Synopsis: gathers pertinent information about the most recent and active news articles<br><br>
<font size="-1">Configuration:<i>located in the ad.ini file under [ns/server/servername/acs/chunks]</i><br>
NewsCacheLength - amount of time(in seconds) to hold the gathered information for before hitting SQL again<br>
MaxNews - the maximum number of articles to retrieve<br>
MaxNewsBodyLength - the approximate length that the body will be truncated to(it is actually the first space after the given number).</font><br><br>
<font size="-1">Returns:<i>One list containing a variable number of sublists. The sub lists are structured as follows:</i><br>
sublist[0] - news_item_id :: most useful for linking to the item.tcl page<br>
sublist[1] - title :: the title of the news item<br>
sublist[2] - release_date :: the SQL represenation of when the article is to be released<br>
sublist[3] - body :: the first x characters(see configuration) of the body of the news article<br>
sublist[4] - html_p :: whether or not the article was entered in html format<br>
</font>
<br>
<P>
<b>most_active_threads</b> <i>{db_handle}</i> -<br>
Synopsis: Determines and returns the most recently active threads by counting the number of posts in the last x days<br><br>
<font size="-1">Configuration:<i>located in the ad.ini file under [ns/server/servername/acs/chunks]</i><br>
BboardCacheLength - amount of time(in seconds) to hold the gathered information for before hitting SQL again<br>
MaxBboardThreads - the maximum number of threads to
retrieve<BR>
MaxMsgBodyLength - the approximate length that the body will be truncated to(it is actually the first space after the given number).</font><FONT
size=-1>
<br>
CountOldMessages - the number of days back to
take individual messages into consideration (the age of the thread itself does
not matter)</FONT><br><br>
<font size="-1">Returns:<i>One list containing a variable number of sublists. The sub lists are structured as follow
s:</i><br>
sublist[0] - root_msg_id :: the original message in the thread; most useful for linking to the *fetch.tcl page<br>
sublist[1] - count :: the number of recently posted messages in that thread<br>
sublist[2] - topic :: the name of the topic that this thread is in<br>
sublist[3] -
one_line :: the subject of the original message in the thread<BR>sublist[4] -
body
:: the first x characters(see configuration) of the body of the root message
</font>
<br></P>
<P>
<b>current_calendar_events</b> <i>{db_handle}</i> -<br>
Synopsis: gathers pertinent information about the most current events on the calendar(events that have not ended yet)<br><br>
<font size="-1">Configuration:<i>located in the ad.ini file under [ns/server/servername/acs/chunks</i><br>
EventsCacheLength - amount of time(in seconds) to hold the gathered information for before hitting SQL again<br>
MaxEvents - the maximum number of events to retrieve<br>
MaxEventBodyLength - the approximate length that the body will be truncated to(it is actually the first space after the given number).</font><br><br>
<font size="-1">Returns:<i>One list containing a variable number of sublists. The sub lists are structured as follow
s:</i><br>
sublist[0] - calendar_id :: most useful for linking to the item.tcl page<br>
sublist[1] - category :: the category name that this event has been placed in<br>
sublist[2] - title :: the title of the calendar item<br>
sublist[3] - body :: the first x characters(see configuration) of the body of the calendar item<br>
sublist[4] - html_p :: whether or not the body is in html format<br>
sublist[5] - start_date :: the SQL representation of when this event will/did start<br>
sublist[6] - end_date
:: the SQL representation of when this even will end
</font>
<br>
<b>most_recent_classifieds </b><i>{db_handle}</i> -<br>
Synopsis: gathers pertinent information about the most recently posted classified ads<BR><br>
<font size="-1">Configuration:<i>located in the ad.ini file under [ns/server/servername/acs/chunks</i><br>
ClassifiedsCacheLength - amount of time(in seconds) to hold the gathered information for before hitting SQL again<br>
MaxAds - the maximum number of classified ads to retrieve</font><br><br>
<font size="-1">Returns:<i>One list containing a variable number of sublists. The sub lists are structured as follow
s:</i><br>
sublist[0] - classified_ad_id :: most useful for linking to
the view-one.tcl page<BR>
sublist[1] - domain
:: the category that the ad has been placed in
<BR>sublist[2] - one_line :: the 'subject'
line of the ad<BR>sublist[3] - posted :: the SQL representation of when this ad
was posted<BR>sublist[4] - manufacturer :: the software stores a textual
representation of the price in manufacturer</FONT>
<p>
<br>
<b>most_active_classified_auctions</b> <i>{db_handle}</i> -<br>
Synopsis: Determines and returns the most recently active auctions(determined by number of bids in last x days)<br>
<font size="-1">Configuration: <i>located in the ad.ini file under [ns/server/servername/acs/chunks]</i><br>
AuctionsCacheLength - amount of time(in seconds) to hold the gathered information for before hitting SQL again<br>
MaxAuctions - the maximum number of ads to retrieve<br>
CountOldBids - the number of days back to take bids into consideration</font>
<br><br>
<font size="-1">Returns:<i>One list containing a variable number of sublists. The sub lists are structured as follow
s:</i><br>
sublist[0] - classified_ad_id :: most useful for linking to the view-one.tcl page<br>
sublist[1] - domain :: the category that the ad has been placed in<br>
sublist[2] - one_line :: the 'subject' line of the ad<br>
sublist[3] - posted :: the SQL representation of when this as was posted<br>
sublist[4] - manufacturer :: the software stores a textual representation of the price in manufacturer<br>
sublist[5] - count :: the number of recent bids on this particular ad
</font>
<br>
<br>
<p>
A demonstration of the functions at work can be found in the <A href="/admin/chunks/">admin</A> directory.
<hr>
<address><A href="mailto:james@jamesshannon.com">james@jshannon.com</A></address>
</body>
</html>