Q (cue) rapid dev library

  Returns an Integer, which is the length of current Stack.

message

This is a mandatory parameter in the form of JS Object. This object should have the following properties:

• message: String
  Text of the message to be displayed in stacktrace records.
• type: (optional) String
  This should be either "info", "warning", or "error" (case-insensitive). Value of this parameter is one of the filterable properties for GetStack().
  Default "info" when empty/null.
• priority: (optional) Integer
  Priority determines whether or not the message will be recorded, based on current setting of Q.options.loggingMinimumPriority. In order to minimize memory usage and unnecessary overhead, Q usually records only stack messages of priority 1 and above.
  Default 0 when empty/null.
• origin: (optional) String
  Due to lack of backtracking of function calls in Javascript, Q uses this optional parameter to identify the origin of the stack record. Recommended value is, for example, "myJSClass.myFunction()".
  Default false when empty/null.
• arguments: (optional) Array
  Sometimes it is useful to know what arguments your function has received. By simply passing the reserved word arguments to this property, you will record an array of arguments exactly the way your function had received them.
  Default null.
• element: (optional) jQuery DOM Object
  When appropriate, you may also want to provide a reference to a DOM element for easier debugging. This property is where you should place it.
  Default false when empty/null.
• instance: (optional) String
  When appropriate, you may also want to provide a string identifier of the instance which recorded the Stack item. Default null.

1. function HelloWorld()
2. {
3. this.id = 'HelloWorld';
4. Q.AddStack(
5. {
6. message:'Hello Stacktrace!',
7. type:'info',
8. priority:1,
9. origin:'HelloWorld()',
10. arguments:arguments,
11. element:$(document)
12. instance:this.id
13. }
14. );
15. }

Instead of a whole Object, you may also provide only a String containing the text of the message to be recorded. If you do that, the optional properties will be set to their defaults.

1. function HelloWorld()
2. {
3. Q.AddStack('Hello Stacktrace!');
4. }

  Returns an Array of all records in the Stack, matching the filter criteria (if any were specified).

filter

This is an optional parameter in the form of JS Object. This object may have the following properties:

• origin: String
  If value of the origin property matches or is a substring of an origin property of a Stack record, the record will be displayed.
• type: String
  If value of the type property matches that of a type property of a Stack record, the record will be displayed.
• message: String
  If value of the message property matches or is a substring of a message property of a Stack record, the record will be displayed.
• instance: String
  If value of the instance property matches or is a substring of an instance property of a Stack record, the record will be displayed.

1. function HelloWorld()
2. {
3. Q.GetStack(
4. {
5. origin:'HelloWorld()',
6. type:'info',
7. message:'Hello',
8. instance:'HelloWorld'
9. }
10. );
11. }

1. function HelloWorld()
2. {
3. Q.GetStack({type:'error'});
4. }

  Returns an instance of Q.

This function allows you to trigger an existing event within your plugin. It is one of the key components to a fully customizable event model.

eventName

This String parameter is the name of an existing event. If a non-existant event is triggered, the method will create an error report in the Stack. Both successful and unsuccessful event trigger return instance of Q.

params

This optional Object parameter is passed to all event handlers as parameter. It is recommended that one of the properties of this object is instance with value this, so that the event handler can properly address the instance which triggered it:

1. this.eventTrigger("MyEvent",{instance:this});

1. this.onMyEvent(
2. function(e)
3. {
4. e.instance.myFunction();
5. }
6. );

Note that plugins created using Q.PluginFactory also use event methods, though they're not using the ones from Q.Core. Therefore you would call this.eventTrigger within a plugin, instead of Q.eventTrigger.

  Returns an instance of Q.

This function removes either a single event handler from the queue, or drops the entire queue of event handlers.

eventName

This String parameter is the name of an existing event. If a non-existant event is referenced, the method will create an error report in the Stack. Both successful and unsuccessful function calls return instance of Q.

eventHandler

This optional Function parameter is used to identify the exact handler to be dropped. Because event handlers are most often written as closures, this is the most reliable way of identifying a handler. Q looks at all handlers registered in the event queue for that particular event, and compares their string representation to string representation of this parameter. All matching event handlers are then removed from the queue. Yes, all of them - it is not unheard of to have an event handler registered multiple times; this takes care of that issue.
Note: If you leave this parameter out, the entire event handler queue will be cleared.

1. this.dropEvent("MyEvent");

1. this.dropEvent(
2. "MyEvent",
3. function()
4. {
5. alert('Hello World!');
6. }
7. );

Note that plugins created using Q.PluginFactory also use event methods, though they're not using the ones from Q.Core. Therefore you would call this.dropEvent within a plugin, instead of Q.dropEvent.

  Returns String

This Object encapsulates two key methods for handling HTML Strings: Encode and Decode. While many implementations strive to process strings using regular expressions, Q uses a temporary DOM node to perform the transformation in a fast and reliable way.

html

This String parameter contains unescaped HTML as can be, for example, retrieved with jQuery function $('#MyDOM').html().

text

This String parameter contains encoded HTML, for example a result of HTML.encode().

1. var EncodedHTML = Q.HTML.encode( $("#MyDOM").html() );

1. $("#MyDOM").html( Q.HTML.decode( EncodedHTML ) );

  Returns String

This Object encapsulates two key methods for handling Base64: Encode and Decode. It is quite rare to encode and decode Base64 in Javascript, but since Q supports JSON and fully AJAX-driven interfaces, this feature will eventually be used.

source

This String parameter contains raw source data to be encoded.

base64

This String parameter contains encoded Base64 data.

1. var BASE64EncodedString = Q.Base64.encode( "MyDataString" );

1. var MyDataString = Q.Base64.decode( "BASE64EncodedString" );

  Returns String

This function provides a way to use parts of HTML as templates for rendering data. To achieve this, the HTML code needs to be wrapped in HTML tag <template>, which is a part of HTML5 specification. Note that <template> is not rendered by browser, and therefore its contents are hidden from users, yet still available to Q.Template.

A <template> to be used by Q.Template needs to have two attributes assigned: id, and data-content. The id has to be unique in the page scope, and the data-content attribute needs to have value "QTemplate". That is how Q recognizes <template> that is assigned for its use.

1. <template id="myTemplate" data-content="QTemplate">
2. <strong>{Q:lastname}</strong>, {Q:firstname}
3. </template>

Notice the placeholders {Q:lastname} and {Q:firstname}. As you may have guessed, these will get replaced by actual values of variables lastname and firstname. There placeholders can be used anywhere in the template; it is therefore very easy to fill in parts of text, URL, CSS classes, etc. At the same time, you are keeping HTML code separate from data, which is a great thing - and any software architect and webdeveloper will agree.

templateId

This String parameter tells Q.Template which HTML template to use as basis for rendering.

1. <template id="MyTemplate" data-content="QTemplate">Hello World!</template>
2. Q.Template("MyTemplate");

data

This optional Object or Array parameter contains structured data to be rendered (e.g. a JSON response from AJAX request). Note that Q.Template always expects the data to be an Array, and if the data provided are an Object, Q.Template transforms it into an Array whose only item is the Object you have provided.

1. [
2. {lastname:"Doe", firstname:"John"},
3. {lastname:"Smith", firstname:"Bob"}
4. ]

1. {lastname:"Doe", firstname:"John"}

1. [
2. {lastname:"Doe", firstname:"John"}
3. ]

filter

This optional function parameter may contain advanced logic that filters the data and only performs templating on those that match the function's criteria. The function is called for each data item and receives the item's data as parameter. Should the function return true, the record gets displayed. Should it return false, the record gets skipped.

1. var MyData = [
2. {lastname:"Doe", firstname:"John"},
3. {lastname:"Smith", firstname:"Bob"}
4. ];
5. Q.Template(
6. "MyTemplate",
7. MyData,
8. function(data) {
9. if(data.lastname==='Smith') {
10. return true;
11. }
12. return false;
13. }
14. );

The very simple filter function above would return true only for records where the lastname is "Smith", and so only the "Bob Smith" item would get rendered.

  The example above is a very simple one; your filter functions may be much more complex, even up to the point where they perform AJAX requests, themselves.

Q.Template, naturally, doesn't magically understand where you want the results displayed. To actually print them out into your web page, you'll need to use jQuery's function $.html(). For the sake of being thorough, let's take a look at what a very plain page with a very plain use of Q.Template looks like:

1. <html>
2. <head>
3. <-- contents of HEAD element -->
4. </head>
5. <body>
6. <-- This DIV will become a "canvas" into which we print the results. -->
7. <div id="MyOutput"></div>
9. <-- This is the TEMPLATE we will use to print out variables -->
10. <template id="MyTemplate" data-content="QTemplate">
11. <strong>{Q:lastname}</strong>
12. {Q:firstname} <br/>
13. </template>
15. <script type="text/javascript">
16. $(document).ready(function() {
17. var MyData = [
18. {lastname:"Doe", firstname:"John"},
19. {lastname:"Doe", firstname:"Jack"},
20. {lastname:"Smith", firstname:"Bob"},
21. {lastname:"Smith", firstname:"Bill"}
22. ];
24. $('#MyOutput').html(
25. Q.Template(
26. "MyTemplate",
27. MyData,
28. function(data) {
29. if(data.lastname==='Smith') {
30. return true;
31. }
32. return false;
33. }
34. );
35. );
36. });
37. </script>
38. </body>
39. </html>

What happens in the example above? Well, Q.Template finds the HTML element <template> that is identified as "MyTemplate". If it didn't, it would fail without throwing a JS error, but it would record an error in the Stack, so you could retrieve it using Q.GetStack() method.

Next the method loads the data provided as 2nd parameter. Since the data is already an Array, Q.Template leaves it unchanged. Then it begins looping over the data Array. Because we have also provided a 3rd parameter (a filter), Q.Template evaluates the filter function and provides it the entire row of data.

If the filter function returns true, Q.Template proceeds with parsing the template, processing the variables and inserting their values into marked places. Then the processed HTML code is stored in local cache until processing of all data is complete.

Finally, Q.Template returns the cached results as a single string of HTML code. That is where jQuery function $.html() receives the processed data and inserts them into the right place. The example would result in this:

1. <div id="MyOutput"></div>
2. <strong>Smith</strong>
3. Bob <br/>
4. <strong>Smith</strong>
5. Bill <br/>
6. </div>

The actual value of this method begins to show more as you'll have more data, an more complex structures to render.

  That's right, Q.Template can render much more complex structures, including nested Objects or Arrays. A "Guide To Advanced Templating" is being prepared.

  Returns String

This function returns a Unique Identifier string, generated according to Version 4 UUID specification.

This method does not accept any parameters.

  Returns String

This function returns a string representation of a human-readable date and time. The function calculates how much time has passed since the provided date/time, and return a human-readable format of a time (and date when applicable).

A date/time which falls on today will only show time. A date/time which happened yesterday, will read "Yesterday at hh:mm". A date/time which happened two days ago, will read "Two days ago, at hh:mm". Anything older than that will display a date and time.

datetime

This optional String parameter should be a String representation of a timestamp. Timestamp means "number of seconds since 1/1/1970". When left empty, defaults to "now".