addedValues Plugin
...Powerful Free! Database Expansion for Manila
Get tropes here!
Click to see internals
Report bug
American Civil Liberties Union of New Jersey
|
Defining Variables
A variable is the name of field within one of the entities that addedValues knows about - Manila messages, Gems, member records or addedValues shortcuts, globals, user transactions or other specialised addedValues objects. Manila supports many variables already, such as the body (text) and subject of a message, the postTime of a message and so on. In the metadata Plugin, variables were called metatypes.
You can add new variables to each message (gem, member, shortcut) by defining them on the addedValues variables home page and then refining the definition by selecting it from the multiple choice box and clicking the edit button. Click on the images below for a full size illustration
 |
 |
| Variables Home | Variables Detail |
|---|
When a variable is first defined, addedValues sets its attributes to default values, some of which can be changed as a site preference. For many purposes, the defaults will do; when it won't consult the menu items under Variables (see left menu) for the meaning of the attributes.
Adding a Variable
To add a variable, enter a name, select from the Applies To menu and click add. If the name is valid, a variable is created with default values and it appears in the multiple choice box. Valid identifiers begin with a letter, and are composed of letters and digits. Internally, addedValues uses names that are the concatenation of the values of attribute Of, group and the supplied identifier. The composite names must be unique, and for messages, gems and member variables each variable identifer must differ from all others in the same value of attributeOf, regardles of group.
Another preference determines default values of some of the properties of new variables. You can also clone an existing variable, by seelcting the original and entering a name for the copy.
Modifying Variables.
You may edit any number of variables simultaneously, by selecting them from the multiple choice box and clicking Edit. The response is the Variable Detail page shown above. On this page, you make changes and apply them by clicking Modify. From there, to return to the Variables Main page, click Done. While editing a variable, you have "custody" of the variable and no other editor is allowed to make changes. The Done button relaxes that that control.On the Variables Detail page, most rows have a link to specific help pages for the corresponding variable attribute.
When you create or change a variable, addedValues might have to examine every entity of that type (message, member) to be sure there is no conflict, to change the representation of an existing value, or to gather the values into an index. If the number of candidates is large, this process can take some time. Because values are sometimes manipulated, there is a possibility of errors occurring, these are reported with a link to help correct the offending message (member, GEM, etc.) However, if 10 errors are seen the process terminates and it is prefixed with a question mark in the variables list. When the variable is edited the variable detail pages will show which routines failed, and offer a button to Retry the failing action. Error messages from a retry attempt are the same as displayed by the original and they will link to the message where the error occurred. Fixing the errors clears the question mark flag and removes the Retry button.
Modifying a variable might invalidate the choice of renderings made for each form that includes the variable. addedValues allows such changes but it notes such potential problems and provides a link to each affected forms detail page.
Deleting Variables.
To delete one or more variables, select them from the multiple selection box ands click the delete button.
Variables are protected against deletion if any use is made of them in the website. AddedValues lists all the current places each variable is used, and links to a URL where you might modify that usage.
Method Scripts
Methods are the scripts generated for each variable to handle getting and saving values, validation etc. For indexed variables there are additional scripts which support search. These scripts are built from templates at variable define time and thereafter when modifications require. If the method script templates are changed, either to fix bugs or provide enhancements, these generated scripts become obsolete.
As a rule of thumb it is best to have the latest versions of method scripts, but their action is so fundamental that automatic regeneration was deemed. This has led to additional support work because bugs fixed in methods are not propagated until the site variables are modified. to overcome this, addedValues checks for obsolescent methods at enable time and remembers that status for each variable until the next enable or until editing the variable regenerates the methods. This status is visible because variables with one or more obsolete methods will appear with a line-through in the variables menu in modern browsers, and with a prompt to regenerate on the edit page. If you see obsolescent varibales, but your site is working satisfactorily there is no immediate need to regenerate; but you should plan to do it at a convenient early date.
A Manila server administrator who has installed controlpanelAddins from bayly.root can use a new applyTo process called addedValuesMethodsObsolete to do this from the administration website (you will need to update bayly.root to obtain this enhancement).Bugz reports for addedValues, from websites that have obsolescent variables will not be looked on favourably.
Indexed Variables.
A search is where you ask addedValues a question such as "List all messages with a postTime before a certain date" . Or, "list all members with City field = New York". In these questions postTime and City are message and member variables, which means that each message (member) has its own value of them. Searching is identifying which messages (members) satisfy a condition. To answer questions efficiently, addedValues requires that you enable Indexing for the variables used in these questions. Once enabled, indexing looks after itself, but you can monitor and control the indices by clicking the Index button.
Defining Builtins
Builtins are variables that Manila creates and updates according to its own lopgic. AddedValues can read values of builtins variables, but will not recognise their names until explicitly asked to. Once defined, builtin Variables can be indexed, and used as other variables, except addedValues never changes the values of Manila builtin variables. In advanced browsers builtins show in green in the multibox listing variables, unles they are indexed, in which case they are red. The values will continue to exists regardless of whether addedValues recognises them or not.
Displaying Builtins
Because there are a lot of builtins, it is sometimes convenient to not see these names in the multiple selection box. These buttons control whether they are visible or hidden.
Globals.
Globals are properties of website, there is ony one value for the whole website. They are useful for storing values which are not constant and whose value can be used in the website with a simple macro call. For example, a company address, a url of an associated website. They can also act as lookup tables, useful in a multi-lingual websites or to look up the full names of state codes (NY = New York). And, they can be used as a repository for patterns used to validate values of other variables.addedValues creates some standard globals in every website - USstates which is a lookup table, and USZipCode and USPhoneNumber whose values are regular expressions, which can be used to require variable values to match that regular expression. It also creates a special variable - addedValues.logo - which contains an image link to the addedValue website and which is appended to every form created with addedValues on servers with non registered copies of the plugin.