Transforming Text in Xaraya
The hook system in Xaraya provides Xaraya with the extensibility that is unmatched in other content management systems. There are several types of hooks in Xaraya and calling them in modules is a relatively easy exercise to expand any module. All hooks though, fall into one of three categories. API hooks which do something when an API is called. Whether that be when something is created, modified, deleted. Display hooks have control over the UI and are the visible hooks in the system. The final type of hook is the Transform hook which will look at either the input or the output of the content and transform the text in a different manner.
These transform hooks are versatile in nature. Some examples would be the BBCode transform, Autolinks, BBClick, Wiki type transforms. Basically any control over the content that you need can be done via transform hooks. I do a couple of items with changing calls to link to search engines to save me time. I also make extensive use of transforms to change the output to insert paragraph tags into my content to maintain the structure of my documents without having to format each one. After all, why should I be interested in content management if I still have to format every simple piece of text.
How transform hooks work is very simple:
- Module calls the transform hooks
- Xaraya calls the appropriate hooks
- Hook must be active for the content
- Hook must be capable of performing action
- The specific function performs the transform action
- The transform returns the output back to the calling function
This is in essence how the transform hooks work.
Module calls the transform hook
Each module output function should call the transforms when returning content to the page. If a module is not, then the module is not complete in my opinion. Just like in the '92 election where "it's the economy stupid" was the mantra, with Xaraya "it's the extensibility stupid". Calling the transform is basically one or two lines of code within your module:
This is very simple. We are basically calling the hooks and telling them that whatever an item transform is active, use this id and transform the $data array for the module "modname".
The specific function performs the transform action
Once called, the transform will receive each field in the $data array and do its thing. An example would be the line break transform in the HTML and BBCode modules.
In this case, this is a secondary function that is called from the html module which uses a primary function to set up the function to be called. These very simply takes the $text array, which is each field that you sent from the $data array and adds a paragraph tag when it finds a line break.
It then returns the $text string to the intermediary function which in turn returns it back to the main function which called the transform in the first place. Once back in the main module the text is transformed to whatever hooks the website's administrator has enabled. The module in fact does not know what it is displaying any longer just that it is displaying something.
Final thoughts about transforms
There are two basic types of transforms, input and output. Input transforms should be used with basic HTML type transforms which you do not need to be dynamic. For instance the BBClick module will take a URL string and transform it to an anchor. No need for this to be dynamic. However, Autolinks change over time, and for that reason they remain on the output functions.
Output transforms will use more resources to work. Pay attention to using the transforms on long lists, as that can drain your performance in your module. What you may want to consider is allowing the option of turning off the transforms in the summary views, to reduce the performance drains if necessary. This is what the articles module does, and it tends to work quite well.
All output functions which are displaying anything through the user type displays should be transformed. It should be considered a necessary call to your module and will allow others to develop smaller helper modules to expand your output.