When creating new database template, there will be times where you want to add custom fields in specific locations with them. This guide covers how custom fields are used within your own custom database templates, examples on how to enter these, and a brief explaination of each field display type.
In order to understand how custom fields are used within templates, it is important to understand the items in which will be used within your template code.
When creating a custom field with a view to displaying in your own templates, the following items will be of note when you are creating these
Display Methods
-
Template Key - This is how you will reference your field within your template. When creating fields, try to stick to a convention of naming which is relevant to what the field contains, and the database if you have more than one.
So for example I may have 'bugs_area_text' which would be clear to me in my instance, that it's the bugs database, the field which shows the area where the bug is, and it's a text field. Sticking to some sort of convention may help make your templates easier to read as you are developing them.
-
Listing View Format - This is the format used when referencing the listing view, which will be discussed below.
-
Display View Format - This is the format used when referencing the display view, which will be discussed below. Note also that display is the default view to be used if no other is specified.
- Display - In addition to the Display View Format, there is also a specifier for where this should be placed. You can reference each of these options specifically in your template code.
Any field you have created can be used within your database templates. This can be done using the following code
{$record->customFieldDisplayByKey('your_template_key', 'viewtype')|raw}
The template key parameter would be whatever you have entered in the 'Template Key' field, in the display tab of your custom field.
The view type parameter is what you would use in order to specify what format you are using, which would depend on which of the options from your display tab in your custom field you wish to show. The view types that can be used are as follows
-
listing - This will show the value as per any listing badge preferences as set up on your custom field. This is usually used within a record list.
-
display/display_top/display_bottom - Each of these show the value as per any display value set up in your custom field. Display on its own will just show the format, however you can use display top and bottom to display based on which of these items is selected within that field for the display section.
-
thumbs - returns an array of \IPS\File objects . Returned only with image types, where thumbnail creation is selected.
-
upload- returns an array of \IPS\File objects . Returned only with upload field type.
-
raw - this will show the value as store in the database, unless there are muliple upload (returned as an array of URLs) or they are a Reciprocal field type (returned as an array of record objects)
- processed - this will show the raw value as specified above, however is also passed through the form helper
Adding |raw will mean that the value will not be escaped. For some items which specifically contain URLs this may be desirable. For example returning a thumbnail, or a youtube item. However if using for items such as plain text, please be aware that you are allowing raw unescaped text to be added to the page.
For this example, I have created a field named "Sub Title". First of all I have set my field up. For this item I am aiming to add a subtitle to the record, shown below.
Template Key
I'm happy with one of the preset display options, do have selected the one below
Display View
I now need to edit my record template, and add in the line where I require it to show up. In this case, just below the title
Template Edit
Note that the syntax used here includes the |raw at the end. This is because what will be returned will the the HTML from the standard display format I have chosen, and I dont wish for this to be escaped.
{$record->customFieldDisplayByKey('sub_title', 'display')|raw}
Result
Report Guide