Blog items tagged with "tutorials"

Making your Custom Theme more Accessible

We're recently added better 'accessibility' support to Exponent so it may be used with a screen reader. This is mandated with some public website due to the Americans with Disabilities Act. While the code shipped with Exponent v2.4.0 includes these changes, they may need to be integrated into your custom theme. Though you can check your theme/subtheme templates and custom views with the ones we ship, here are some things to look for:

  • The theme/subtheme templates must contain a 'language' in the html tag
    • from
      <html>
      to 
      <html lang="<?php echo (substr(LOCALE,0,2)) ?>">
  • any {img ...} tag found in any template view (.tpl file), must include a 'alt=xxx' entry
  • any button or input area with NO label, or any with only an icon must include 
     aria-label="{'button label'|gettext}"

While this is not an all-encompassing list, it will get you through most of the errors that an accessibility plugin for your browser would report

eCommerce Payments

BillingThe goal of this article is to help better understand how 'payments' operate within the Exponent eCommerce system.  'Payments' are used to virtualize an online cash transaction for goods (products) or services (event registration or donation).  There are basically two (2) types of payment systems called 'billing calculators' within Exponent:

  1. Those which handle the entire transaction online through a 3rd party which charges for their service (such as Authorize.net, WorldPay, and PayPal)
  2. Those which record a payment due where the transaction must be accomplished outside of Exponent...which may or may not charge for their service (such as cash/check, credit card, and bill me)

In most cases, we would only want to offer one (1) online payment option if we conduct all our business online, or perhaps a 2nd option if we also handle business directly with a customer at a brick-and-mortar location where the customer can pay when they arrive at the location for the event or to pick up the product.

Though no explanation should be necessary for handling and processing cash or checks, the 'cash/check' and 'pass-thru' payment options are designed for 'point of sale' type transactions by an employee of the merchant.  Perhaps the best method to allow customers to pay by cash or check possibly by mail, or to use a credit card when they show up is to use the 'bill me later' payment option.  If we wish to allow payment online by credit card and already have a service for processing credit card transactions, we could use the 'credit card' payment option.

If we want to have the entire payment not only recorded but processed online, we'd need to use one of the other payment options.  All of those options charge a fee for their services, though PayPal Express only charges per transaction instead of a monthly fee like the others.  ALL types of credit card or bank debit payments are transacted using several steps:

  1. Authorization - places a hold on a specified amount of funds, usually the total cost of the order (+- 15%) for 3 days.  However, the money is not transferred from the customer to the merchant.  You may have seen this occur when you make a purchase which initially appears as a $1 charge, but later changes to the full amount.
    • Void - cancels out the remainder of a funds 'authorization'.  If the authorization has already be partially 'captured' (or paid out), the 'void' action will simply close the authorization out.
  2. Capture - moves a specified amount of funds from the customer to the merchant.  This amount may or may not be the total of the entire order, such as a segmented shipment of an order due to some items being out of stock requiring two shipments.  Each 'capture' must usually be specifically authorized, and in most cases, the amount captured may or may not equal the amount originally authorized.  E.g., the shipping cost of the order was slightly more/less than what appeared at checkout and the exact cost was charged to the customer.
    • Refund - transfers previously 'captured' funds from the merchant back to the customer
  3. Others - there are some other actions which can take place such as:
    • Order - simply earmarks a future 'Authorization' by collecting the customer information, no 'hold' is placed on the funds and they may not exists.
    • Reauthorization - allows extending an 'Authorization' by 3 days (to a maximum of 30 days) or allowing a 2nd 'Capture' against the 'Authorization.

We'll primarily use the PayPal Express (PPE) payment option as an example here since it's the easiest full-featured one to use, which offers a good place to start.  PPE offers three (3) 'Processing Modes'.  1) Sale, 2) Authorization, and 3) Order.  

The recommended mode is 'Sale' which automatically authorizes and immediately captures the entire amount of the order when it is submitted.  This works well since it doesn't require additional actions or monitoring on the part of the merchant, but it also implies the merchandise is 'in stock' and will be shipped very quickly.  However in larger companies, it might be more prudent to only charge the customer (capture funds) once the merchandise is shipped, and then only for those items actually shipped.  The 'Sale' mode doesn't allow for this although you could simulate it by issuing a partial refund.  When managing the order, you'll note the 'Refund' button with an area to enter the amount on the invoice 'Billing' area.

A better approach might be to use the 'Authorization' or 'Order' modes where the funds are manually 'captured' when the items are shipped.  Since we can't initiate an 'Authorization' from within Exponent (in the current release), we don't currently recommend using the 'Order' mode (Though this can be accomplished on the PayPal site).  In 'Authorization' mode, the amount is 'authorized' when the order is submitted.  If you pull up the order, you note a 'Capture' button with an area to enter the amount and 'Void' button on the invoice 'Billing' area.  The order processing sequence would work like:

  • new order submitted/received (funds are 'authorized' and placed on hold for 3 day)
  • order review begins (status set to 'processing' with a optional email sent to the customer)
  • order is sent to 'warehouse' for packaging, order items are retrieved and boxed, and the box weighed (status set to 'sent to warehouse')
    • package data used to create/purchase shipping label and get a shipment tracking id
    • shipping label applied to package, then picked up by carrier
  • total cost of the order is 'captured' from the order invoice, since the funds were previously authorized (placed on hold)
    • shipping date & tracking id entered into the invoice (status set to 'order has been shipped' with an optional email set to the customer)
  • the order has been 'fulfilled' at this point
  • if a 'return' is required, a full or partial 'refund' can be issued from the order invoice (once the returned item is received?)

Though perhaps not a full-fledged 'how to conduct e-commerce article, this information may help you better understand how ecommerce billing works and encourage you to 'take the plunge' into the icy waters of e-commerce.

Theming with Twitter Bootstrap version 3 - Part 3

Twitter Bootstrap 3(Corrected May 5, 2014) Recently, Google changed the way they rank search hits by elevating those from 'mobile friendly' web sites and lowering those which are not mobile friendly.  To be 'mobile friendly' your web site must conform to modern standards (HTML5) AND must be small device and 'touch friendly' ...meaning the page is viewable on a small screen and the buttons/links have some space/distance between them for 'fat fingers.  The easiest way to make your Exponent CMS site 'mobile friendly' is to switch or update to a Twitter Bootstrap 3 based theme.  Exponent CMS allows you to do this in just a matter of minutes.

The easiest (and most obvious)  method is to simply switch to the included 'bootstrap3theme'.  This would immediately ensure your web site is 'mobile friendly.'  In most cases, the content of you web site will remain unchanged, though some custom theme elements in the header, footer, and sidebar may not appear if you were using a non-standard 'source' name within the previous custom theme.  In its stock form, the bootstrap3theme is well, plain.

The next level of customization would be to 'customize' the shipped theme using the 'Configure' button found with the theme on the 'Manage Themes' page.  

  • We offer a dozen or so different theme styles which offer a variety of colors, fonts, and styles
  • You could spice up the look with some 'flair' to the widgets by selecting the 'Bootstrap v2 Styles' setting which will give them a slight 3d effect
  • You could choose a 'fluid' width which would make the content fill almost the entire width of the display or browser width.  'Fixed' width limits the overall width of the content.
  • You can also select the 'size' of the buttons, location of the main menu (navbar), whether the navbar is aligned to the left or right side of the page, whether the flyout sidebar container is displayed, and a couple of tweaks to adjust how the main navbar is displayed.

The only drawbacks thus far are: 1) the theme and its 'configuration' will be overwritten the next time you update the site software with a new version since you are using a 'shipped theme', and 2) the basic Twitter Bootstrap themes are somewhat lacking in 'flash'.

Therefore the next level of customization would be to create a custom version of the shipped bootstrap3theme.  The documentation for creating a custom theme is found here.  A quick overview would be  to copy the entire /themes/bootstrap3theme folder into a new folder with a different name.  We'll say 'customtheme' for example and ensure we update the new custom theme's 'class.php' file to reflect the new theme's real name.  Once this complete, you'll need to select your new 'customtheme' from the Manage Themes page.  At this point your site will be identical to the previous step, but will not longer be in jeopardy of replacement when updating the site software version.  If you want to place the custom theme swatch files within your custom theme for further customization, you will need to:

  • Copy the .less files from the selected theme style which is found in /external/bootstrap3/less/'theme style name'.  You should find two files here...variables.less and bootswatch.less
  • WARNING! You MUST edit the new variables.less file which will fill in any missing, but essential variables:
    • Add the following line to the TOP of the new custom variables.less file
      • @import "../../../external/bootstrap3/less/variables.less";
    • The 'merge' the contents of the existing 'variables.less' file to the BOTTOM of the custom theme variables.less file to ensure any custom navbar 'collapse' width is followed.  
  • NEXT you MUST also insert the following line at the top of the 'bootswatch.less' file to get it to compile correctly
    • @import "variables.less";
  • Then if you want to make some subtle color changes, you can use a site like bootswatchr.com which will let you copy in your 'variables.less' file and allow you to edit it with instant feedback on color changes.

That's it, you now have a custom 'mobile friendly' web site.  Next time we'll dig a bit more deeply (and spend more time) to customize the theme to look 'less plain.'

Basic Theme Framework Concepts

Bootstrap 3A 'theme framework' is a tool or library of stylesheets and javascript code which help a web designer more efficiently create a stylish web site. In most cases they allow for effectively sectioning off a page using styles instead of tables. They also include code to easily create the different user interface 'widgets' and utilities which would otherwise take a lot of code (e.g. time) to produce.  Exponent CMS currently contains built-in support for two (2) different theme frameworks: 1) Yahoo User Interface (or YUI), and 2) Twitter Bootstrap (or Bootstrap).  And within each of these frameworks we include two (2) versions.  The question is 'which one to use?'

First, we'll cover some definitions which relate to the goals of each of these theme frameworks:

  • Fixed - this term relates to a section (page, column, etc...) having a 'fixed' width in terms of pixels.  Regardless of the size of the display (this includes the width of the browser window when resized), the section is the same size.  A fixed section may have to be 'zoomed' in order to be fully displayed on the screen, and then the size of the text may be unreadable.
  • Fluid - this term relates to a section having a 'fluid' width in terms of percentage of the parent section.  When the size of the parent container changes, the 'fluid' section will change.  A fluid section inside a fixed section would appear to be fixed, but could adjust based on the style used for that parent section.
  • Grids - this term relates to using html 'div' containers to section off a web page layout, instead of having to use html tables (which at this point in time is an ancient concept).  Most web pages have many grids, especially to make headers, columns, navigation areas, etc... for the page layout.  In other words, to keep the entire page from acting as if it were a single block of text.
  • Responsive - this term relates to the page layout (automatically) adjusting itself based on the size of the display (whether due to the physical size of the screen or width of the browser window).  Of these four definitions, this is 'the goal' for being able to present content to a visitor to your web site.  Imagine browsing to a web page on your smart phone, where the entire page is displayed but it is so small it is unintelligible...enter 'responsive' web site styling.  In days past, web designers were required to create two different web sites to provide content to both small handheld devices and desktop pc's.  Exponent provides built-in support for using two different types of sub-themes  based on whether a device is small or large (mobile theme variations), but that still requires creating two page layout designs.  'Responsive' styling allows a single page layout to provide the best information display to the user regardless of the size of display being used.

A basic rundown of the five (5) available frameworks (we'll count 'NO' theme framework as one) included in Exponent are:

  • YUI2 - has been deprecated since 2011 and was the primary framework used in Exponent v0.9x..  The styles allow for both fixed and fluid grids, but they are not responsive.  It also provides many widgets from its own javascript code library.  
    • YUI3 based widgets are automatically displayed, since we've replaced all the YUI2 javascript code (as of about v2.3.0)
    • To use the YUI2 grids, you must specially load the stylesheet 'YUI2_RELATIVE."yui2-reset-fonts-grids/yui2-reset-fonts-grids.css"' in your expTheme::head();. YUI2 grids typically use a class name with a 'yui-' prefix and provide both fixed and fluid variations
    • Though we don't recommend creating new custom themes based on YUI2, there is an example theme named 'basetheme'  based on YUI2 available here.  
  • YUI3 - is no longer supported by Yahoo, but is still being maintained.  It was the primary framework used in Exponent v2.x until v2.2.0.  The styles allow for both fixed, but mostly fluid grids, and more recently (since v2.2.0) allows for minimal 'responsive' support.
    • YUI3 based widgets are automatically displayed.  To display jQuery library based widgets (if they are available instead of YUI3), you can set the theme framework to 'jquery' in your expTheme::head(); (which also automatically loads the jQuery javascript library).  You can also display Bootstrap 3 based widgets (including the Exponent and module menus) by setting a config.php constant named 'NEWUI'.
    • To use YUI3 grids, you must specially load the stylesheet 'YUI3_RELATIVE."cssgrids/cssgrids-min.css"' in your expTheme::head();.  YUI3 grids typically use a class name with a 'yui3-u-' prefix.
    • Though we don't recommend creating new custom themes based on YUI3, we ship an example theme named 'simpletheme'  based on YUI3.  
  • Bootstrap 2 - was originally shipped with Exponent v2.2.0.  The styles allow for both fixed and fluid grids with some responsive support.  The typical grid system uses 12 columns.  To use the Bootstrap 2 theme framework, set it to 'bootstrap' in your expTheme::head();
    • Bootstrap 2 based widgets are automatically displayed (using jquery or YUI3 widgets if Bootstrap 2 ones are not available).  The Exponent and module menus are still YUI based.  Bootstrap 2 widgets use the jQuery library, but are written to support Bootstrap 2 styling.
    • Bootstrap 2 grids are automatically available with responsive support and columns typically use a class name with a 'span' prefix.
    • We also automatically provide Font Awesome v3.x support with icons having an 'icon-' prefix.
    • Since Bootstrap 2 has reached 'end of life', we don't recommend it for new custom themes, however we ship an example theme named 'bootstraptheme' based on Bootstrap 2.
  • Bootstrap 3 - is the current recommended theme framework for Exponent and has been available since v2.3.0.  Like Bootstrap 2 it's grid system uses 12 columns, but allows for fully 'responsive' web designs since it is 'mobile first'.  Each grid may be 'classed' as to how it should display on various sized devices (large widescreen desktops, medium desktops, tablets, and smart phones).    To use the Bootstrap 3 theme framework, set it to 'bootstrap3' in your expTheme::head();
    • Bootstrap 3 based widgets are automatically displayed (using Bootstrap 2, jquery, or YUI3 widgets, in that order if Bootstrap 3 ones are not available).  Bootstrap 3 widgets use the jQuery code library, but are written to support Bootstrap 3 styling.
    • Bootstrap 3 grids are automatically available with responsive support and columns typically use a class name with a 'col-' prefix.
    • We also automatically provide Font Awesome v4.x support with icons having an 'fa-' prefix.
    • Bootstrap 3 is the recommended theme framework and we ship an example theme named 'bootstrap3theme' based on Bootstrap 3.
  • No framework - you are not required to use a theme framework for a custom theme in Exponent CMS.  In fact most web theme templates can be converted for use in Exponent (see this article)
    • YUI3 based widgets are automatically displayed.  To display jQuery library based widgets (if they are available instead of YUI3), you can set the theme framework to 'jquery' in your expTheme::head(); (which also automatically loads the jQuery javascript library).

If you have already developed a custom theme for Exponent, you may want to stick with a known quantity and use that familiar theme framework.  However, if your just starting a custom theme, we'd recommend using Bootstrap 3.  Though we will continue to include, support, and fix the YUI2, YUI3, and Bootstrap 2 theme frameworks, in the future most of the new features will emphasize Bootstrap 3.

NOTE: For details about building a custom theme for Exponent CMS or about how themes work, please visit our help/documentation pages found here.  Details about the expTheme::head() method are found here.

Where, Oh Where Has My Little Script Gone...

Scripting...oh where, oh where can it be!  Was your web site running a script that has seemed to stop working (or no longer even appears in the content) since your upgrade to v2.3.1 (or one of the v2.1.4 or v2.2.3 security patches)?  Well on the 'plus' side, that means the security fix is working, but that's not what you wanted to hear.  To help eliminate possible site security issues which could be caused by script injections, we now strip all content of any 'script' tags EXCEPT within Code Snippet modules.  Therefore, if you had embedded a script such as Google Analytics or similar within a Text module, it is now stripped out before saving or displaying.  What you'll need to do is either embed the script directly within the theme/subtheme template file (e.g., v2.3.3 now allows calling a script or code directly from the expTheme::foot() call) or use a Code Snippet module on the page.

jQuery and Exponent....sitting in a tree...

jQueryThe 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.

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 Revisions

'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.Revisions
    • 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’.Unapproved Revision
      • 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.
  • 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.

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.elFinder 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:

  1. 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
  2. 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.
  3. 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.
  4. 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
  5. 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.
  6. 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
  7. 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.
  8. 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.

 

Successful Site Upgrade Strategies

Exponent is a very active project and frequently receives new features.  Issues or anomalies are also corrected shortly after being identified.  You'd think those would be great incentives to update to the most recent stable version, just to make managing and maintaining a web site much easier.  Here are some tips to help in upgrading a site, or to prepare to upgrade a site.

As a quick overview, an Exponent web site consists of five (5) components:

  1. the Exponent software, which gives you an empty site and is the starting place for all sites whether being built from scratch, moved to a new server, or restored after a server failure. This is the part of the update that we provide for you.
  2. the custom theme, which gives your site a unique character apart from all other web sites.  While we provide some sample themes (either in the package or additional ones on the download site), most users want to customize their own theme.  The user must maintain (update?) the custom theme and ensure it does not contain obsolete commands or calls.  It is stored/contained in the '/themes' folder.
  3. the site's configuration settings, which hold the basic information about the site.  It is stored in the 'config.php' file which is created and updated by the Exponent software.  It is unique to each web server.
  4. the site's content, which is the majority all you see on the web site.  This is stored in the database and is updated automatically during the 'upgrade' process.
  5. the site's support files, which includes all the images used on the site, and any files made available though the site.  These are stored in the '/files' folder and are not affected by upgrades.

The first step in preparing to upgrade a site (and preventing disaster in general), is always maintain a BACK UP of your site.  In order to back up the five (5) components:

  1. The Exponent software is always available on Sourceforge and through GitHub, so there's no need to keep a local copy.
  2. The custom theme was created by you and in most cases you'll already maintain a copy.  However in v2.2.0+, there is a new 'Export Theme' command available in the Theme Manager to easily package and download your custom theme for restoration, or to move to a new site.  The theme may be restored/added to a site using the 'Install Extension' command.
  3. The 'config.php' file is located in the '/conf' folder (v2.0/2.1) or the '/framework/conf' folder (v2.2).  The easiest way to quickly get 'back up and running' is to restore a copy of the config.php file.  For security reasons Exponent provides no automated method to retrieve nor restore the config.php file.  However, we highly recommend you use cPanel or ftp to obtain a copy.
  4. The site's content (database) is easily saved or restored using the Import/Export EQL (Exponent Query Language) File commands. The export command allows you to tailor which information/tables are saved, while the import command replaces any database tables with the ones stored in the EQL file.
  5. Lastly, the site's support files are easily saved using the Import/Export Files commands.

So once you have a backup of your site, especially the site's content (EQL file), you may proceed.

In a very simplistic sense, upgrading to a new version of Exponent is an easy two (2) step process.

  1. Install the new software version on your server by either extracting the .zip file to the root folder/subfolder, or using 'git pull' from ssh or a shell.
  2. Browse to your site and follow the instructions in the 'upgrade' notice which now appears.

That sounds so simple, what could go wrong?  Well, here are some common issues or problems which might prevent a smooth upgrade:

  • Your custom theme (or a custom view) is outdated and uses obsolete commands.  Though the basic format of an Exponent theme hasn't changed much from the v0.9x days, many of the 'commands' have been updated and streamlined.  Here's the documentation on the theme template format to check/update your theme.  Here's a good article on checking for and updating themes to be v2.2.0+ compliant.  As we move into version 2.2.0+, many of the obsolete calls will no longer work.  The easiest way to confirm the problem lies in the custom theme is to switch your site to a 'shipped' theme and see if it works as expected.  If for some reason you can't log onto the site, the current theme is stored in the 'config.php' file on the line with DISPLAY_THEME_REAL.
  • Your site crashed in the middle of an upgrade and now is 'broken'.  While this rarely occurs with the 'stable' software, it can exist after a test with pre-release software.  Your best bet is to run the upgrade again by manually kicking it off with a browse to your site via www.yoursite.org/install/index.php.  In many cases this will detect and correct a half-upgraded site which may also correct the issue.

While we realize that many Exponent users are actually providing a paid service to clients and their 'time is money.'  Therefore, if a site is up and running, why 'donate' your valuable time to a paying customer.  However, if YOU are the one doing most of the site content, it sure helps to have access to the 'user suggested' new features and have those annoying quirks and bugs fixed.