part of the ArsDigita Community System
by Philip Greenspun
this module is maintained separately from the rest of OpenACS by James Shannon. Go there for more help and bugs and features and whatnot.
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.
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.
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 reiterate_through_chunk function returns straight html similar to what has been passed in.
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.
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.
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.
The most efficient and easy to use function to print formatted content onto a page is reiterate_through_chunk.
reiterate_through_chunk {db_handle, which_chunk, template} -
Synopsis: returns a templatized and formatted html string for each item gathered by a chunk function
Configuration: there is no configuration for reiterate_through_chunk
Arguments:
db_handle - a valid database handle
which_chunk - 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.
news :: uses the most_recent_news function; sets the variables: news_item_id, title, release_date, body, news_link, and pretty_release_date
threads :: uses the most_active_threads function; sets the variables: msg_id, count, topic, one_line, body, and msg_link
calendar :: uses the current_calendar_events function; sets the variables: calendar_id, category, title, body, start_date, end_date, calendar_link, pretty_start_date, pretty_end_date
classifieds :: uses the most_recent_classifieds function; sets the variables: classified_ad_id, domain, one_line, posted, manufacturer, classified_ad_link, pretty_posted
active_auctions :: uses the most_active_classified_auctions function; sets the variables: classified_ad_id, domain, one_line, posted, manufacturer, count, classified_ad_link, pretty_posted
template - 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 template
Returns: a string formatted as specified in the template argument(see arguments)
Example: try calling [reiterate_through_chunk $db news "<a href=\"\$news_link\">\$title</a> (\$pretty_release_date) - \$title<br>"]
Alternatively, you can use the more detailed functions and then reiterate through the output lists yourself with a for loop.
most_recent_news {db_handle} -
Synopsis: gathers pertinent information about the most recent and active news articles
Configuration:located in the ad.ini file under [ns/server/servername/acs/chunks]
NewsCacheLength - amount of time(in seconds) to hold the gathered information for before hitting SQL again
MaxNews - the maximum number of articles to retrieve
MaxNewsBodyLength - the approximate length that the body will be truncated to(it is actually the first space after the given number).
Returns:One list containing a variable number of sublists. The sub lists are structured as follows:
sublist[0] - news_item_id :: most useful for linking to the item.tcl page
sublist[1] - title :: the title of the news item
sublist[2] - release_date :: the SQL represenation of when the article is to be released
sublist[3] - body :: the first x characters(see configuration) of the body of the news article
sublist[4] - html_p :: whether or not the article was entered in html format
most_active_threads {db_handle} -
Synopsis: Determines and returns the most recently active threads by counting the number of posts in the last x days
Configuration:located in the ad.ini file under [ns/server/servername/acs/chunks]
BboardCacheLength - amount of time(in seconds) to hold the gathered information for before hitting SQL again
MaxBboardThreads - the maximum number of threads to
retrieve
MaxMsgBodyLength - the approximate length that the body will be truncated to(it is actually the first space after the given number).
CountOldMessages - the number of days back to
take individual messages into consideration (the age of the thread itself does
not matter)
Returns:One list containing a variable number of sublists. The sub lists are structured as follow
s:
sublist[0] - root_msg_id :: the original message in the thread; most useful for linking to the *fetch.tcl page
sublist[1] - count :: the number of recently posted messages in that thread
sublist[2] - topic :: the name of the topic that this thread is in
sublist[3] -
one_line :: the subject of the original message in the thread
sublist[4] -
body
:: the first x characters(see configuration) of the body of the root message
current_calendar_events {db_handle} -
Synopsis: gathers pertinent information about the most current events on the calendar(events that have not ended yet)
Configuration:located in the ad.ini file under [ns/server/servername/acs/chunks
EventsCacheLength - amount of time(in seconds) to hold the gathered information for before hitting SQL again
MaxEvents - the maximum number of events to retrieve
MaxEventBodyLength - the approximate length that the body will be truncated to(it is actually the first space after the given number).
Returns:One list containing a variable number of sublists. The sub lists are structured as follow
s:
sublist[0] - calendar_id :: most useful for linking to the item.tcl page
sublist[1] - category :: the category name that this event has been placed in
sublist[2] - title :: the title of the calendar item
sublist[3] - body :: the first x characters(see configuration) of the body of the calendar item
sublist[4] - html_p :: whether or not the body is in html format
sublist[5] - start_date :: the SQL representation of when this event will/did start
sublist[6] - end_date
:: the SQL representation of when this even will end
most_recent_classifieds {db_handle} -
Synopsis: gathers pertinent information about the most recently posted classified ads
Configuration:located in the ad.ini file under [ns/server/servername/acs/chunks
ClassifiedsCacheLength - amount of time(in seconds) to hold the gathered information for before hitting SQL again
MaxAds - the maximum number of classified ads to retrieve
Returns:One list containing a variable number of sublists. The sub lists are structured as follow
s:
sublist[0] - classified_ad_id :: most useful for linking to
the view-one.tcl page
sublist[1] - domain
:: the category that the ad has been placed in
sublist[2] - one_line :: the 'subject'
line of the ad
sublist[3] - posted :: the SQL representation of when this ad
was posted
sublist[4] - manufacturer :: the software stores a textual
representation of the price in manufacturer
most_active_classified_auctions {db_handle} -
Synopsis: Determines and returns the most recently active auctions(determined by number of bids in last x days)
Configuration: located in the ad.ini file under [ns/server/servername/acs/chunks]
AuctionsCacheLength - amount of time(in seconds) to hold the gathered information for before hitting SQL again
MaxAuctions - the maximum number of ads to retrieve
CountOldBids - the number of days back to take bids into consideration
Returns:One list containing a variable number of sublists. The sub lists are structured as follow
s:
sublist[0] - classified_ad_id :: most useful for linking to the view-one.tcl page
sublist[1] - domain :: the category that the ad has been placed in
sublist[2] - one_line :: the 'subject' line of the ad
sublist[3] - posted :: the SQL representation of when this as was posted
sublist[4] - manufacturer :: the software stores a textual representation of the price in manufacturer
sublist[5] - count :: the number of recent bids on this particular ad
A demonstration of the functions at work can be found in the admin directory.