Advanced Block Development: Part Three
Andrew introduces how to include the file manager to your blocks.
Adding the File Manager is not a hard thing to do. Simply adding these lines of code will create an interface to use concrete5's file manager.
$al = Loader::helper('concrete/asset_library'); echo $al->file('optional-ID', 'fID', t('Pick a file.'), $bf, $args);
This is the most basic use of the asset library helper to bring up the file manager. The arguments are as follows:
- $id: a string that will be used to create an id for the HTML elements. Can be anything.
- $postname: This is how you will reference the file ID for saving in the block's controller.
- $chooseText: Text displayed to the user for choosing their file.
- $bf: An optional file object. Generally you want this to be the file the block is already using. Check out the image block's form.php for an example.
- $args: These are essentially a set of attributes, as a keyed array of the attribute's handle and the attribute's value.
The last option is the most complex since it is dealing with concrete5's attribute system. To get a basic understanding of this is used in context, check out how the helper uses the fType attribute to filter out files in its various functions, and then again how the image block's form.php view extends this by using
minWidth and so on.
Also worth noting is that although most helpers are going to be at concrete/core/helpers/ all of the concrete/ helpers are in concrete/helpers/concrete/, which puts the asset library at concrete/helpers/concrete/asset_library.php. The concrete helpers are more likely to change and are not as general use, so they are not part of the override structure.
Andrew goes on to mention how the slideshow block can load multiple images at once. This can all be seen in the slideshow block. Basically, its form_setup_html.php view includes a skeleton of what each image row should look like which is stored as image_row_include.php.
Rather than loading the asset library helper, the slideshow block just uses
ccm_launchFileManager('&fType=' + ccmi18n_filemanager.FTYPE_IMAGE);
To improve the performance of your block's you might want to tweak some of these options. These options are simple booleans. Here are Andy's recommendations:
- $btCacheBlockRecord : Should be safe in most cases, this will lighten the load on your database.
- $btCacheBlockOutput : This caches what is actually rendered by the block. Basically, when this option is set, the block will always load whatever was entered after the last "save". This is also generally safe to use. However, in situations where you are relying on visitor contribution or other dynamic content, the cached output will be wrong.
- $btCacheBlockOutputOnPost : This option will cache a block, even when the page it is on is recieving a post request. So you would want this disabled for something that needs input to change, but you can set this to true for something that does not.
- $btCacheBlockOutputForRegisteredUsers : Unregistered users will never have complicated permissions that might influence what they can or can not see, so some things are cacheable for them, but not registered users. If your block has nothing to do with permissions, this can be true.
The "on post" and "registered user" cache options have no effect if
btCacheBlockOutput is not set to true.
The last option is
btCacheBlockOutputLifeTime, which controls how long to wait before clearing out the cached version. Usually this is set to the system default, which is how long your caching layer is configured to cache on the server generally. If you want, you can define this value yourself, for example if it's something that might change dynamically, but not often enough that it needs to be checked every time the block is loaded.