Xaraya Module Development Basics: Part 2

When I left you last time, you had your new module's DNA files established (xarversion, xarinit, xartables). Your module has a name and a registered extension number (to be official). It still doesn't actually DO anything, except represent potential; much the same as your own DNA. But it gives you the instructions needed to build it into something that performs. All you really need to know is the database structure to get started writing the rest of your module.

The database structure of your module tells you what tables and what fields your module will be dealing with. In it's most basic form, all a module really does is manage a specific type of data. This implies the use of one or more tables, each of which will have roughly the same set of functions required in order for your module to make use of it.

So, pay attention, as we explore the real guts of your new module...

Every data component and it's associated table will involve a certain time-honored set of functions that are an absolute must if your module is to work correctly.

These functions come in two sets: data-output and data-input.

Data-output function sets use an API function to grab the data and a GUI function to display it.

Data-input function sets use a GUI function to display the input form, a GUI function to catch form submission, and an API function to make changes to the database.

In some cases, a data-input function set may place both the form and the form catcher in the same function. This is often the case with the "delete" data-input function set. Neither method is incorrect, although complex form processing typically necessitates placement of the form catcher in it's own file.

Every data type, therefore, makes use of the following basic function sets:

• View a list of data items
• Creating a new data item
• Displaying a single data item in detail
• Modifying an existing data item
• Deleting a data item

At three functions apiece, this results in 15 different functions, each in it's own file.

This, of course, doesn't take into consideration all of the associated BlockLayout templates that will be used by those functions; another five files.

You can generally deduce the default contents of each file based on a quick copy-and-paste from either the Example of Dyn_Example modules. Established module developers typically have their own set of files that get re-used and updated periodically to include improved feature implementations. This typically begins with the desire to simply remove the plethora of inline comments that come with the example modules.

Another dev trick is to just copy the Example files (or your own default set) and then run a cross-file search&replace to establish the name of whatever new component you are working on in the code. This can blow up in your face if you choose a commonly used name for your module or it's fields. Try to avoid names that appear too generic, like "object". And avoid naming individual components the same as your module, if you intend to search&replace, unless you enjoy spending a lot of time correcting discrepencies; it's not always the fastest way to get it done.

There is currently some debate over the preferred location for component files, given the options of placing them in the user-side of the module, the admin-side, or in their own component directory. I am a fan of component directories because it allows more freedom to customize both the user-side and admin-side deployment of the same features in different ways. This makes it very convenient for AJAX based deployments that need to pull a component form separately for placement inside an existing page.

So, let's say that you decide to create a module called "Widgets". You have your DNA files, which instruct Xaraya to create your Widgets table in the database. Your resulting files would then be as follows:

• modules/widgets/
  • xarversion.php
  • xartables.php
  • xarinit.php
• modules/widgets/xaradmin
  • main.php
  • modifyconfig.php
  • updateconfig.php
• modules/widgets/xaruser
  • main.php
  • display.php
  • view.php
• modules/widgets/xarwidgets
  • display.php
  • view.php
  • new.phpp
  • create.php
  • modify.php
  • update.php
  • delete.php
• modules/widgets/xarwidgetsapi
  • get.php
  • getall.php
  • create.php
  • update.php
  • delete.php
• modules/widgets/xartemplates
  • admin-main.xd
  • admin-modifyconfig.xd
  • user-main.xd
  • user-display.xd
  • user-view.xd
  • widgets-display.xd
  • widgets-view.xd
  • widgets-new.xd
  • widgets-modify.xd
  • widgets-delete.xd

Ok, so 31 files total. It seems like quite a lot for a single module with only one table. However, you must keep in mind that each file contains one function (except xarinit.php, which has three). This makes it a lot easier to keep track of where a given function is at, although it may result in you have quite a few files open at the same time when working.

Some of the most common ways to expand the functionality of your module are as follows:

Register a "usermenu" hook that pulls a usermenu function in your module so that you can provide access to your module from the "My Account" section of the website. This is useful for any module that involves users creating their own content. First, you have to make sure that you register the hook in your module initialization (xarinit.php). Then you'll need to create (modulename/xaruser/usermenu.php) and two new templates: user-usermenu_form and user-usermenu_icon. Take a look at these files in the Themes module (or just flat-out copy them into your own module and play search&replace).

Other modules that contain similar features to what you wish to implement are the perfect source of code to replicate, saving you hours of development. There is no use re-inventing the wheel... unless, of course, you think that whatever wheel currently being used is truly square.

You can also provide a set of default links to various parts of your module that can be used by the Xaraya menu block to add navigation options. Simply create a getmenulinks file/function in either your xaruserapi or xaradminapi module directory, and the links specified will be pulled by Xaraya when indicated.

Finally, the most common basic module feature to include has got to be the admin and user menus. This is the first exposure to the BlockLayout template tag ("<xar:template file='...'") that most developers typically receive. By creating an "includes" subdirectory in your xartemplates directory, you have a place to put templates that will be re-used by your module across several other templates in it. The first one you find is usually right at the top, pulling in either the admin or user menu from the includes directory.

Next time, I'll discuss the most commonly found code snippets that are used to build your module, starting with database queries and data retrieval methods. Ciao.