CabMasterPro User Guide
The middleware action command ShowFriendlyPages lets you define one or more categories and pages in a QIQ file, and make it pop up as a modal friendly pages user interface dialog (with OK/Apply/Cancel buttons). The controls on the pages of this popup edit values in the "current context".
So for example if the popup action is done at item level, then any variables edited will save their new values into item level variables. Similarly, if the popup action happens at section level, then the current section will be the context receiving any changed variable values.
To make a QIQ file for use as a ShowFriendlyPages control file, you can edit/create any collection of one or more categories and pages, then "Save" that as a QIQ file, using the "Save" button on the dialog. For example, we could save the file myqiqname.qiq in the Library folder (or specify the full path) and then it will be used to create the popup when put in as the second parameter like this:
ShowFriendlyPages("My Title","myqiqname",ANum,"ANum","section[box]")
The first parameter provides the text for the title bar of the popup.
The third and fourth parameters as a pair provide optional substitutions so the one qiq file can be used as a template specifying multiple variables when used with different ShowFriendlyPages calls, as described in the rules for substitution markers in the QIQ file.
It may not always be convenient to fire off the popup action from the actual context we want to create/edit variables within. An example of this is when we have (say) lots of drawers in separate sections, and we want to use the same QIQ popup for each section, with the user controlling which section to edit. In this case, we can use the optional fifth parameter which provides the context for editing. It might say "section[drawer1]" or "section[drawer2]" etc.
Here is how this could be done using this alternate context parameter.
From cabinet level (or from some other section or wherever), you can provide a combo to select relevant sections, then specify the same QIQ to be used in whatever context and edit the variables relating to that section. Say you have 5 drawers and they are individual sections called "drawer1" "drawer2"... "drawer5". If you set the variable mydrawer to one of those five names, then you can provide a button to directly edit the properties of that drawer by providing a context parameter Section[mydrawer].
Once you are in the drawer context, it might override a variable called runnerlength, say. If that variable is defined at cabinet (or some containing section level), but not yet at section[mydrawer] level, then the ShowFriendlyPage will work fine, populating controls by getting values from the parent. HOWEVER, the moment you change one of those values, it will create a local section level override variable with the new value. All the other drawers will keep behaving with the cabinet level runnerlength, but this one drawer will now have a different length.
In the above example, it is important to note that the QIQ may be providing overrides for some default behaviour, and so the variables for each drawer may not even be defined. That is, the formulas in the drawer sections might be all using the same parent level variables as defaults to start with. In this case, some variables might not be initially defined in the popup context. This does not matter as the evaluator still pulls values from parent and grandparent contexts etc, as required. This displays in the ShowFriendlyPages popup initially with just the default values from the parent sections. But when you edit any of these values, a newly created variable of the same name will be created at the active (drawer1 etc) level, and this will immediately override the default behaviour.
If the user does not change a value when the popup ShowFriendlyPages dialog is displayed, then no override variable will be created. That is, if there is no local variable (in the current context) before viewing the friendly pages, and no changes are made, then there will continue to be no override variable after dismissing the ShowFriendlyPages dialog, with either an OK or a Cancel. This avoids proliferation of unnecessary variables per section when the section is just trying to use the default behaviour.
Most of the parameters in ShowFriendlyPages are optional. The simplest calling method uses just one parameter, which is the name of the QIQ file:
... which pops up a friendly page dialog using the qiqfilename supplied, and a default title bar based on this name. The qiqfilename, if not fully specified, defaults to the current Library folder and default extension is .qiq.
If we use two parameters, we can also explicitly provide a title for the dialog, like this:
ShowFriendlyPages(title,qiqfilename)
Adding a third parameter lets us provide a simple substitution array directly in the calling parameters, like this:
ShowFRIENDLYPAGES(title,qiqfilename,substitutions)
This replaces numbered markers in the QIQ file with corresponding elements in the substitution array. The numbered markers look like this: ~1~, ~2~, ~3~ and so on.
Eg, SHOWFRIENDLYPAGES("Materials Selection","myqiqname",["carcass","laminate"])
...replaces ~1~ by carcass and ~2~ by laminate.
If there is only one substitution to do, then you can drop the square brackets for the array syntax and just use a string.
Eg. SHOWFRIENDLYPAGES("Materials Selection","myqiqname","carcass")
...replaces ~1~ by carcass wherever it appears in the QIQ.
Adding a fourth parameter provides a bit more flexibility with the substitutions, allowing you to use named parameters, like ~SECTION~.
For example SHOWFRIENDLYPAGES(title,qiqfilename,substitutions,names)
...replaces named markers in the QIQ file that match elements in the names array with corresponding elements in the substitution array.
For example SHOWFRIENDLYPAGES("Materials Selection","myqiqname", ["carcass","laminate"],["SECTION","MATERIAL"])
If there is only one substitution to do, again, you can drop the square brackets for the array and just use a string for each of the 3rd and 4th parameters.
For example SHOWFRIENDLYPAGES("Materials Selection","myqiqname", "carcass","SECTION")
Finally, there is an optional fifth parameter which lets you provide a context for the variables that will be edited by this ShowFriendlyPages popup. Context can be specified as any valid context such as "extn.section[box]".
For example SHOWFRIENDLYPAGES(title,qiqfilename,substitutions,names,context)
...does a friendly page popup working in specified context, as described in Alternate Context
