Theming with Twitter Bootstrap version 3 - Part 2
In the first article, I explained some of the basics of creating a Twitter Bootstrap 3 (BS3) based theme for Exponent. In this article I'll attempt to alleviate some of the myths or quirks associated with BS3 that may be delaying your move to use this versatile framework for your next custom theme.
Myth #1 - BS3 themes are limited to a one page design - NOT TRUE. While many of the examples found across the internet are limited to one (possibly) long page with a menu of relative links on the page, you can still use the multi-page approach Exponent has used in the past.
Myth #2 - BS3 themes must have the fixed menu (navbar) always displayed at the top of each window - NOT TRUE. Again, while many examples on the internet follow this approach, our sample BS3 theme (bootstrap3theme) provides the option of 'static top' (stays at the top of the content and will scroll out of view), 'fixed bottom' (always displayed at the bottom of the window), or 'fixed top' (always displayed at the top of the window).
Additionally, you may place a banner above the navbar using one of the techniques found here. You are not limited to generic sort of layout. Some example non-Exponent themes can be found at:
Quirk #1 - BS3 navbars are limited to children only (depth of two) and no grandchildren (depth of three or more) - While we support multi-level navbars of any depth, this will NOT work with touch devices (grandchildren are only displayed on 'hover'), nor with the 'collapsed' menu provided on small devices (or small width browser windows)
Quirk #2 - Not everything is 'touch' enabled - Though we're working inside Exponent to alleviate (work-around) this, some elements like the 'carousel' are not 'touch' enabled, in addition to the aforementioned multi-level menus.
Quirk #3 - The site looks slightly different on different sized devices or different browser widths - This is actually a feature, NOT a problem. With BS3 you won't need to develop a complex stylesheet based on media queries, nor have separate mobile subthemes (a feature of Exponent documented here). Since BS3 is 'mobile first' it makes it simpler to desing a web site style and layout which works equally well on large (desktop) or small (smartphone) displays.
Hopefully, this has alleviated some of your fears in pressing forward into the Bootstrap era. I do still plan to write another article/tutorial on converting an open-source/free BS3 theme (from one of the sites listed above) into an Exponent theme, which may be a greater incentive to take the plunge.
Theming with Twitter Bootstrap version 3
Twitter Bootstrap version 3 (BS3) is becoming the user interface framework library of choice for Exponent CMS. Though initially shipped with Exponent v2.3.0, that BS3 implementation was still lacking some refinement, and wasn't fully implemented across the entire user interface. This has been somewhat remedied by the first three patches to v2.3.0, and will be even more-so in the upcoming patch #4 release. In this article I'll attempt to share some of the basics of how to create a Twitter Bootstrap 3 custom theme.
First off, this is NOT an introduction to using Twitter Bootstrap 3 or it's grids, nor understanding what 'mobile first' or 'responsive' means. There are several tutorials on the web including this one. However, we won't avoid those topics as we focus on Exponent CMS theming specifics as they apply to using BS3.
We ship a BS3 sample theme with Exponent v2.3.0 appropriately named 'bootstrap3theme'. Since the release of v2.3.0 we have tweaked this theme (as we said we would), therefore the one being included in v2.3.0 patch #4 has some changes from the one included in the initial release. This article assumes you have access to those sample theme files and can use it as a starting point. Eventually I may also publish a second part to this article to walk you through converting an existing open source BS3 theme template for use as an Exponent template (with the purpose of it being added to the help/doc site).
When you examine the /themes/bootstrap3theme/index.php
default theme template, you'll note several Exponent specific things in the 'head' section with the expTheme::head()
parameters:
- the '
framework
' parameter is set to 'bootstrap3
'. This automatically ensures we are loading the BS3 stylesheets, jQuery script, and 'prefer' the '.bootstrap3' view template variation (which includes any form control or template engine plugin variations) if available.- BS3 scripts are never automatically loaded, but must be requested by the expJavascript::pushToFoot() call or the theme template {script} smarty function using the 'bootstrap=' parameter. This parameter works just like the 'yui3mods' and 'jquery' parameters.
- there are no 'reset' scripts being loaded. The new standard css reset script, 'normalize.css' is automatically loaded by BS3.
- we can optionally load the BS3 'theme' stylesheet which gives a BS2 appearance to BS3 styles, if that setting was saved within the theme configuration.
- though the '
viewport
' parameter is optional since we always set the minimum defaults, it is in this theme template as a point to deviate from. - we account for two (2) less stylesheet compiler variables (
lessvars
) we pull from the theme configuration settings which are mandatory for this theme's .less stylesheets. Most (but not all) stylesheets used with a BS3 theme are in the .less format to allow custom configuration by the end user. For example, the bootstrap3theme allows selecting from the entire set of 'BootSwatch' themes.
Now a short sidebar on some BS3 basic concepts...there is a hierarchy of three (3) basic components for the BS3 grid system: 1) container, 2) row, and 3) column.
- The 'container' class element is mandatory as the highest level element for the grid system. It may NOT be nested as this will create anomalies with display of the page. The classname used for a container element is 'container'.
- The 'row' class element MUST be placed within a 'container' class element, however unlike the container, they may be nested if the nesting occurs within a column. In a basic sense, the row is a placeholder for up to 12 equal-width columns of data. The classname used for a row element is 'row'.
- The 'column' class element MUST be placed within a 'row' class element, and like the container may NOT be nested...except when found within a nested row. The classname for a column element is more complex and composed of at least three (3) parts:
- 'col-' to signify that this is a column
- a designator for the device size the column setting applies to (more or this later). But in our example we'll use the size for a small device or tablet with a max-width of 768 pixels which is 'sm-'. Grid column classes are divided into device sized groupings:
- 'lg' for large devices such as wide-screen monitors (max width 1200 pixels)
- 'md' for medium sized devices such as desktop monitors (max width 992 pixels)
- 'sm' for tablet sized devices
- 'xs' for extra small devices such as phones (max width 640 pixels
- These can be mixed within the same element to provide for a different layout on different devices. E.g., a 4 column wide layout on a desktop would become a 2 column layout on a tablet (2 rows high) or a single column layout (4 rows high) on a smartphone.
- and a digit to set the number of column units of width this column is to fill (from 1 to 12)
- so the simplest column element would be 'col-sm-12' for a single column the entire width of the row. A equal-width 2-column layout would be two elements each with a class of 'col-sm-6' (6 + 6 = 12).
<body>
<div class="container">
<div class="row">
<div class="col-sm-12">
This is a full width column, 12 units wide.
A row with columns could also be placed within this element.
</div>
</div>
</div>
</body>
Therefore, in Exponent, the template theme/subtheme template MUST hold any 'container' element(s). There must NEVER be an element with the class of 'container' found within a view template. A BS3 styled view template can ALWAYS assume it is being loaded within a 'container' and/or a 'column' element. Therefore, the view template should be wrapped within a 'row' element if it will be subdividing its display using the grid system with 'column' elements. The only exception to this is the navigation menu (navbar) which in most examples (including the main BS3 site) is simply wrapped within a 'container' element without rows nor columns.
So within the 'body' section of the /themes/bootstrap3theme/index.php
default theme template, you'll note:
- We have two (2) containers: one for the menu and one for the content
- Within the menu container we have NO rows or columns, so the menu 'template' view can assume it's within a container
- Within the content container we have two rows: one for the actual page content, and one for the page footer area
- Within the actual page content row we have two columns: one for the main content, and one for the sidebar
For the Exponent theming system to work correctly with several UI frameworks, we allow for view templates to also have theme framework variations. These system view templates are denoted by a framework type suffix before the file type. So a system 'showall.tpl' view template with a BS3 variation would be named 'showall.bootstrap3.tpl'. In the absence of a BS3 specific view template, the system would fallback and choose a BS2 template with that framework suffix...in this example if the BS3 variation template did not exist but a BS2 variation template existed named 'showall.bootstrap.tpl, it would be used instead of the base 'showall.tpl' file. Since a custom theme can only use one UI framework, ALL custom template views use the root name without any framework variation.
A note about the /themes/bootstrap3theme/config.php
theme configuration settings file. You MUST include a variable named 'SWATCH' or the .less stylesheet compiler will crash when compiling the BS3 stylesheets.
There MUST always be a file /theme/customthemename/less/variables.less
, even if it's an empty flle. This file is ALWAYS compiled by the bootstrap.less file and overrides any bootstrap 3 and swatch variables as needed. A failure to include this file (it may be empty) WILL result in a .less compiler crash. This file should ONLY contain .less 'variables' as it will also always be compiled as a theme stylesheet and any 'styles' included within in it will also create a theme stylesheet named /css/variables.css.
In summary:
- The theme/subtheme template MUST include the un-nested BS3 'container' element. The theme/subtheme template is the only place the 'container' element will be found. It may optionally contain 'row' elements' so long as it also contains 'column' elements within the 'row'.
- The view template can always assume it's being displayed within a 'container' and/or also a 'column' element.
- Any 'custom' view templates must only have the '.tpl' file type suffix and can NOT contain the '.bootstrap3.tpl' framework variation suffix.
- Failure to follow these guidelines will cause horizontal margin anomalies and prevent theme custom views from loading
jQuery and Exponent....sitting in a tree...
The jQuery javascript library has been integrated into Exponent since v2.2.0 in an effort to help us move away from the YUI library. jQuery is more popular and has many more add-ons/plugins/widgets than does YUI. It is also the javascript library of choice for Twitter Bootstrap. Just like YUI, Exponent easily integrates the use of jQuery into the Exponent framework. Here are some tips on using jQuery with your custom theme or view.
Just like YUI, jQuery is NOT automatically loaded, but only loaded if needed on the page. (However, most every page has some YUI code or widget, therefore it appears that YUI is always loaded). We load jQuery (or YUI) using the {script} Smarty template tag. We can either simply load the base jQuery library script, or we can use it to also load add-ons/plugins and associated stylesheets (again just like the YUI module loader).
The {script} block is used within view templates to delineate a javascript script or javascript code (docs found here). It is recommended that you NOT load your own jQuery library within the view template or theme template, as it will likely conflict with the integrated version. We ship the latest versions with Exponent and load jQuery v2.x in most browsers and v1.x in Internet Explorer versions less than 9 and Firefox version less than 3.7. The simplest approach is to use this to embed a jQuery code snippet:
{script unique="myuniqueid" jquery=1}
{literal}
$(document).ready(function() {
// jQuery code goes here
} );
{/literal}
{/script}
We can also use the tag to load jQuery add-ons/plugins either in the system or within the custom theme. To load an addon, just enter its name (sans the .js) into the jquery parameter. It will first search the theme's /js folder and if found will then look for a like named .less or .css file in the /less or /css sibling folder. The system jQuery add-ons are located in /external/jquery/addons/. So to load the jQuery Colorbox (lightbox) addon (jquery.colorbox.js and jquery.colorbox.css), you'd use the following:
{script unique="myuniqueid" jquery='jquery.colorbox'}
{literal}
$('a.calpopevent').click(function(e) {
target = e.target; $.colorbox({
href: EXPONENT.PATH_RELATIVE+"index.php?controller=eventregistration&action=show&ajax_action=1&title="+target.id,
maxWidth: 650
});
e.preventDefault();
});
{/literal}
{/script}
We can also use the tag to load a jQuery script just as we would any other script.
{script unique="myuniqueid" jquery=1 src='myjqueryscript.js'}
{literal}
$(document).ready(function() {
// jQuery code goes here
myjsfunction(1, 2, 3); // function contained in myjqueryscript.js
} );
{/literal}
{/script}
Hopefully this little introduction to using jQuery within Exponent has whetted you appetite for using javascript within your custom theme or view.
Are you having a Facelift letdown?
You've unwrapped (installed) v2.3.0, and much to your dismay it looks the same! Where are all these major new features? One of the goals of the Exponent CMS project is to provide seamless or transparent upgrades to newer versions. While this isn't always true (1.x code deprecation, etc...), we do try to keep your web site looking the same after an upgrade, while offering new features and improving the site management tools. In this article, I'll attempt to show you how to activate the 'new' interface options and work around a couple minor issues.
First off, some issues which may require some editing or settings changes on your part are:
- We moved the bootstraptheme navbar/menu code from the theme template file into the navigation view template file. Here is an article describing needed changes if you have built a custom theme based on 'bootstraptheme' (the Twitter Boostrap v2 theme)
- This article also describes how to fix a 'jQuery' script crash/collision and solve a 'disappearing content' issue.
- If the WYSIWYG editor (CKEditor) doesn't appear, there may be a conflict between 'Minification' and CKEditor. Several different ways to work around this issue are:
- Turn Minification OFF using the Exponent, Super Admin Tools, System Cache menu
- Leave Minification ON, but turn off 'Minify and Combine linked js scripts' using the 'Minify' tab of the Configure Website command found on the Exponent menu
- Switch to begin using the new optional TinyMCE WYSIWYG editor (see below)
- Some settings/input forms may not save or close because we've added better validation of entries. Specially, this would apply to 'url' (link) and 'email' (address) type input. Though this is NOT the case in every place Exponent asks for a url or email, some of them require specific entry formats. The 'url' entry may be rejected if it doesn't begin with a protocol such as 'http://'. And an 'email' entry may be rejected if it doesn't contain the '@' sign, or it contains more than one email address (a comma is included). We have a fix for the multiple email address entry.
- We now correctly load style sheets in an expected sequence. The main framework library stylesheets (YUI, Bootstrap, etc...) are always loaded first, then the Exponent system stylesheets (core styles and those in the module views), and finally the theme stylesheets. This ensures the styles cascade correctly and that the theme custom styles have 'final' say on the styling. However, you may discover some display anomalies exposed by the correct loading order we now use, but they should easily be fixed by a custom theme style update.
- You may notice the .less stylesheet compiler takes a bit longer than before, but it is also faster than before. As before, we ONLY compile .less files into .css stylesheets once, or when updated, so like any caching option, the first time to the page is a bit slower. We've had to switch to a new 'less' compiler which is compatible with Twitter Bootstrap v3 (TB3), and in turn, TB3 also has some very complex stylesheets. However, we've now sped up the less compilation cache checking. So if you have Error Reporting turned OFF, the .less file will only be compiled/checked if the corresponding .css file is missing. If Error Reporting is turned ON, it will operate as in the past few versions where the cache is checked for each .less file and it will be (re) compiled if the .css file is missing or any of the .less files (including those being @import'ed) or the less variables have changed.
Now, here's how to use some of the new features:
- The new 'elFinder' File Manager is activated by changing the setting on the 'File Manager' tab of the Configure Website command found on the Exponent menu. Here is an article describing it.
- The new 'TimyMCE' WYSIWYG editor is activated changing the setting on the 'WYSIWYG' tab of the Configure Website command found on the Exponent menu. Here is an article describing it. Just like the CKEditor, you can create a custom configuration with an alternate skin, plugins, or toolbar, etc...
- The new 'Workflow' feature is activated using the Exponent, Super Admin Tools, Turn Workflow On/Off menu item. Here is an article describing it.
- We've provided an initial implementation of a TB3 based theme (bootstrap3theme) which also includes a new TB3 based admin user interface (new slingbar and chrome)! Designers can begin to develop their own custom TB3 theme(s) based on this one, though we will probably tweak the bootstrap3theme over the next six months. We strongly recommend you move away from any Twitter Bootstrap v2 (TB2) theme development as it has been deprecated and no new features or updates to TB2 support are planned for Exponent. However, we will still continue to support YUI3 based themes (YUI2 compatibility has been deprecated by YAHOO and is subject to breaking in the future). We will also continue to support non-Bootstrap/non-YUI based themes (which inherit YUI2/3 widgets, etc.. at this point).
- TB3 is the 'new interface' direction we are moving toward, and away from YUI2/3 as the primary/only user interface. This interface is called 'NewUI'. These themes are identified by a head config setting of 'framework=bootstrap3'.
- TB2 development is suspended, but uses TB2 buttons and controls (though some widgets are still YUI2/3 based/styled) with YUI2/3 slingbar and chrome. Since there are conflicts between TB2 and TB3 it will not receive any NewUI interface elements. These themes are identified by a head config setting of 'framework=bootstrap'.
- YUI and other non-Bootstrap themes are based on YUI2/3 (styled) buttons, controls, slingbar and chrome. These themes are identified by a head config setting of 'framework=yui', 'framework=jquery', or no 'framework' setting. However, these themes may be 'upgraded' to use the 'NewUI' by changing a system setting. Once this setting is turned on, the theme will use the NewUI (TB3) slingbar, chrome, controls/buttons, and other widgets. Since this feature is not yet fully robust/implemented, there is no user interface to turn it on or off. However, it can be activated within your non-Bootstrap based theme by adding '
define("NEWUI",'1');
' to your theme's 'config.php' file (found in the custom theme folder).
<?php
define("NEWUI",'1');
?>
- There is a new 'church web site' sample database which may be selected during installation. This is in addition to the general site, blog site, and eCommerce site sample databases. If you've already installed Exponent, but want to use one of these samples to 're-initialize' your site (will NOT affect current users/groups, but may affect their permissions), you can locate the /install/samples folder in the Exponent package file and do a 'Restore Database' (which will wipe-out/overwrite all/most current site content).
- If you need to move some blog, news, or portfolio items to another site, you can now export and import them, by module and by item. Importing the export file will add them to your content instead of overwriting it as would occur with a 'Restore Database.'
- There are many more new features, most of which can be found on the module configuration setting views. Look for a future article describing some of these.
And finally, here are some new features which are automatically implemented:
- Out of the box, you should have better Search Engine Optimization (SEO) since we now provide better, more specific meta data to the search engines. This should appear as greater search hit detail (event & product data such as dates, cost, reviews, etc...).
- If you use a Twitter Bootstrap based theme, you should immediately notice better response on mobile and handheld devices, or even on desktops when the browser window size changes.
- On some of the management views (manage users/groups/permissions, display form data, and event registrations) we now use a 'widget' which provides for much faster paging and column sorting, better filtering (search), and options to copy/print/export.
As mentioned in previous articles the next upgrade, v2.3.1 shouldn't be expected until around the end of 2014. What this means is that only patches will be released to address issues with v2.3.0 such as bug fixes or a 'proper' or 'broader' implementation of existing features. Now go have fun with your 'NEW' web site!
Using the new Workflow Feature
Version 2.3.0 includes a new optional feature called 'Workflow'. This feature allows greater control over a multi-user site, especially where there are many users adding new material which should be edited or approved prior to being visible to the public. 'Workflow' adds 1) Revisions, and 2) Approval.
'Workflow' is activated or deactivated using the 'Exponent' 'Super-Admin Tools' menu. Workflow is currently enabled within the Blog, News, & Text modules. A 'Workflow' enabled module can be identified on the Manage Modules view. Once 'Workflow' is activated creating or updating module items behaves differently depending on the user's permissions.
Revisions – in a very basic sense, revisioning creates a new copy or revision of a module item each time the item is edited/saved. This affords an opportunity to ‘roll back’ or ‘undo’ an edit.
- Revisions are ‘reported’ on the standard view with a badge displaying the revision # next to the ‘Edit’ button/link.
- Revisions are ‘managed’ in the Edit item view.
- Revisions are initially hidden within a collapsed container below the standard edit area…with the most most recent at the top of the stack.
- The ‘revision’ being edited will be highlighted
- A previous revision may be activated by 1) clicking on that revision, and 2) when the display refreshes with the new data, saving the item
- Currently, old revisions can NOT be manually removed, so you will have a permanent history of all edits to that item. However, it is possible to set the max number of revisions by manually editing the config.php file (no UI exists yet).
Approval – in a very basic sense, approval adds a layer of ‘moderation’ before content may be presented to a basic user with no permissions.
- Without an ‘approve’ permission, the user will only see (interact with) the most recent ‘approved’ item revision (if any).
- All new/edited items will be saved as un-approved revisions unless the user has 'approve' permission:
- If a user WITHOUT 'approve' permission edits an item,
- they will be editing the most recent approved revision which will be saved as an un-approved, but newer revision
- With an ‘approve’ permission, the user will see the most recent item revision which may then be ‘approved’ using the new ‘Approve’ button/link.
- Creating/Editing, then saving an item will automatically approve it
- Turning on ‘Preview Mode’ will display the most recent approved revision (if any)
- An un-approved item will be ‘displayed’ on the standard view with special highlighting (yellow background and red border) which disappears on ‘hover’.
- Currently, you can NOT un-approve a revision, therefore you are required to either leave it alone (unedited, unapproved), edit it (will be saved as approved), or simply approve it as is.
- If a user WITHOUT 'approve' permission edits an item,
- The ‘Approve’ permission is tied to the ‘edit’ and ‘create’ permissions. It applies to ALL items in the module the user has ‘edit’ permission with…therefore the ‘create’ permission with an ‘approve’ permission only allows (automatic) approval of that user’s items, but not all items in the module, you must also grant them the ‘edit’ permission…e.g., if you can’t edit it, you can’t approve it.
- As a reminder, Admins and Super-Admins are ALWAYS granted ALL permissions, and a 'manage' permission grants ALL permissions (for that page/module).
One thing to consider before activating 'Workflow'
- Non-admin users MUST specifically be granted an 'approve' permission to create/edit items for display, otherwise that revision must be approved before it is displayed. So, until you grant 'approve' permissions, the admin(s) may be busy approving all new content.
And a big caution before de-activating 'Workflow'
- When you de-activate workflow, ALL revisions except the most recent approved revision will be permanently removed!
In most instances, 'Workflow' may not be of use. But if you are in a multi-user environment where you need to control what actually is displayed on the site, you now have a new tool.
Preparing to Upgrade to v2.3.0
Version 2.3.0 is the follow-up to version 2.2.3 and was given a version bump due to the many new features added. It also marks a 'slowing down' of version releases as it's purposely been five months since the last release. While it doesn't require as many changes as the move to v2.2.0 (which deprecated all the old 1.x code), it would still be wise to note and adhere these following changes.
The navigation showall_Flydown view for a bootstrap based theme now includes all the associated markup in the view instead of in the theme template. Therefore if you use this view or have based your custom theme on 'bootstraptheme' (it is the default menu for the boostraptheme) you MUST edit your theme templates (including subthemes)
- The older code looked something like:
<!-- navigation bar/menu -->
<div class="navigation navbar <?php echo (MENU_LOCATION) ? 'navbar-'.MENU_LOCATION : '' ?>">
<div class="navbar-inner">
<div class="container"> <!-- toggle for collapsed/mobile navbar content -->
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span> <span class="icon-bar"></span>
<span class="icon-bar"></span> </a>
<!-- menu header -->
<a class="brand" href="<?php echo URL_FULL ?>"><?php echo ORGANIZATION_NAME ?></a>
<!-- menu -->
<?php expTheme::module(array("controller"=>"navigation","action"=>"showall","view"=>"showall_Flydown")); ?>
</div>
</div>
</div>
<div class="navbar-spacer"></div>
<div class="navbar-spacer-bottom"></div> - This is simply replaced by:
<?php expTheme::module(array("controller"=>"navigation","action"=>"showall","view"=>"showall_Flydown")); ?>
- Depending on which exponent version you created your theme from (first shipped w/ v2.2.0), you may not have all those lines above. In fact, in v2.2.0, the menu was a theme custom menu simply call 'showall'
There may be duplicate Search Engine Friendly (SEF) URLs. We include an optional upgrade script to correct this issue, but do NOT run it automatically. Duplicate SEF URLs can cause issues when using the new 'Workflow' feature.
If your pages/content seems to have disappeared for non-admin users, you should first (re)run the 'Fix Sectionrefs' upgrade script. If that doesn't fix the problem, you need to ensure the 'Disable Privacy Feature' is selected found in 'Confgure Website' Exponent menu item, under the 'Display' tab.
If you have manually loaded the 'jQuery' script, it may be colliding with the auto-loaded jQuery script. The BEST method to ensure that jQuery is auto-loaded, is to set the theme framework (in the theme template/subtheme templates) to either 'jquery'. jQuery is also auto-loaded with the bootstrap theme frameworks. Documentation found here.
Again, not a lot of earth shattering changes required, but we always recommend doing a test before upgrading a production web site, just in case.
Which WYSIWYG Editor to Choose?
Version 2.3.0 includes a second optional What You See Is What You Get (WYSIWG) editor called TinyMCE. While in most cases you'll probably want to stick with the venerable CKEditor, TinyMCE will work on Android devices, where CKEditor does not.
To enable the TinyMCE editor, open ''Configure Website' from the Exponent menu. Then select the 'WYSIWYG Editor' tab and select 'TinyMCE' as the system text editor. For the time being, the TinyMCE text editor is only an option and not the default.
In addition to working on an Android device, TinyMCE offers most of the features found in the CKEditor. However, some features are not as advanced as with CKEditor. TinyMCE also offers a menu bar which may contain additional commands not found in the toolbar.
You may not have a need to use the new TinyMCE editor, but we offer it for those requiring WYSIWYG editing on Android based devices.
Using the new elFinder File Manager
Version 2.3.0 includes a new modern File Manager which (in the long run) will make it much easier to manage and work with uploaded files. In general, elFinder follows an 'operating system' paradigm, so it should be fairly logical to begin using, but it is much different than the old Exponent File Manager.
Some of the (new) elFinder features include:
- True file folders for easier file organization
- Drag and Drop file upload and moving (CAUTION: while you can move a file, it may break any references within WYSIWYG text since they are embedded as hard reference links instead of as an expFile object)
- File cut/copy/paste
- Single 'pane' file management and upload, instead of the old separate file uploader
- Command toolbar to access most actions directly
- Item option (context) menus
- 'Touch' enabled to work with mobile devices
- Integrated file archive creation and extraction (not available on windows servers)
- Icon and details folder views
To enable the new elFinder file manager, open ''Configure Website' from the Exponent menu. Then select the 'File Manger' tab and select 'elFinder' as the system file manager. For the time being, the elFinder file manager is only an option and not the default file manager.
How to use these new features:
- Basic Window Layout
- As with most modern file mangers there are three basic areas or panes in the elFinder window
- Toolbar - is located at the top of the window
- Folder Tree Pane - is located to the left side of the window. The folder hierarchy can be collapse or expanded and the pane width may be adjusted
- File Pane - this is the largest area of the window which displays all the file in the current folder or those matching a search request
- elFinder also uses context menus which appear on folders, files, or the File Pane background
- As with most modern file mangers there are three basic areas or panes in the elFinder window
- File Uploads
- The easiest way to upload files into the file manager is to simply drag them from your PC desktop/file manager and drop them on/into the folder you choose.
- You may also click on the 'Select files to upload' toolbar button, or choose the 'Upload files' context menu item from the file pane. This will present a window to drag/drop files, to paste a file, or open a file select dialog to choose the files to upload.
- File Selection
- The easiest way to select a file when the file manager is opened from within an editor or edit item dialog, is to simply double-click the file.
- You may also click on the 'Select files' toolbar button, or choose 'Select' from the context menu for the file(s)
- You may select more than one file by using the control/shift method or a drag box.
- File Operations/Management
- You may cut, copy, paste, duplicate, rename, delete, or preview a file using the appropriate toolbar button or context menu item
- You can display the files in the file pane as either large icons or a detailed list
- You can sort the displayed files by name, size, kind, and date, in ascending or descending order
- Image Editing
- elFinder includes integrated image resizing, cropping, and rotation using the 'Resize & Rotate' command
- For more advanced editing, we now use an online service called Pixlr to provide full graphics editing features.
- As is the case with all commands, you can use the toolbar button or the context menu which will present you with a dialog to select either the full-blown Pixlr editor or Pixlr Express which has fewer features.
- Exponent File Management
- The options to change file sharing, image title, image 'alt' title are now found in the 'Info' dialog of the file which can be displayed via toolbar or context menu
- The 'sharing' status is changed instantly, but the 'title' and 'alt title' require you click on the 'update' button for the change to take place
- You'll also see additional details such as file type, size, dimensions, file owner, etc...
- There are also details about the file/folder found in the 'status' bar at the bottom of the window
- There is also a 'Preview' command available to display/play images, videos, & mp3 files
- File Search
- There is a built-in search feature using the input box in the toolbar. Simply enter the phrase, press 'enter' and all the files in the system matching that phrase will be displayed, regardless of their folder location.
- Click on the 'x' button or select a folder in the folder tree pane to clear the search.
- Transfer (back) to the Insert/Modify Link Dialog
- If you are inserting a 'link' to a page into an editor instead of a link to a file, you can switch to the dialog with a list of pages available, the option to select a module on a page, or to switch back to the file manager. This button is found on the toolbar to allow you to switch back to the Insert/Modify Link window. It is located next to the toolbar 'Help' button.
Overall, we think you'll be pleased with the new elFinder File Manager and find it much simpler to use.