Configuring Custom Fields in JEvents Club Addon
With this new addon you will be able to create custom fields for your event descriptions and include these fields in your event filters too.
You will require the latest build of JEvents 2.0.0+ for this plugin to work.
Install, CONFIGURE and enable the plugin. You must configure the plugin to create the required database table.
At the moment this plugin is configured via an xml file - I may (when I have the time) write a configuration component that will allow you do the configuration dynamically. Having said this the format of the XML file is quite simple.
Configuring your custom fields
1. Copy the file plugins/jevents/customfields/templates/fieldssample16.xml to plugins/jevents/customfields/templates/fields.xml. If you are using Joomla 1.5 then copy the fieldssample.xml file instead.
2. Edit the file plugins/jevents/customfields/templates/fields.xml to create the custom fields you require. The next section describes the format of the file.
Params Tags & Tabbed Editing of Events
You can configure your custom fields to appear on separate tabs when editing events. To do this put them into separate <params> tag groups using the group attribute to set the tab name on the event editing screen. The sample files illustrate this process.
Each field is configured as a "param" tag. For types with no options (jevrtext, jevrtextarea and jevrboolean)
these tags are on one line and take the form
<param name="field1" type="jevrtext" default="default text" size="20" maxlength="100" required="1" searchable="1" label="Text Field" description="Text field tooltip" allowoverride="0" filter="1" access="0"/>
Note that you MUST have the /> at the end of the line.
For fields with options the tags have option tags within them e.g.
<param name="field1" type="jevrlist" default="-1" label="Select List" required="1" description="Select List tool tip" allowoverride="1" filter="1" multifilter="1" filtersize="3" access="0">
<!-- select lists MUST have numeric values//-->
<option value="-1">Select One</option>
<option value="4" archive="1">Probably</option>
You can have as many fields as you want - but they must all have a unique name (it must not start a number and have no spaces, quotation marks or other special characters). The name is only used internally so a numerically incrementing sequence like there is in the sample file is ideal (e.g. field1, field2, field3 etc.).
The type of the field is held in the "type" attribute value. The choices are:
Select List (choose one item from dropdown) = jevrlist
Text Box = jevrtext
Text Area = jevrtextarea
Boolean (Yes/No) = jevrboolean
Radio boxes = jevrradio
Multiple Select List (choose one or more items from dropdown) = jevrmultilist
Comment/Instruction Text = jevrinstruction
URL field (must include the http:// part) = jevrurl
File or Image – if you have the standardised images and files addon then you can create custom images and files using the custom fields addon. This is particularily helpful when editing locations and managed people = jevrimage and jevrfile
Calendar/Date with extra attribute of format e.g. format=”%Y-%m-%d” = jevrcalendar
Notes – these are notes that the event creator can create that are not visible on the event detail pages = jevrnotes
Joomla user – outputs a user's name = jevruser
An example of each of these field types is included in the sample file. More types (including custom types) may be added later.
Taking the generic attributes you can use in turn:
Default Values (defaultvalue)
You can specify a default value for each field in the default attribute. This is the value that is displayed/selected when you first create/edit an event. For the jevrlist, jevrboolean, jevrradio and jevrmultilist types if the default value matches the value of one of your options that that is the option that is initially selected.
The label attribute is the label that appears alongside the "input" area. This label is also used in the filter if you enable the filter in the jevents filter module. Note that is you set the hiddenvalue attribute then this label is also hidden when the field has the default/empty value (see below).
The description attribute is the tooltip that appears on top of the label when you edit an event. No quotation marks are allowed in this attribute.
Allow Override (allowoeverride)
If you specify allowoverride="0" then when you edit a repeat this custom field cannot be altered. If you specify allowoverride="1" then when you edit an event repeat this custom field can be customised for the specific repeat.
If you set filter="1" then this field will appear in the jevents filter module (if you enable the filter 'customfield' in the list of filters)
If you set searchable=”1” then this field will be included in the JEvents search and the Joomla search (via the JEvents search plugin).
You can set the reader access level for a field. In Joomla 1.6+ this field is a comma separated list of access levels that are allowed – see your site's access levels for the ids to use but typically in Joomla 1.6/1.7 1=public. In Joomla 1.5 it is a one value field (0=public, 1=registered, 2=special).
Hidden Value (hiddenvalue)
You can set a value for a field so that it is not displayed if this value is set. For example if you only want to show a non-default value to the site visitor. This even works with the jevrinstruction field type so that you can give your event editors instructions that are not visible to the site visitor.
Filtering Menus and Modules (filtermenusandmodules)
You can filter your menu items and modules if you set this attribute to 1 – then when you edit menu items of modules you'll see this custom field in the parameters.
For jevrlist, jevrradio and jevrmultilist types you must specify options for the choices available. These follow the same format as shown earlier
The value field must be numeric and unique within the field.
Options that are no longer valid
Over time some of your options may become out of date - e.g a price range or a conference room may no longer be available. If you set the archive attribute for an option to 1 then the field is no longer available as a choice when editing an event but will be 'translated' into human readable form when you view the event detail.
If you simply remove the option then when you view events with the out of date value the value will appear as a blank in the event detail.
Special Attributes for specific types
For the jevrtext field you can specify a size and maxlength value which controls the size of the input box and the maximum length of the allowed input.
For the jevrtextarea field you can specify the number of rows and columns for the field using the rows and cols attributes. Additionally for textarea fields you can allow HTML in the field using the allowhtml=”1” attribute.
Formatting Output in the Layout Editing Tool
If you use the layout editing tool in JEvents to customise the layout of your event detail page or your list views then you can choose the fields you want to display and where from the drop down list of fields next to the editor.
You also have control over what is displayed when the field has no value set or is set to the default.
Filtering Your Lists/Calendar
If you wish to offer add a filter on these fields in your jevents filter module say yes to "make fields available in lists and calendar" in the plugin config and add the filter to the module using the name "customfield".
Don't change your custom field template
Finally - note that you can only have one set of custom fields. If you change your template file then existing custom fields from old templates will be ignored. In future releases I may make it possible to have a choice of custom field templates but this could be complex to implement and would probably have a performance impact.
Enjoy and feed back requested please