Formulize is the XOOPS of XOOPS. It allows you to create custom forms and then use and display the data as you see fit to build interactive applications within XOOPS. Very powerful but comes with a high learning curve, too.

Latest: 3.12 | Website

Formulize also has several companion modules: Pageworks, iMenu, and RegCodes all look worthy and are on my short list for review/usage. Formulize 3.11 now accesses extended profile information directly from the new XOOPS 2.3.x Profile Module.

Note: other form-based modules are worth reviewing if you need a simpler form tool, but none of them have the true power of Formulize; however they are also much simpler to learn and use and will meet many simple forms needs. These include Liaise (a Contact Us module), Contact Us, Formulaire (what appears to be a Liaise clone from a usability standpoint with a couple of small additions) and BMSurvey, a survey tool/collector/reporter.

Finally, I'll note that this really isn't a HOWTO document, rather it's a collection of notes for me so I can remember everything. You may find some helpful information in here, and you're welcome to suggest information that will help others.

Installation | Creating an Application | Bugs/Defects | Enhancement Requests | Coding Reference

Installation

New Install

Generally a breeze, just upload and install per the usual XOOPS instructions. They include a XOOPS hack that replaces the datebox default value functionality in XOOPS (which I had problems with in other modules, too, where the default is todays date and causes problems there....). It uses the non-US standard of YYYY-MM-DD which some don't like.

The XOOPS Hack

To get datebox functionality to work correctly, you will want to install their hack which includes changes to:

• class/xoopsform/formtextdateselect.php
• include/calendarjs.php

Note that I would suggest adding the XOOPS security php code per my instructions below. You also have to add the calendar script into your theme: <{$calendarjs}> or the pop-up calendar won't actually ever show. Note this hack changes the default date and such throughout your XOOPS site.

Upgrade

They have extensive upgrade information. I started playing with this in 3.1, so 3.11 didn't require me to do any upgrades, but you'll want to follow their instructions if you're upgrading from earlier editions.Pretty easy, and in the course of doing some debugging, I did successfully upgrade a 2.3 application to a 3.11 application using their instructions so I remain confident others can, too.

Configuration

Just a little stuff to configure, especially date, and number conventions.

Creating an Application

Believe me, the module has a fairly steep learning curve, but is very powerful. If you want to make a real application, you'll want to ensure your PHP skills are up to date and pour through the Formulize/Pageworks documentation. It's not quite as steep as learning the underpinnings of XOOPS, but you'll be mired in it for awhile. These notes are for someone (primarily me) who's read through the documentation provided by the authors. You'll likely refer to it again and again especially for their functions and such.

If you're a database and php-based app developer, this may make sense to you. For others, your mileage may vary.

Quick Overview

A Form is the basis of any application and is essentially a database table with an interface to manage the data and views. A Framework sets the relationship between two or more Forms (tables). A View is a configured display set of fields and sort order. A screen is an advanced method of displaying the data and actions (buttons and such) from a Form and can be based on a View and/or a Framework as well as make custom php-based templates. With the custom templates, you can link to almost anything and create almost any action.

Forms/Tables

Create the basic forms with all the information you want in them. This is just like creating a table (in fact, it does). You can create tables of data to use/link to fill in the fields of other forms (like states/provinces and/or countries). Whenever you think form, think table. Now, we'll just think forms. You can set them to display or not. Display or not is wholesale (all users). The permissions (and denies) can be per field. Either way, if the user gets to the form screen, then they'll have access to whatever you give them permission to access.

Views & Screens

Views is a method to save your data selection (columns and WHERE conditions through the QuickSearch fields) and sort order. Screens are the method of displaying and interacting with data based on a Framework and/or Saved View as well as a Multi-Page form.

Quicksearch - There is documentation on (but strangely missing the OR searches, and if it exists, boolean searches)

• OR Searches: OR!=Text//OR{BLANK}
• AND Searches:
• Boolean ?? (will have to try it)

Screens allow for more custom layouts based on the data specified in a View. I'll note that the usual permissions don't always apply here when displaying data, so you'll have to check the various permissions for the various users and only display what they should be able to see.

If you can't do it in the Screens, you'll have to resort to Pageworks; a last resort. So far I haven't had to use Pageworks and the developers continue to try and steer you away from it (and I understand why with the overhead aspects).

Frameworks - Relating Forms/Tables

Create Form/table relationships (one-to-one, one-to-many, many-to-one) by creating a Framework. A Framework controls the relationships between one or more tables together as a single set of data. Screens can be based on a form or a Framework that is based on a form.

Permissions

Permissions are very granular specifying not only which forms you may see but also which fields and/or entries (based on the user's entries, all entries, as well as those in the user's groups). Unlike most XOOPS modules, you can also deny permission. Besides groups, you also have the current user as a selection in many places. It may take a little time, but you'll figure out what they do. About the only ones that aren't intuitive to me were view_globalscope (can view all entries) and view_groupscope (can view entries owned by those in user's groups).

Bugs/Defects

Admin Menu Wrong with ThAdmin

While not necessarily a true bug, I found an incompatibility between Pageworks and the admin module when running the now highly recommended ThAdmin module that themes the administration area. The problem is that the code calls the global variable $adminmenu which doesn't sit well with ThAdmin. Turn off ThAdmin in the site general preferences, and everything works as advertised. I made a few small changes to admin/index.php and include/pageworks_includes.php to make the menu display correctly and submitted the bug to the Formulize forums so they can fix in a future release. There is a comment in the code that reminds them they should look at it anyways.

XOOPS Hacks

The class/xoopsform/formtextdateselect.php file is VERY old (dates back to a code page from XOOPS 2.0.9.2 and at this writing XOOPS is at 2.3.3). Yet, there were a couple of changes, slightly significant: the basic security feature preventing files from running outside of XOOPS. Also, I didn't like the way this hack sets the JS calendar to the current date rather than the date of the value. Also, there was still a 'test' output in the calendar script. It seems generally compatible, though. So I played around with it some to integrate it better with the 2.3.3 release.

Magic Quotes

It took me awhile and a discussion with the developers to get this figured out. I couldn't save the options for a select box (there are a couple of other elements this occurred with as well -- essentially any element that stores an array of selectable values in the ele_value and ele_uitext fields of the _formulize table is affected). The problem was that magic_quotes_gpc was on and needed to be off. They had supposedly fixed that in version 3.11, but it wasn't working for me. Once I set magic_quotes_gpc to off, it started working as it should. The developer is now aware. However, magic_quotes_gpc is set as deprecated already (it was a bad idea security-wise, realistically, but came at a time before SQL injections were a common attack vector) and will not be included in PHP 6, so I would suggest they put it in the instructions and move on to more important tasks.

Reference to Database Table

According to information I found in the forums, apparently this doesn't work anymore and was done for a single client. I liked the idea, but it was tough to find the handles and such which were just numbers (I had to do a print_r statement in the logic/template areas to figure this out). I thought it might be an easy way to get some data from another table without a custom query or xoops_getmodulehandler call through custom code. Just a notation that it's not a priority for the team at this point.

Enhancement Requests

Multi-Column Sort

Unfortunately, Formulize currently only sorts by a single column at a time. The only way I figured out how to sort by more than one column at a time was to create a derived value combining data from several fields and then sort on that field. To reverse sort numbers, I had to subtract from a larger value in making the derived value.

xoModRewrite Issue

If you are using the xoModRewrite "module" then the main index page redirects to the old URL (with modules in the path). It's a simple fix. In initialize.php, change line 179 from:

header("Location: " . XOOPS_URL . "/modules/formulize/cat.php");

to:

header("Location: cat.php");

Back to Top

Coding Reference

GET/POST variable

• fid - formid (found as GET var title when editing form elements)
• sid - screen id (form screen number, can be used alone) - highly configurable, can be combined with views
• loadview - saved view to load, sv_id (see below)
• cf - Framework ID (same as frid, in edit URL when editing a framework)
• frid - Framework ID (same as cf, but used to view)
• ve - entry number

Accessing the Forms, Frameworks, Screens, Views, and Pageworks Pages

Formulize Pages, Forms and Entries

http://www.yoursite.com/modules/formu ... ndex.php?fid=5&ve=132
http://www.yoursite.com/modules/formu ... ndex.php?frid=3&fid=7
http://www.yoursite.com/modules/formulize/index.php?sid=1
http://www.yoursite.com/modules/formu ... php?sid=1&loadview=12

Forms without entryID (ve) show a blank form. A Framework should also specify the primary formID. A Screen can be combined with a view (in the formulize_saved_views table, the sv_id parameter).

To sort and have certain columns and such, just make a bunch of views with the different sort orders, then look at $the_view_name variable(s) to find which one is in use, then modify the display as appropriate. Too bad you only get one sort column (best I can tell).

Pageworks Pages

http://www.yoursite.com/modules/pageworks/index.php?page=ID (ID is page number)

Screen Templates

Buttons and Controls

Note that the Formulize developers are working to help users get away from needing to use the Pageworks functionality (which can be much harder to keep up) and allow it all to be done from a combination of the Screens combined with the specifications and setups used in the Views and Frameworks aspects.

Tips/Tricks

Limiting a Drop-Down Box to User-Created Entries

If you use a Select Box and then pull from another table, you get all entries to instead of just those you created -- even if the form is supposed to show only the user's entries. Maybe this is a bug, maybe a feature. We'll let the developers decide. But, you can create a field in the secondary Form (table) of Derived Value type and then fill it with the entry's creation_id. This is because derived values are calculated AFTER the rest of the data in the form is saved. Then you can filter the select box to show just the entries that are equal to {USER} (which matches the creation_id).

Top/Bottom Template Variables in List Portion

If you need access to variable values from the Top/Bottom template (for instance, $The_view_name isn't accessible in the List Portion), then you have to declare and set a global variable (make sure it's unique) in the top template and then you can access that info in the List Portion by declaring the variable global and then accessing it.

Global Variables

There are some variables I've found that may prove useful (some only available through $GLOBALS[]):

• entry - the value of current entry (if any), null if listing
• formulize_screen_loadview - viewID loaded (also loadThisView???)
• formulize_countMasterResults - results count
• screen - details for the screen in use
• Unknown but found: formulize_up, formulize_elementData, creation_users, formulizeConfig, formulizeModuleConfig

Quicksearches

Pageworks Functions

Some of these work in screens, templates, too.

• getCurrentURL();
• $_POST['var']
  • form_submitted - true if user clicked Save button
  • lastentry - contains ID of last entry if user clicked All Done button
• $The_view_name - is true if name of view last selected from the list (note these won't work if you try to use special characters in your view name)
• $viewX — X (number) corresponds to position of view in list, 1 through n (note the position can change as you add/remove views)

Displaying Data, an Example

// get all the entries in form 12
$data = getData("", "12");
// getCurrentURL is a special function available in Pageworks pages
$currentURL = getCurrentURL();
// "Activity Log" is the title of the form
// "87" used in the display function is the element ID of the form
// element where the name of activity is entered
foreach($data as $entry) {
$ids = internalRecordIds($entry, "Activity Log");
$id = $ids[0];
print "<p><a href=" . $currentURL . "&entry=$id>" .
display($entry, "87") . "</a></p>";
}
displayForm("12", $_GET['entry']);

maybe do an if/then, display the entry above the data, heck it could even be a sliding jquery box, eh?