Blog items tagged with "tips"

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.

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.TinyMCE WYSIWYG Editor

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

 

More About Less

less cssCSS3Back in version 2.0.8 we added the LESS ​stylesheet compiler to Exponent.  LESS is a dynamic stylesheet language which extends CSS with dynamic behavior such as variables, ​mixins, operations and functions.  This functionality makes it much easier to create flexible stylesheets since redundant styles and style variations can be handled by the compiler/server instead of the designer.  Though this addition to Exponent was primarily to support Twitter-Bootstrap, its use is increasing especially beginning with v2.2.3.

In this article our focus is on creating or updating .less stylesheets.  For information on how to incorporate .less style sheets into your custom theme, module, or view, please see this help doc.  The use of .less stylesheets in place of .css stylesheets is transparent within Exponent.  

In version 2.2.3 we convert all our core css stylesheets to .less, since we now also have custom 'mixins' to do some of the heavy lifting.  Mixins allow you to tie a bunch of properties and customizable values all into one nice little package.  Here’s an example:

/* Mixin */
.box-shadow (@x: 0px, @y: 3px, @blur: 5px, @color: #333) {
  -webkit-box-shadow: @x @y @blur rgba(0, 0, 0, @color);
  -moz-box-shadow: @x @y @blur rgba(0, 0, 0, @color);
  box-shadow: @x @y @blur rgba(0, 0, 0, @color);
}

This takes all of the box-shadow code needed for display on multiple browsers and wraps it up nicely into a single mixin that can be implemented with custom values (or the defaults that we used above). Now, instead of writing a huge chunk of code every time you want a box-shadow, this is all you need:

/* Implementation */
.somediv {
  .box-shadow(5px, 5px, 6px, #eee);
}

Pretty awesome right? When this code is compiled automatically by Exponent, it’ll create a the appropriate CSS stylesheet. You get a much more readable code without sacrificing browser compatibility.

In v2.2.3 we include a custom 'mixins' file which is located in /framework/core/assets/less/exponent.less.  This mixn may be included in your .less file by adding the following line to the top.

 @import '/framework/core/assets/less/exponent.less'

Here are some of the mixins found in exponent.less:

  • .border-radius and .border-radius-custom
  • .box-shadow and .drop-shadow
  • .gradient and .quick-gradient
  • .reflect
  • .opacity

Take a look at exponent.less to see all the included mixins, plus some implementation samples.

I think you'll appreciate how LESS can make your work 'more' productive and will consider using it in your next project.

Bring Out Yer Dead!

Bring Out Yer Dead!Monty Python fans will quickly recognize the title phrase and remember the scene where he's not quite dead.  So begins this article on how to remove all the old, dead stuff from your Exponent site and custom theme.  Before the end of the year (probably v2.2.3 which tentatively will be a Thanksgiving/Christmas holiday/last release of 2013) we'll have stripped out several deprecated modules and no longer support older themes (deprecated function calls).

Deprecated Function Calls

  • The most prevalent deprecated call when hard-coding modules is that a 2.0 controller requires an 'action' parameter where all the old school modules only used a 'view' parameter.  The default action is ALWAYS 'showall' (if none is passed) and the default view is ALWAYS the action name (if none is passed).  Therefore if you simply updated an old function call by changing it to 'expTheme::module()' and did not ensure you passed an 'action' parameter...you may not see the correct view...especially if the view you requested was not a variant of the showall action.  
    • Take for instance, the Search module 'Show' view.  If you updated it to simply pass the 'view' parameter of 'show', it would attempt to display the 'showall_show' view with the showall action.  The easiest fix is to change the 'view' parameter to an 'action' parameter which will automatically use the same named view ('action'=>'show').
  • I've previously written about the other hard-coding function calls which must be replaced.  In v2.2.1 you'll now receive a deprecated theme call warning message when logged on as an admin.  The message will contain details about what file and line the deprecated call is on and a suggestion on the fix with a link to a more detailed help page.  (updating to 2.2.0 blog post) (theme update guide)

Deprecated Modules

  • The Headline module was marked as deprecated quite a while back and was fully removed in v2.2.0.  It is replaced by the Text module showall 'Headline' view.  This change is automatically accomplished in an upgrade by converting all Headline modules into Text modules with the Headline view.
  • The Flowplayer module uses a non-HTML5 compliant player and was replaced by a newer Media Player module.  The new Media Player module also plays simple YouTube links using the same player (YouTube module requires using the 'embed' code) so we've also deprecated the YouTube module.  Though they still exist, they will be completely removed as stated above.  There is currently an optional upgrade script to convert all Flowplayer and YouTube modules into Media Player modules.  Currently if you run a 0.9x Migration, it will create Flowplayer/YouTube modules which you can then upgrade to Media Player modules.  This will be changed once the deprecated modules are removed.
  • All the old school modules have been deprecated, replaced, and removed as of v2.2.0.  In fact, you'll notice the 'Old School' modules tab is missing from the Module Manager.  Any old school modules on the site will automatically be upgraded to work with their 2.0 controller replacement during an upgrade.

Updated Requirements?

  • And now that PHP v5.5 has been released, PHP v5.3 is no longer recommended (end of life) and PHP 5.2 is obsolete, we should consider updating the minimum PHP requirement be at least v5.3.1 (or one of the more robust iterations of v5.3) to allow some of the v5.3+ only PHP features such as namespaces, etc...

Using Graphics and Files in Exponent Part #2

Recently I had written an article on using graphics and files which was common to most modules using either the WYSIWYG editor or as 'attached' files.  In this article I want to explore how to take advantage of the unique features of each module based on their designed purpose.  Again, you can use the text module to mimic the output from most of the other modules, but why not 'use the right tool for the job'

We'll start with the 'News' module.  The strengths of the news module are: each news item has a publish and an optional unpublish date, meaning the first date to display and the last date to display.  Also the items can be sorted several different ways by date in addition to manually (by rank).  You may also set the priority of the item by 'featuring it'.  A featured item will displayed in all views, where if not featured it may be hidden on some displays if the 'show featured' setting is on.  You may also publish the news items as an rss news feed or pull another rss news feed into the news module to be displayed as news items.  News modules may also have user subscriptions using the optional E-Alert feature.  Additionally, the a news item may be tagged so it can be associated with other similar news and non-news items based on the keyword tag(s).  Therefore the 'News' module is best suited for news or announcement type information.

In some ways, the 'Blog' module is like the news module on steroids.  It allows user comments on blog items and optionally allows groupings by category.  It has a 'draft' feature where the article will only be visible to the editor or administrator until published.  Unlike a news item, a blog item/article does not have an unpublish date, is only sorted by publish date, and doesn't pull in external rss feeds.  As it title suggests, the 'Blog' module is best suited for managing articles or web logs (blogs).

The 'File Downloads' module is very versatile, especially when contrasted with the blog module.  It deals with 'attached' file directly instead of the system generic method.  In addition to the attached file, you can attach a 'preview' image to be displayed on the site, or point the download to an external link.  It can optionally publish it's items as a Podcast.  It can optionally display attached media files using a media viewer to play the audio/video within the item.  It does not proved the user subscription feature.  If you need to provide file downloads or a Podcast, the 'File Downloads' module is your best bet.

The 'Portfolio' module deals with lists of data.  It does not store publish dates but can be ordered either manually or alphabetically.  It also provides a 'feature this' option.  It does not allow comments nor provide an rss feed option.  The 'Portfolio' module is best suited for directories or other lists of information.

The 'Photo Album' module deals with photos or images.  Its views focus on the attached image rather than the title and description, such as the gallery or slideshow views.  In addition to being sorted manually, photo items may be displayed randomly.  It also deals directly with an image file, meaning one photo item per image.  It should go without saying, but the 'Photo Album' module is bested suited for photos and images.

The 'Flowplayer', 'YouTube', and 'Media Player' (new to v2.2) deals with audio and video files.  While the 'file download' module can provide some features, the focus on these modules is displaying the media by playing it on the web site.  It provides greater control over the actual display of the media player being used.  These modules are best suited for display media on your site.  The 'Media Player' replaces both the 'Flowplayer' and 'YouTube' modules primarily because it can handle both types of media and is HTML5 compliant (Flash is not required)

Hopefully this article has provided some insight on choosing the best module for the task at hand.  I'll plan to write a follow up article on some of the more unique modules.

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.

Using Graphics and Files in Exponent

Though Exponent is designed to be 'easy to use' and 'flexible', sometimes the overlap of features between modules can make it  seem a bit complex.  Most modules allow you to display text and graphics, however each module is different in how content is displayed (how it appears to the user and acts as a web page) or administered.(managing and updating the content such as editing).  In this article I'll attempt to show the various features and limitations available to help you determine which is right for your particlular application.

The easiest method to display content on a page is to use a 'text' module. In fact you can mimic the content of most of other modules using a single text module if you're willing to do a lot of work to manually manage it.  In it's default state a text module item simply has a title and WYSIWYG (what you see is what you get) content.  However, you can optionally add file attachments using the module configuration settings 'Files' tab.  First let's look at how we can use graphics and files in the WYSIWYG content.

The WYSIWYG editor allows you to insert insert graphics and links in the content.  To insert a graphic into the text, click on the 'Image' icon (looks like a landscape picture).  In the 'Image Properties' dialog which appears, the 'Image Info' tab determines which graphic will be used and how it will appear in the text.  You can either type in the url to the graphic, or use the 'Browse Server' button to open the File Manager.  Once you've selected a graphic, the File Manager will close itself and the graphic will appear in the 'Preview' pane of the Image Properties dialog.  You can adjust the graphics appearance by using the settings to the left of the Preview and evaluate the results in the Preview pane.

The WYSIWYG editor Image Properties dialog also allows you to assign a link to the graphic when it is clicked.  Using the 'Link' tab you can enter a url to be sent to, or use the 'Browse Server' button to bring up the 'Insert/Modify Link' Manager.  This window allows you to easily select from any of the pages on the site in either the 'hierarchy' or as a 'standalone page' which returns you to the Image Properties dialog.  You may also link to a specific module on a page by using the 'Click Here to Link to Content' link in the top center.  This will bring up a copy of the web site, but you'll notice that all the 'chrome' menu bars now have replace the module menu with 'module type - Link to This Module'.  Browse to the desired page and click on the 'module type - Link to This Module' to select it and be returned to the 'Insert/Modify Link' Manager, where you can click the 'OK' button to return to the Image Properties dialog.  Or you may link to a file by clicking on the 'Switch to File Manager' link in the upper right corner of the 'Insert/Modify Link' Manager.  You may also select how the 'link' opens when clicked by selecting a 'Target' in the 'Links' tab of the Image Properties dialog.  Click OK, to place the image in the text.  You may manage existing graphics by dragging them around, or right-click to bring up a menu to change link or graphic settings.  As you can see, there is a limited amount of flexibility even at this point.  

However, let's say you want to associate graphics with the content, not necessarily embed them within it.  You can attach files to the text item  by turning this feature on using the 'Files' tab in the module Configuration Settings dialog.  This will activate an area below the WYWSIWYG editor to select and attach up to 10 files.  You can delete or rearrange the attached files using this same area.  The default setting on the 'Files' tab is 'This module does not use files' however you can attach files by selecting one of four display styles: Downloadable Files, Gallery, Showcase, Slideshow:

All four display styles allow you to set the Display Box.  You can adjust the 'box' placement (above, left, right, or below the content), its width, and its margin.  Exponent does its best to display the attached files within the display box and wraps the item content around it.  Any thumbnails will wrap within the display box, so if you do not set a display box width, you'll see a column of thumbnails.

  • Downloadable Files displays a list of all attached files as names with links to download the file.    For the Downloadable Files, you may also set the Title above the list.
  • Gallery is used to display one or more graphics with an optional 'lightbox' display.  You may select to only display the primary or first image on a listing or showall view, with all images displayed on an item or show view.  You can set the size of the thumbnails and their placement in relation to the primary image.
  • Showcase is used to display one or more graphics with a larger version of the current/selected graphic.  This also can be set to only display the pimary image on a listing page.  You can also set the action to display the thumbnail in the larger graphic by either a click or hover.
  • Slideshow is used to display a set of graphics as a slideshow.  And in v2.2+ you may optionally display the slide title and/or slideshow controls.

This has been a preliminary introduction to files and graphics in Exponent.  I plan to write another article to pick up on some module specific features dealing with files and graphics.

Prepping Your Site for v2.2.0 (or how to deal with a major update)

(Update: we HAVE reverted to the name 'container' instead of 'container2' for release candidate1!)  Here are some tips and tutorials to help ensure your site is 'v2.2 ready'!  While there is really no show-stopping change moving from v2.1.1 to v2.2.0, the move to v2.2.0 will reveal any themes or custom views which haven't been updated to 2.0 standards.  In a pragmatic sense, though the upgrade must be run and completed to convert the database for use in v2.2.0, your site would continue to work using one of the shipped or add-on themes which are 2.2 ready.

Since this upgrade only affects a custom theme and/or custom views, that's where we'll need to look:

  • Theme 1.0 compatibility removed
    • This one is the easiest to spot and correct.  It will occur in the main theme template (/themes/mytheme/index.php) and the subthemes (found in the subthemes folder)
    • Calls to the deprecated 1.0 theme subsystem look like 'exponent_theme_method' instead of 'expTheme::method'  And moreso there are only three mandatory calls with a fourth recommended call for hard-coding other modules
      • expTheme::head(...) in the <head>...</head> section, this method is used in place of the deprecated exponent_theme_headerInfo(...) call
      • expTheme::main() in the main content area in the <body>...</body> section, this method is used in place of the deprecated exponent_theme_main() call.
      • expTheme:foot() at the bottom of the <body>...</body> section, this method is used in place of the deprecated exponent_theme_footerInfo() call.
      • expTheme::module(...) within the main content area for hard-coding (embedding) modules, this is THE single multi-purpose method to display a module in place of many deprecated calls: 
        exponent_theme_showSectionalModule(...), 
        expTheme::showSectionalModule(...), 
        exponent_theme_showTopSectionalModule(...), 
        expTheme::showTopSectionalModule(...), 
        exponent_theme_showModule(...),
        expTheme::showModule(...),
        expTheme::showSectionalController(...),
        and expTheme::showController(...)
        • A big difference between the expTheme::module(...) call and the others (except the last two) is that it is called with a single parameter of an associative array of named parameters, whereas the deprecated ones were called with simple (sequential) parameters.
        • Likewise most of these various calls were to either deal with a 1.0 module or 2.0 controller, or to hard-code a module with a specific 'scope' (global, sectional, or top-sectional), which is now simply a 'scope' named parameter with 'global' being the default.  The expTheme::module(...) call is 'smart' in being able to to it all!
        • Deprecated call - expTheme::showModule($module,$view,$title,$source,$pickable,$section,$hide_menu,$params);
        • 2.0 call - expTheme::module(array("controller"=>"navigation","action"=>"showall","view"=>"showall_mega","source"=>"mega","chrome"=>true));
  • Old School (1.0) modules no longer exist
    • Another fairly easy thing to spot and correct are hard-coding an old school module within the main or subtheme template.  In many cases, these old school modules have been disappearing and references to them as hard-coded modules may have already been exposed.  However some were replaced with like named 2.0 modules (controllers)
    • A big difference between the old and 2.0 modules is old school modules only required a 'view' parameter, whereas the 2.0 modules require an 'action' parameter (with the default view implied).  The old school default (view) was 'Default' whereas the 2.0 module default action is 'showall' and the default view is also 'showall'. Therefore to locate old school modules, they were typically called using a 'module' parameter instead of 'controller' (however each are interchangeable).  Specifically, 2.0 modules need to have an action parameter, whereas the old school modules only pass a 'view' parameter (with NO action parameter).  If the old school view was something other than 'Default', please see the next area of discussion.
    • Here's a list of old school modules and their 2.0 counterparts:
      • simplepollmodule or simplepoll => simplePoll
      • navigationmodule or navigation => navigation
      • calendarmodule or calendar => events
      • formmodule or form => forms
      • containermodule or container => container (this has changed to simply 'container' in release candidate 1)
      • headlineController or headline => text (this is a 2.0 controller which has been deprecated)
    • Here's an example of an update required since most themes include a hard-coded container
      • Deprecated call - expTheme::module(array("module"=>"container","view"=>"Default","source"=>"@left"));
      • 2.0 call - expTheme::module(array("controller"=>"container","action"=>"showall","view"=>"showall","source"=>"@left"));
    • ​​If you've kept up to date through v2.1.1, the only NEW upgrade involves the 'container' module.  
    • The deprecated call may continue to work, but is unsupported.  If it fails to work because this is a module name change, your custom themes will not seem to work (will say that containermodule is unavailable) until it is corrected.
  • Old School Module Custom Views must be updated to work with their 2.0 module counterpart
    • The most complex of the changes will likely be required for any old school module custom views.  These would be found in the //themes/mytheme/modules/ folder using any of the above full module named folders.  In many cases, the custom view could be upgraded by a couple of simple renames.
      • Rename the 'module' folder into its 2.0 counterpart...e.g., 'navigationmodule' into 'navigation'
      • Within the newly renamed folder, enter the 'views' folder and create a new folder with the name of the module, such as 'navigation'
      • Move all the other files (.tpl files) within that 'views' folder into that newly created folder
      • Enter the folder with the moved templates, then rename the view template(s) into a 2.0 suitable name which includes the action:
        • 'Default.tpl' would become 'showall.tpl'
        • 'YUI Top Nav.tpl' would become 'showall_YUI Top Nav.tpl'
    • Any configuration or form files (.config or .form) would need more complex editing.
      • .config files are no longer used as these details must now be handled within the controller itself
      • .form files are now templates within the 'configure' subfolder of the views folder.  They are named by the associated view name with a .config suffix.  The files are now formatted just like a view instead of using the shorthand notation to create controls.  You should look at a system module like 'events' or 'blog' to get an idea of how view specific configurations work.
  • (Updated) Some YUI constants and file names/locations have been deprecated
    • Both of these issues tend to be revealed as improper formatting such as misaligned columns or font styles.
    • The 'Reset' stylesheet names have been deprecated for quite some time (apparently) and were finally removed in YUI v3.10.0.  Since many of the older themes use YUI reset(s) instead of the new 'normalize' standard, here's the changes you'll need to look for and make in the expTheme::head() call at the top of your theme templates (and subthemes) (note the additional 'css' at the beginning of the filename!)
      • cssreset/reset-min.css has become cssreset/cssreset-min.css
      • cssreset/fonts-min.css has become cssfonts/cssfonts-min.css
      • cssreset/grids-min.css has become cssgrids/cssgrids-min.css
    • We have finally removed the deprecated YUI path constants for consistency with other path constants.  These were typically used to load scripts or stylesheets in the theme templates (also subthemes) and custom views)
      • JS_FULL is now JS_URL
      • JS_PATH is now JS_RELATIVE
      • YUI3_PATH is now YUI3_RELATIVE
      • YUI2_PATH is now YUI2_RELATIVE

Other articles of interest: