Created by Karen Atherholt

The Greens template being used here was created by Karen Atherholt.

This page is being used to demonstrate the DateTimePlus, GetAuthorData, and ListDocuments snippets as well as documenting their use.

This page was last edited on: ( Monday, April 10th, 2006 3:27 pm ) by Administration account

This page was last rendered on 04-20-2024 @ 13:05:33

Using DateTimePlus

DateTimePlus is an Etomite snippet that I developed as a versatile piece of code for displaying date and time information in templates, other snippets, or in chunks. As you can see from the examples listed below, I tried to cover as many bases as possible with this one. And without breaking my arm patting myself on the back, I think I did a pretty good job in doing so. After giving the nitty gritty details on how the snippet works I'm sure that you'll be finding many ways to make use of DateTimePlus.

Why is this snippet named DateTimePlus, you might ask. Well it isn't because it can be used to display the date and time as it can do a whole lot more than that simple task. This snippet can display any portions of a date and time based on parameters sent as the format variable within the snippet call which will be used by the PHP strftime() function to format the output. The snippet will, by default, display the current date and time, or any portions thereof, based on the default settings which can be configured within the snippet code. It can also display a documents createdon or editedon date and time by assigning either date object to the timestamp variable when calling the snippet. And if all of those features weren't enough, you can also make adjustments to reflect differences between timezones. This is done by sending the appropriate +/- difference with the diff variable.

Okay, now that I've boasted the capabilities of the DateTimePlus snippet, look at the examples below and take notice of how many different ways it can be implemented. The examples are fairly self-explanitory and the snippet has enough documentation to cover the code logic as well as default variable assignments. If someone happens to be adventurous and is using Etomite to develop a multi-language site I'm sure that DateTimePlus could be modified accordingly to cater to differing date and time display formats.

Last Edited: [ [DateTimePlus?timestamp=editedon] ] = ( Monday, April 10th, 2006 3:27 pm )

Created: [ [DateTimePlus?timestamp=createdon&diff=0&format=m/d/Y] ] = 07/15/2005

Current Time (UK): [ [DateTimePlus?diff=5] ] = ( Saturday, April 20th, 2024 6:05 pm )

Current Time (EST): [ [DateTimePlus] ] = ( Saturday, April 20th, 2024 1:05 pm )

Current Time (PST): [ [DateTimePlus?diff=-3] ] = ( Saturday, April 20th, 2024 10:05 am )

The DateTimePlus snippet will be one of the standard snipptes starting with Etomite 0.6.1 in an effort to make Etomite as flexible as possible.

Using GetAuthorData

GetAuthorData, as the name implies, is a snippet which retrieves information about the author of a given document. As with all of the new snippets which I have created for inclusion in future releases of Etomite this snippet gives plenty of flexibility to the developer. In addition, besides the GetAuthorData snippet, I have also created a core API function with the same name, getAuthorData(), which can be used within other snippets. In fact, the GetAuthorData snippet makes use of the getAuthorData() function. In light of the correlation between the two methods I will be covering both within this article.

Considering how the GetAuthorData snippet utilizes the getAuthorData function we'll cover the function first. The theory behind the getAuthorData function is that it returns an array of data to the caller based on the common Etomite table column internalKey. The internalKey column is used as a link between all of the manager_user related data tables within the Etomite database. The resulting array returned a call to getAuthorData, $author = $etomite->getAuthorData($internalKey); would yield an array containing $key=>$value pairs for all of the columns in the user_attributes table. The user_attributes table contains the columns id, internalKey, fullname, role, email, phone, mobilephone, blocked, blockeduntil, logincount, lastlogin, thislogin, failedlogincount, and sessionid. Using the example function call above it would then be possible to assign these values to variables using $fullname=$author['fullname']; or $email =$author['email'];, for example. The function itself is relatively straightforward when compared to the GetAuthorData snippet which will be covered next.

Now that we've covered how to use the getAuthorData() function we'll examine how to use the corresponding snippet call, GetAuthorData. First, some theory. As stated previously, the GetAuthorData snippet uses the getAuthorData function as a means of retrieving author related data from within templates, chunks, and documents. The main difference between the two methods is that when using the snippet call it is only possible to retrieve one column of data at a time from the authors user_attributes record. But that doesn't mean that the snippet lacks efficiency. The snippet actually optimizes its efficiency by storing the current results in a session variable in an effort to reduce database queries which could slow the parsers page renderings. A subsequent call to GetAuthorData, whether in the same document or the next page rendering, would result in the snippet checking the appropriate session variable for results prior to calling the getAuthorData function which would once again query the database for the user_attributes record. If the internalKey of the record stored in the session variable matches the internalKey of the current snippet call then the result is returned without the need for the additional database query, thus saving valuable server resources over a period of time. Although the session variable could be populated by the getAuthorData function this task has been left to the snippet so that this process can be bypassed by other snippets utilizing the function call that may not require the overhead of such functionality.

So much for the theory, now let's move on the practical application. Here is where the versatility of this function/snippet pair truly comes to light. Let's say, for example, that you are creating a custom template that is intended to be used by either a specific author or a group of authors, possibly for columnist publications. Such is the theory behind this column, Doing More With Etomite, which implements these features for both practical application as well as proof of concept. My name, which is displayed in the header of this article, has been extracted from the user_attributes table using the snippet call [ [GetAuthorData?internalKey=1&field=fullname] ]. When this snippet runs it sends the internalKey, which has been extracted from the document object record by the parser, to the getAuthorData function for processing. When the results are returned to the snippet it then extracts fullname and returns that value for display on the rendered page. Along the way the snippet also stores the entire author array in a session variable for future reference prior to calling the getAuthorData function again with a subsequent GetAuthorData snippet call. If the internalKey's match then the data will be extracted from the session array rather than wasting time querying the database again. So, what else can this snippet do that makes it so special? How about retrieving information pertaining to the last person who edited a particular page by using the snippet call [ [GetAuthorData?internalKey=1&field=fullname] ] and then getting that persons email address by issuing the snippet call [ [GetAuthorData?internalKey=1&field=email] ], both of which would be returned with only one query of the database because both calls are using the same internalKey. And if the next document page rendered happens to call for the same authors information it will once again be returned without accessing the database. Now does it all make sense? Think versatility and efficiency! It should be noted that you could also send internalKey as an integer just as easily as sending a document variable tag although I don't foresee that method being required very often.

Well, that about wraps things up for this installment of Doing More With Etomite. Next time I'll be covering yet another versatile snippet, GetDocObject, which does as the name implies but with a few added twists. In closing, the getAuthorData function and GetAuthorData snippet will be included in the Etomite 0.6.1 core API for developer convenience.

Using ListDocuments

ListDocuments being used to display the contents of the Repository > News folder.

These listings have been created using the ListDocuments snippet which is an improved version of the original NewsListings snippet. ListDocuments can be used to aggregate documents from multiple folders as well as having the capabilities to accept passed parameters to control several output parameters. See the snippet code for details on the versatility of this snippet.