This page will describe a number of things not documented in the interface, due to lack of space or otherwise.
Thread Filtering
XThreads offers a {$filters_set}
array variable on the forumdisplay page when thread filters are used. This section describes this array.
The general format to use in templates is something like this: {$filters_set['key']['var']}
. key refers to the filter; for example, if you've enabled filtering on a thread field having a key of "myfield", the corresponding key is myfield. As for var, the following are available:
- value: value of selected filter, for example, if the user is filtering "myfield" by "label_a", sticking
{$filters_set['myfield']['value']}
in the appropriate template will displaylabel_a
. Note, if an array of filters have been used, this will contain all values selected, separated by commas. - urlarg: URL parameter with selected filter, for example,
filtertf_myfield=label_a
- urlarga: same as above, but with a preceeding ampersand, eg
&filtertf_myfield=label_a
- urlargq: same as above, but with a preceeding question mark, eg
?filtertf_myfield=label_a
- forminput: like urlarg, but as a hidden form parameter, eg
<input type="hidden" name="filtertf_myfield" value="label_a" />
- selected: an array, containing the selected value as a key and
selected="selected"
as the value (that's a preceeding space before 'selected' there). Example usage - the appropriate option in the listbox will be selected depending on what filter is being used:<select name="filtertf_myfield">
<option value="label_a"{$filters_set['myfield']['selected']['label_a']}>label_a</option>
<option value="label_b"{$filters_set['myfield']['selected']['label_b']}>label_b</option>
...
</select> - checked: same as above, but sets value to
checked="checked"
- active: same as above, but sets value to
filtertf_active
(may be useful for applying a CSS class) - nullselected: if filter is NOT set, will set to
selected="selected"
, otherwise will be blank - nullchecked: if filter is NOT set, will set to
checked="checked"
, otherwise will be blank - nullactive: if filter is NOT set, will set to
filtertf_active
, otherwise will be blank - hiddencss: puts hidden CSS if filter is set, is blank otherwise; in other words, if this filter is being used at all, this will be set to
display: none;
- visiblecss: opposite of the above; set to
display: none;
if filter is NOT set, or blank otherwise
There are also some special values for key, these are:
- __xt_uid, __xt_lastposteruid, __xt_prefix and __xt_icon: for filtering by uid, lastposteruid, prefix and icon, respectively
- __all: aggregation of all thread field filters, and uid/lastposteruid/prefix/icon filters (does not include inline search); this doesn't support selected, checked and active as var
- __search: for inline forum searching, if enabled
Display Format Fields
The Display Format, Display Item Format, Blank Replacement Value, Unviewable Value and replacement values for Formatting Map List have fairly complex display formatting abilities - this section will try to explain how it works.
Special Tokens
{VALUE}
- represents the value; not available for Blank Replacement Value as the value is blank here{RAWVALUE}
- as above, but without the sanitisation step (step 5 below) - use with caution! Only available in Display Item Format and Display Format if multiple values are not allowed.{VALUE$1}
,{VALUE$2}
,{VALUE$3}
etc - represents captured value components if a capturing Text Mask Filter is defined{RAWVALUE$1}
,{RAWVALUE$2}
,{RAWVALUE$3}
etc - as above, but values not gone through the sanitiser- Variables - similar to how they work in MyBB templates, eg
{$mybb->user['username']}
; note, these must be surrounded by curly braces as in the preceeding example. Variables are always in the global scope. - Conditionals - see the following section
Conditionals
XThreads supports conditionals in many fields, which are in the same syntax as the Template Conditionals plugin. There are a few differences/notes with the plugin however:
<template ...>
calls are not allowed{VALUE}
and similar tokens above are treated as quoted string values, eg<?='This is '.{VALUE}?>
is valid syntax- All variables are auto-global'd - no need to do this explicitly. Note that, because of this, it won't work correctly with some PHP syntax, such as
$$variable
- The two functions added in v1.4 of Template Conditionals are named
xthreads_phptpl_eval_expr
andxthreads_phptpl_eval_text
PHP support is also available, but only if the PHP in Templates plugin is installed and activated (and/or appropriate setting set in cache/xthreads.php); accepts PHP within <?php ... ?>
tags, similar to how the plugin works.
Parse Process
- If the value is blank, the Blank Replacement Value will be displayed
- If the user is in a group which cannot view the value, the process will continue, however Unviewable Value will be used in place of Display Format
- At this point, file thread fields will go off and do its own thing and pass finally through Display Format; other thread fields continue
- If the value matches one defined in the Formatting Value List, the defined replacement will be used here and the following step will be skipped
- The value will be sanitised according to the Display Parsing option chosen, at this point (eg, MyCode parsed)
- If a capturing Text Mask Filter is used, components are captured (from the raw input, not the output of above step) and sent through the sanitiser (as above)
- If multiple values are supported, the above goes into Display Item Format, and the above two steps are repeated for each value. Once done, all these values are aggregated together, separated by the Multiple Value Delimiter
- Finally, the value goes into the Display Format, for display
Image Filtering Chains
XThreads allows you to define image filtering/processing chains, which specify how thumbnails are created. What's described below is applicable only to file type thread fields, which only accept images.
Each filter is like a function and thus must have brackets after the name even if no parameters are passed. Separate filters using ->
- example resize(100,100)->brightness(50)->grayscale()
PHP expressions are supported in arguments (subject to the same limitations as conditionals)
Image Filters
downscale((int) width, (int) height)
Scale down image so that its width and height are less than or equal to width and height. If the image is already smaller, no scaling is performedupscale((int) width, (int) height)
Scale up image so that its width and height are greater than or equal to width and height. If the image is already larger, no scaling is performedscale((int) width, (int) height)
Alias forscale_max
scale_max((int) width, (int) height)
Scale image so that it just fits within the bounds of width and height. For example,scale_max(120,120)
will scale a 90x45 image to 120x60, or a 800x600 image to 120x90scale_min((int) width, (int) height)
Scale image so that the bounds of width and height just fits within the image. For example,scale_min(120,120)
will scale a 90x45 image to 240x120, or a 800x600 image to 160x120resize((int) width, (int) height)
Resize image to widthxheight without maintaining aspect ratiocrop((int) width, (int) height)
Alias forcrop_cm
crop_lt((int) width, (int) height[, (int) x-offset[, (int) y-offset]])
Crop image anchored from left-top corner (offset by specified x/y coordinates, if given) to widthxheight. Negative values for any arguments are offset by the current width/height of the image, so a width of -10 means 'crop 10 pixels off the right'.crop_ct((int) width, (int) height[, (int) y-offset])
Crop image anchored from center-top side.crop_rt((int) width, (int) height[, (int) x-offset[, (int) y-offset]])
Crop image anchored from right-top cornercrop_lm((int) width, (int) height[, (int) x-offset])
Crop image anchored from left-middle sidecrop_cm((int) width, (int) height)
Crop image anchored from the centrecrop_rm((int) width, (int) height[, (int) x-offset])
Crop image anchored from right-middle sidecrop_lb((int) width, (int) height[, (int) x-offset[, (int) y-offset]])
Crop image anchored from left-bottom cornercrop_cb((int) width, (int) height[, (int) y-offset])
Crop image anchored from center-bottom side.crop_rb((int) width, (int) height[, (int) x-offset[, (int) y-offset]])
Crop image anchored from right-bottom cornercopy((image) from[, (int) x[, (int) y]])
Copy image from onto current image, where the top-left corner of from is placed at the specified x/y coordinates of the current image. Negative values of x/y will offset the right/bottom corner of the from image with the right/bottom corner of the current image.copy_onto((image) to[, (int) x[, (int) y]])
Similar tocopy
, except uses the to image as a base where the current image is copied onto.negate()
Invert image coloursgrayscale()
Desaturate imagebrightness((int) value)
Increase brightness by value (-255 to +255, 0 = no change)contrast((int) value)
Decrease contrast by value (-100 to +100, 0 = no change)colorize((int) red, (int) green, (int) blue, (int) alpha)
Increase each pixel's RGBA colour components by specified values (-255 to +255, 0 = no change). alpha parameter ignored on PHP < 5.2.5edgedetect()
Highlight edgesemboss()
Embosses the imagegaussian_blur()
Apply gaussian blur to imageselective_blur()
Blur the imagemean_removal()
Sharpen the image using mean removalsmooth((float) strength)
Smooth the image, with specified strengthpixelate((float) blocksize[, (bool) advancedmode])
Pixelate image with specified blocksize. Requires PHP 5.3 or laterjpeg([(colour) transparent[, (int) quality]])
Indicate to save the image as a JPEG. Transparent colours will be saved as transparent. quality indicates the quality/size tradeoff when saving (0 = smallest file, lowest quality, 100 = largest file, best quality, default = 75). If you change the file type using this, note that XThreads may not send the correct MIME type for the thumbnail (although most browsers should automatically detect this and not be affected).png([(int) compression])
Indicate to save the image as a PNG. compression specifies how much compression to apply, where 0 = no compression, 9 = maximum compression, 6 = usually default level. If you change the file type using this, note that XThreads may not send the correct MIME type for the thumbnail (although most browsers should automatically detect this and not be affected).loadimage((string) filename)
Discards current image and loads image specified by filename, affecting all image variables described below - note that the forum root directory will be prepended to the filename and '..' is not allowed in the pathblank((int) width, (int) height[, (colour) background])
Discards current image and creates a blank canvas of specified width and height, filled with background; affects all images variables described below
Image Variables
{WIDTH}
: Current width of the image{HEIGHT}
: Current height of the image{OWIDTH}
: Original width of the image (from lastload
orblank
call){OHEIGHT}
: Original height of the image{TYPE}
: String representing type of image; can be'PNG'
,'JPEG'
,'GIF'
,'WBMP'
or'XBM'
{FILENAME}
: Filename of original image
Notes
- By default, thumbnails are saved in PNG format unless it was a JPEG, in which case it still saves in JPEG format.
- The 'simple' thumbnail generation is almost identical to a
downscale
call, for example, specifying thumbnail generation to be 160x120 is almost equalent to specifying160x120=downscale(160,120)
- Using hawt pink (#FF0080) as an example, colours can be specified using:
- HTML-esque string:
'RRGGBBAA'
eg'FF0080'
- Integer:
0xAABBGGRR
eg0x8000FF
- Array:
array(RR, GG, BB, AA)
egarray(255, 0, 128)
- HTML-esque string:
- The function
newXTImg()
can be used to create a new image. You should always callblank()
orloadimage()
after creating a new image to specify exactly what to create
Examples
- Make a fixed 100x100 image, preserving aspect ratio and cropping if necessary
scale_min(100,100)->crop(100,100)
- Scale down to 200x200 (or smaller) and add a watermark in the bottom-left corner (loaded from forum_root/images/logo.gif) - the watermark will be slightly transparent when blended (if PHP 5.2.5 or newer)
scale_max(200,200)->copy(newXTImg()->loadimage('images/logo.gif')->scale(50,50)->colorize(0,0,0,48),2,-2)
- Scale down to 200x200 (or smaller) and put a 2 pixel red border around the image (will also make the background red if the image contains transparency)
scale_max(200,200)->copy_onto(newXTImg()->blank({WIDTH}+4, {HEIGHT}+4, '#FF0000'),2,2)
Additional Custom Thread Field Variables
In addition to the {$GLOBALS['threadfields']['key']}
variable (which displays the value of the thread field), there are other values which can be displayed via the additional variable, {$GLOBALS['threadfields_x']['key']['valuename']}
variable, where valuename can be one of the following:
- title - displays the title given to the thread field
- desc - displays the description given to the thread field
- num_values - displays the number of values stored in this thread - will always be
1
for non-multivalued fields, or0
if no value entered - num_values_friendly - formatted version of the above
- value - reference back to
$threadfields['key']
, unless the field is a multivalued field, in which case, this is an array of each individual value
For multivalued file fields: this directly references the value item, whilst items stores an array of the full attachment info - in other words,{$GLOBALS['threadfields_x']['key']['value'][0]}
is the same as{$GLOBALS['threadfields_x']['key']['items'][0]['value']}
for a multivalued file field - raw_value - raw value of the thread field taken directly from the database
Additional Template Variables
XThreads adds some variables which can be used in templates for convenience.
- Thread/forum URL variables through
{$forumurl}
,{$forumurl_q}
,{$threadurl}
and{$threadurl_q}
(the_q
variants append a?
or&
depending on the context of the URL). Example:<a href="{$forumurl_q}filtertf_myfield=something">filter by something</a>
- Thread start date is evaluated in a variable through
{$thread['threaddate']}
and{$thread['threadtime']}
; available in forumdisplay/showthread/search
Other
- Admins can add XThreads attachments by placing the file in the uploads/xthreads_ul/admindrop folder (and not a subfolder of that), and specify the filename (through URL box) using file:// prefix. For example, if an admin tells the system to retrieve the URL file://bigfile.iso, XThreads will move the file in uploads/xthreads_ul/admindrop/bigfile.iso to where xtattachments are stored.
- You can force xthreads_attach.php to download a file (as opposed to viewing the file in the browser) by appending ?download=1 (or &download=1 if you're using query strings) to the URL
- A number of "internal variables" can be modified by editing the cache/xthreads.php file. XThreads needs to be installed for this file to exist. Note that this file is auto-generated and may be overwritten during an upgrade, however values will be retained.
- Template modifications performed by XThreads can be redone (ie, after you install a new theme) by deactivating and reactivating the plugin (without un/installing)
- XThreads can sort any non-textarea custom thread field in forumdisplay. This reuses MyBB's sorting system - just that the URL parameter is a little different.
To sort by a thread field, prefix its key withtf_
, for example, forumdisplay.php?fid=2&sortby=tf_myfield will sort the threads by myfield. File input fields are a bit different, they need to be prefixed withtfa_component_
where component is eitherfilename
,filesize
,uploadtime
,updatetime
ordownloads
.
Although XThreads adds this ability transparently (and to the list of default sort bys in the AdminCP), it is up to you to add appropriate options to the forumdisplay sorter listbox, if you want to.
As this uses MyBB's system, template variables will be the same, eg{$sortsel['tf_myfield']}
will beselected="selected"
if sorting by myfield.
Note that this is not indexed, like MyBB's sorting options aren't, so these custom sorting options can be slow on a large number of threads. - XThreads can filter forumdisplay by thread starter, last poster, thread icon and thread prefix (MyBB 1.6 only); to do this, supply filterxt_field=value to the URL, where field is either uid, lastposteruid, icon, prefix. These also support the special numeric filtering operands (see Filtering Mode on the add/edit custom thread field page for details). For example, forumdisplay.php?fid=2&filterxt_uid=1,2,5
- In a thread field's Display Format Fields (includes Display Format, Display Item Format, Blank Replacement Value, Unviewable Value and replacement values for Formatting Map List), references to other thread fields are possible, only if the Display Order is set lower than the thread field making the reference (for those with the same Display Order, whether or not it'll work will depend on your luck). For example, if we have two thread fields, the first having a Display Order of 1 and the second having a Display Format of 2, then this second field can refer to the first field via
{$GLOBALS['threadfields']['key']}
in any of its Display Format Fields (where key is the Key of the first thread field, which also isn't a File input field). - The Value List for Listbox, Option Buttons and Checkboxes input types can have an associated "input display label" - that is, a separate value and label. This is achieved through the
{|}
separator, for example:with a Listbox input would give something like:1{|}Value 1
2{|}A second value
5{|}<span style="color: red;">Some other value</span>Additional notes:<select>
<option value="1">Value 1</option>
<option value="2">A second value</option>
<option value="5" style="color: red;">Some other value</option>
</select>- XThreads has the special ability with Listbox inputs to use CSS for items if it is surrounded by a
<span>
tag with a singlestyle
property (like above example; for non-Listbox inputs, HTML is accepted anyway) - This mapping does not affect the output display, so you may wish to use this in conjunction with the Formatting Map List option
- You can override the label of the (Not Set) item by not supplying a value before the separator, eg
{|}Blank
- XThreads has the special ability with Listbox inputs to use CSS for items if it is surrounded by a
- Custom input HTML for file fields styling - some 'hidden' helpers to allow you to style it more easily are included: (note that these may change)
- xta_removed class is added to the
.xta_file
element (whatever element has the class xta_file) if the Removed checkbox is ticked - the default strike-out styling can be removed by simply deleting the xta_file_link class - xta_movable class is added to the
.xta_file
element if the file can be rearranged (two or more files attached to the field uploaded) - The
.xta_file_list
element accepts a JSON list of options in the data-sortoptions property. These options get sent to the dragdrop handler for file rearranging - a list of options can be found in jscripts/dragdrop.js. Example:<div class="xta_file_list" data-sortoptions="{scrollSpeed: 10, scrollSensitivity: 25}">list of files here</div>
- xta_removed class is added to the
XThreads Additions
Just a list of the stuff XThreads adds:
AdminCP UI Additions
- Custom Thread Fields section under the Configuration tab - this is where you can add custom thread fields
- XThreads Options section under forum add/edit - this allows you to customise various XThreads options on a per forum basis; XThreads also adds to the list of sorting options, if you have sortable thread fields assigned to the forum
- Modify Custom Thread Fields textbox under add/edit Moderator Tools - this allows moderator tools to modify custom thread fields; note that values here are NOT validated and permissions are NOT checked!
- Rebuild
threadfields
cache under Cache Manager for rebuilding XThreads caches - Rebuild XThreads Attachment Thumbnails under Recount & Rebuild for rebuilding thumbnails associated with uploaded XThreads images (also required if you change thumbnail sizes)
- Prune XThreads Orphaned Attachments task, which periodically cleans up orphaned XThreads attachments (as well as performs deferred MD5 hashing), similar to MyBB's Find Orphaned Attachments
- Folder chmod check under Tools & Maintenance, System Health
Modified Templates
- editpost and newthread - adds
{$extra_threadfields}
to the template, which just displays any added thread fields - showthread
- insert
{$first_post}
before{$posts}
; in XThreads, it's possible to customise the first post differently from other posts - insert
{$threadfields_display}
before{$classic_header}
(MyBB 1.4/1.6) or<tr> <td id="posts_container">
(MyBB 1.8) - this is for displaying thread fields on show thread (note: displays on every page)
- insert
- forumdisplay_threadlist
- insert
{$nullthreads}
after{$threads}
; this is just for display "null threads" if thread grouping is used - insert
{$sort_by_prefix}
before the first option in the sorter listbox - this is to give the option to sort threads by thread prefix - from the above, some other sorting options are added below the Sort By: Views option in the listbox
- insert
- forumdisplay_threadlist_sortrating - similar to the above, inserts a sort by number of ratings option to the sorter listbox
Added Templates
- editpost_first - allows you to have a different editpost template for editing the first post of a thread; defaults to
{$editpost}
which uses the default editpost template - forumdisplay_group_sep and forumdisplay_thread_null - for use with thread grouping (is explained if you enable thread grouping); defaults to nothing
- showthread_noreplies - displayed in the
{$posts}
variable for showthread only if the thread has no replies and a postbit_first* template is being used; see the comment in the template for more information - forumdisplay_searchforum_inline - inline forum searching - you don't need to bother with this unless you want to...
- post_threadfields_inputrow - how extra fields are displayed in newthread/editpost (of first post) - don't need to worry about this one either
- showthread_threadfields and showthread_threadfield_row - how extra fields are displayed in showthread; the latter is for each thread field, whereas the former is just a wrapper around all thread fields
Although not an added template, you can create postbit_first* templates to override the various postbit* templates for the first post of a thread.