Global Constant
Steve Nay's ramblings

Dialoguing module

You may remember my previous two posts about dialoguing. I illustrated two methods for doing it: form submission with watch() and web events. I’ve been using the second of those methods so much that I wanted to abstract it out to a module. a163x121 is the result.

Documentation

Here’s how it works. First, there are two configuration options that you need to specify when you import the module:

  • app_id - the ruleset ID that will respond to the web events that will be raised. Usually this will be the same as the ruleset in which you are using the module.
  • app_version - either "dev" or "". If you specify "dev", the module will raise web events to the dev version of the ruleset. If you leave it blank, it will raise web events to the production version of the ruleset.

There is one method that does it all, called get_data(). Here are the parameters:

  • selectors - an array of the jQuery selectors that identify the DOM element whose data you want to extract
  • method - usually "val" or "html". The jQuery method to get the data out of the DOM element.
  • param_names - an array parallel to selectors that describes the names that should be given to the data once they are extracted. These will be accessible in the handling rule via event:param("...").
  • event_name - the name of the web event that will be raised once the data is retrieved. You will be writing a rule to respond to this event.
  • callback - the name of the JavaScript function that should wrap this code. This is useful if you want to extract the data when the user clicks a button (e.g., on a search form). If you do not wish to use a callback (i.e., you want the extraction code to run right away), pass an empty string.

Example

I retrofitted the example from this post to use the new module, so the code may look familiar to you. First, I added one line to the meta block:

use module a163x121 alias dialogue with app_id="a163x104" and app_version="dev"

Then I rewrote the rule a bit:

The original byufb_dir_search() function contained two things: First there were some lines to unhides the search results box and show a progress bar; second there was the dialoguing code. Since the module only handles the dialoguing code, I broke out those first two lines into a new function called byufb_dir_search_prep(), which in turn calls byufb_dir_search(). The “Search” button calls the prep function. I passed the name “byufb_dir_search” to the dialoguing module’s get_data() action so it knows what to name the JavaScript function.

The rule that handles the web event is exactly the same as before; no changes were necessary.

Conclusion

This simplifies the code by abstracting out the mundane JavaScript to get data from the page and raise a web event containing that data.

What do you think?