valuelists.ini_file[Permalink]valuelists.ini file ReferenceThe valuelists.ini file stores value lists that can be used as vocabularies? for select lists, checkbox groups, and other widgets the provide the user with options to choose from. Each table can have an associated valuelists.ini file located in its table configuration directory?. E.g. for a table named "people" its valuelists.ini file will be stored in "tables/people/valuelists.ini". In addition you can define an application-wide valuelists.ini file in the root of your application's directory, whose valuelists can be used by any table. SyntaxThe valuelists.ini file uses INI file syntax?, where a valuelist is defined by a single section of the INI file. E.g.
This example would define a single valuelist named "colors" with 3 values: r,g, and b (with corresponding labels "Red", "Green", and "Blue). The values (the left of the equals sign) are stored in the database, while the labels are rendered on screen for the user's convenience. Dynamic ValuelistsIt is often advantageous to load valuelists from the database rather than store them directly in the valuelists.ini file. The __sql__ directive allows you to specify an SQL query which selects up to 2 columns (the first is the id and the second, the label). E.g.
Defining Valuelists in a Delegate ClassIf you require more flexibility with the definition of your valuelists than can be gained from the valuelists.ini file, you can define your valuelist using PHP inside a delegate class. Essentially you just create a method that returns an associative array, where the keys are the IDs that are stored in the database, and the values are the values that are visible in the select list. e.g. In either the application delegate class or a table delegate class:
This method is called each time the valuelist is about to be used, so if your method performs any sort of intensive processing, it is a good idea to use a caching scheme so that it only runs the critical code once per request. For example, you could use a static variable as follows:
In this example the database query is only executed once per request to load the $colors variable. The rest of the time it simply loads the cached value from $colors. Performance ConcernsVocabularies (valuelists) are expensive because they need to be loaded completely into memory on every request, hence they should be used judiciously. It is best not to use them if there will be a large number of records in your table, i.e. more than a few hundred max.For example, the lookup widget doesn't create a vocabulary on its field. This can be an annoyance but it is best for efficiency. Often times a lookup widget is used on a field for which there could be a lot of options (thousands or millions). In cases like this, hide the field in both the list and details view, and instead add a grafted field (via fields.ini __sql__ directive) that contains the name of the item instead of the ID, e.g.:
blog comments powered by Disqus
|