• Internet
• 24.07.2017
• EN

"Why you do want an RQL Framework?"

written by Boris Crismancich, 23. Februar 2012

Prologue

Some of the hints or techniques I describe might seem trivial to you. In this case, please pick the raisins and leave the rest. Funny enough there is lots of users even in large enterprises who don't know them.
 

Introduction

When using RQL for creating new dialog windows or scripts in the background or as a scheduled job, you will start with one first RQL Script or RQL Plugin. One you have done this, you discover how much time you wasted spending hours on things, you could have done in half the time using RQL. At this point you start your own plugin collection. And once you have started, it will certainly grow.
 

File structure

Use an own subfolder within the plugin folder for each script or plugin.
 

Re-use code

When ever you write the XML code for a special RQL query, note that you will most likely need this query again. So first of all, put it in a function (e.g. getPageInfo). Store this function somewhere outside the directory of your current plugin. So this function may be used in any plugin you will create in future. Try to avoid redundant RQL queries. For instance you need a page action load for both, retrieving a change author and retrieving a pages change date. But instead of creating getChangeAuthor(strPageGuid) and an almost identical  getChangeDate(strPageGuid), use a general getPageInfo(strPageGuid) that gives you at least an associated array.

This would look like: 

arPageInfo = getPageInfo(strPageGuid);
strChangeAuthorGuid = arPageInfo["attributes"]["ChangeAuthor"] strChangeDate = arPageInfo["attributes"]["ChangeDate"]

The magic behind this is a function that returns an XML string as associative array:
 

The Valuable getResultArray Function

Let's say you want to list the elements of a page. You use the ELEMENTS load RQL query and get the following XML response:

The getResultArray function would allow you to get an array of the page elements:

Line 4 shows thwo parameters. The first one is an XML string. The second one may be empty. But when an element name is provided like in this case, it collects all of these elements from the rql. In line 7 and 10 you can see how to get each of them. Use them to capsule the famous sendXml function into one getResultString(strRqlQuery) and one getResultArray(strRqlQuery,strTagFilter). While this does not sound like no big deal, this is one of the most valuable things for RQL development and will become one of your best friends and you will never write the words sendXml any more.
 

An easy approach to dialogs

Long time I was thinking and looking for a fast and good way for creating RQL plugin dialogs. I wanted to have the code in a central place without touching it within the plugins.

And I wanted to avoid writing HTML as far as possible. I created a simple Dialog and stored it in the view folder of my framework lib.

Then I created a function that includes this dialog. So when my script starts, the dialog is written. In order to add content, I add a JavaScript.
 

<script type="text/javascript">
$("#dialogContent").append("Content");
</script>

But as i don't want to do this using javascript I added a function addCode. In this example in old school asp:

' Adds code to the dialog content using javascript
' @param {String} strContent Content to append
' @author Boris Crismancich 
Sub addContent(strContent)
   Response.Write "<script type=""text/javascript"">$(""#dialogContent"").append('"& strContent&"');</script>" & VbCrLf
End Sub

So this is how I create a complete dialog.

jDoc, jsDoc, phpDoc, and others

Now let's say you have created a couple of plugins and your library has grown. You are beginning to create a new plugin and you know you already have a function for retrieving an element guid. Unfortunately it is somewhere within your function collection. Was it in the page functions file or in the elements function file? Exactly this is solved using javaDoc or similar systems in other languages. While coding, you comment wach function as always, but in a special way:

And when you youse a good IDE instead of a simple Source code editor, it will instantly help you. As soon as you write the function name, it will show you the details from the function comments, even if they are defined in separate files...

In this case I started to write getElementGuid and the IDE opened the documentation. So I could see that the page guid is the first and the element name the second parameter. Whithout opening and searching the files where I defined the functions. You don't have to intall anything in order to use this. A nice goodie is that tools like javaDoc can gerate a full documentation from this. If needed.
 

Staging and versioning

Todays OpenText customers seldomly have only one single cms server. In most cases it's a cluster. And it's quite common to have this cluster three times. One for development, one for QA/testing and one for production. As each plugin has to be copied to all of the servers, you have to copy a plugin 5 times. This is much easier with versioning tools like Git, Subversion or CVS. It allows you to click "Commit" on the development server and then click "Update" on any of the other folders and the job is done. This is the simple thing. Let's say there's a version 1.0 of your Plugin on the two production servers, you were asked to add some features and there's a version 1.5 on the test environment while you are working on bugfixes for a 1.5.1 in the dev environment. See the point? These tools help you keeping the overview. You cann roll back changes without losing the current version and you can use the version history what was changes and who changed it.
 

Tools for large frameworks

As soon as you forsee that multiple users will work on your framework, perhaps even people from different locations, make sure you use Git instead of SVN. It has a way better merging supprt than SVN and works better for multi user environments. Use namespaces, too so that the modules created by different users do not affect each other. Last but not least use test driven programming. First you write the test by telling what you put in and what you expect to get out. Then you program anything in between. In the end your test will be green. Why doing that? Let's say you change one of the core RQL functions of your framework. Are you really sure that all of your 75 Plugins still work fine? How do you now? Will you test each of them by hand? I guess you got the point. Pushing a button and getting 71 green lights and 4 red ones is a nice thing. And think about new CMS versions or Updates. One click and you now whether all of your plugins still work or not. This saves lots of time and money.

Boris Crismancich: I have been writing RQL for years and in the meantime I was introduced to numerous people who did way better than me. The reason why it is me writing this blog is that I have the chance of picking the raisins.

Source: Why you do want an RQL Framework