Posts by "David Leffler"

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.

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.

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.

The remnants of 'old school' Exponent are numbered...meaning very soon we'll no longer be strapped to the modules, subsystems, etc... of Exponent 0.9x that were necessary to get Exponent 2.0 up and flying.  For the most part, we've been able to disguise the great differences between the 0.9x coding architecture and the 2.x MVC coding architecture.  This was done by updating some of the  old school (0.9x) module admin interfaces to look (and act?) similar to the 2.x modules.  However this was done at some (resource) cost, and the complexity of having to deal with two different animals.  Therefore we'll modify our release and development strategies to best accommodate existing installations, yet not restrict such a bold move into the future!  What follows are some notes to Administrators/Designers and another set to Developers about how this will occur.

For Administrators/Designers - Putting out less-than-stable code for the upgrade of a production server is NOT what any administrator or user would expect, nor want to hear.  However, moving to a fully updated 2.0 system (no old school code) would likely temporarily disable some sites, and may diminish the stability of a running site.  That is, until some custom features (like a theme?) are upgraded on that site.  So how can we maintain stability (a stable code release line), yet vastly change the way things work (implement a major change without stagnating the release flow)?  By moving to a parallel release/development strategy!

What this means, is that while there will be many bug fixes and feature additions found in the next release (v2.1.1), it really won't be different from many of the releases over this past year (though looking back, some of the releases since 2.0.0 stable could be considered to have required major changes).  And you can likely expect at least one more (late spring?) release in like manner (v2.1.2), but it may likely be the last of the 2.0/2.1 line.  However, even that will NOT be a dead end, because it will be an easy move into the 'next' version (v2.2).  Version 2.2 will leave 0.9x (old school) compatibility behind, but will continue to be backwards compatible with any v2.x themes, modules, etc...  So things like any lingering old school modules (the ones found in the /framework/modules-1/ folder) or calls the old school theme compatibility layer (exponent_theme_xxx) will simply NOT exist (meaning the page will probably crash/break)!  However, things like YUI2/YUI3 (javascript/styling library) will still be fully available, but begin moving into a background role.  What will take front, center stage will be a reliance on 'Twitter Bootstrap' (styling library) and 'jQuery' (javascript library)!  We may also leave PHP v5.2.x compatibility behind since v5.5.x is about to be released and the use of v5.3 itself is no longer recommended.  The biggest change found in v2.2 will be a moderate change to the database which will prevent regressing to an earlier version (except by using an EQL backup)!  In fact, installing the v2.2 code on an existing site will give you the impression the site was wiped out...until you run and complete the 'upgrade/install' process!  So the big question is how can we move from a fully stable v2.1.2 to a fully stable v2.2?

Well the answer is to have both a stable release line (v2.1.x) and an unstable pre-release line (v2.2.x) running simultaneously.  In some respects, we already do this with the stable release ('master' branch of the git code repo) and the working development code ('develop' branch of the git code repo).  The BIG departure will be that unlike the 'develop' branch which is updated moment by moment and may be broken at times, the 'unstable' release will only be created as needed and should be a working set of code.  Therefore, when you see v2.1.1 hit the street in the near future, you can expect the release of v2.2.0-alpha1 almost simultaneously.  Any changes made to the v2.1.x line will also appear in the v2.2.x code, so if there are any future updates to the v2.0/2.1 line, it'll already be in the v2.2 code.  Then once v2.2 becomes stable, the v2.0/2.1 line would only receive critical patch updates, with the intent being a move to the v2.2 line.

This strategy should allow for the stability needed by most production sites, and yet allow (early) access to new features in a somewhat less than 'bleeding edge' manner.  For all intents and purposes, v2.2.0-alpha1 should be fully functional, but will NOT have been tested under many scenarios.

For Developers - Most of the changes will affect how we develop and release software updates, but primarily how we manage code branches.  Though these won't be much different from how we've been managing code using the Git-Flow paradigm.  For the most part, 'master' will (always) still be the most recent stable release.  'Develop' will still be the primary place for code updates to the stable release...in this case prep for a possible v2.1.2, but NOT the move to Twitter-Bootstrap, nor the Container 2.0 changes.

The big change however, will be the creation of several new branches of code in the git repo.  There is already a new branch called 'feature/container2' which will become v2.2.0-alpha1.  It already holds container 2.0, Twitter-Bootstrap, and a new bootstraptheme.  These are the major changes slated for v2.2.0.  The 'feature/container2' branch will be updated (merged) from the 'develop' branch on a regular (daily?) basis.  Conversely, the 'develop' branch will NOT be updated from 'feature/container2' until just prior to the release of v2.2.0 (stable).  We may also create a new 'hotfix' branch based on master AFTER the release of v2.1.1.  It will be where any fixes for v2.1.1 would be coded and will be merged/updated into 'develop' (which in turn is merged/updated into 'feature/container2').  We will also create an 'unstable' branch as a substitute for pulling from the the repo using a tag like v2.2.0-alpha1.  And as always there will be temporary (release testing) branches created between a code freeze and code release, which also includes any alpha and beta releases.  Therefore, there will be several branches of code in the Exponent git repo:

• master = most recent stable release (currently v2.1.0)
• develop = changes/updates slated for the next stable release (currently v2.1.1 pre-release).  It will hold any changes planned/needed for the v2.1 (2.0) line.
• feature/container2 = work on the next major release v2.2.0, updated from 'develop' regularly.  Will exist until AFTER v2.2.0 stable is released.  At that point, 'master' would then hold v2.2.0 stable (the most recent stable release at that time), and all code work would move to the 'develop' branch.  This branch can be thought of as the develop branch for v2.2.0 until it is stable.
• hotfix = fixes need for the most recent stable release.  Any work here wil1 eventually becomes a patch release to the current stable release.  'develop' is updated from this temporary branch.  We will automatically create a 'hotfix' branch once v2.1.1 is released to hold any fixes that need to be applied to v2.1.1.
• unstable = snapshot of 'feature/container2' at time of most recent unstable release, which is a substitute for pulling from the repo using a tag like 'v2.2.0-alpha1' or 'v2.2.0-beta1'  This makes it easier to update/test on a site using git pull instead of the unstable package release.

So, if you want the most recent stable release, you'd pull from the master branch.  If you want the most recent unstable release (alpha, beta, release candidate, etc...), you'd pull from the 'unstable' branch.  If you want the pre-release of the next stable version, you'd pull from the 'develop' branch.  And if you want the bleeding edge code, you'd pull from the 'feature/container2' branch.

For the most part this is a tried and true approach. It only seems new, because we didn't have a stable branch to deal with when we were working toward the first stable release of v2.0.0 .  Most likely things will work there way back to how we operate now once v.2.2.0 is released as stable.

Unlike most previous releases, the release of v2.0.9 has seen it's share of problems.  Though most of these are minor issues, they can seem to be an obstacle if not addressed.  Here's some things to watch out for, and steps to correct these issues:

Git Pull upgrade creates a merge conflict and the site 'crashes':

'Git' is supposed to prevent this, but for some reason when updating (git pull) a 'git' maintained site from 2.0.8 (or the patches) to 2.0.9, you'll receive a notice of a merge conflict and the site will no longer work.  The problem lies in two files (exponent_version.php and framework/modules-1/calendarmodule/class.php).  There are a couple different options to fix this, so you'll find the details in this forum post.  We are working to alleviate this issue!

Menus don't work the same as before the upgrade:

Even though the new navigation controller includes some compatibility to still allow old style navigationmodule modules to work...this apparently isn't true in all circumstances, especially complex menus.  The solution is to update the calls and the templates/views to the new 2.0 navigation module format.  This is a fairly simple change as it entails copying and renaming those custom templates.  You'll find the details in this forum post.

My customized site 'crashes':

This occurs if you are running customized modules (controllers) on your site.  Because PHP v5.4.x enforces greater code standards, we've had to update some of the main code which in turn requires updates to any custom modules (controllers).  This is a fairly simple update as it entails adding the 'static' keyword to the static functions inherited from the parent expController class.  You'll find the details in this forum post.

We'll keep this article up to date as things progress.

Here is a tutorial that will be appearing on the docs site which walks you through converting a generic web theme/template found on the internet into an Exponent theme.

Here's how you can create a custom theme using a generic web theme template.  There are countless free and paid web templates available on the internet.  You may search one of the template collection web sites to locate a 'theme' you would like to incorporate into Exponent.  For the purposes of this tutorial, we'll select a simple 3-column liquid template.

The template we've chosen can be found at http://matthewjamestaylor.com/blog/ultimate-multi-column-liquid-layouts-em-and-pixel-widths and we'll use the 3 Column (Blog Style) Liquid Layout which can be downloaded here.  Most themes are very easy to convert EXCEPT for the menu.  In this case the menu is an easy drop in replacement since the basic template doesn't really feature a menu,  Other templates might require custom styles to make it look similar, where others might require a near rewrite to create a duplicate menu.

Extract the template package to a new subfolder within the /themes folder.  Rename the folder to 'blogtheme'.  ALL themes MUST use a folder name that ends with the 'theme' phrase!  Inside the folder you'll note several files, one of which is 'index.htm.'  Open it in your browser to see what we've got.  You'll also note several graphics and a single stylesheet file in the folder.

Next we'll need to reorganize the folder to conform to Exponent theme requirements.  Create a 'css' folder and place all the stylesheets there (in this case only screen.css).  Create an 'images' folder and place all the images there (in this case none of the images are really used in the theme).  Next edit the index.htm and css/screen.css files to update the references to the new locations.

• In index.htm, you'll need to change the stylesheet and image references (this isn't necessary, but a good troubleshooting step).

  • <link rel="stylesheet" type="text/css" href="screen.css" media="screen" />

    to

    <link rel="stylesheet" type="text/css" href="css/screen.css" media="screen" />

  • <img src="mjt-125x125.gif"

    to

    <img src="images/mjt-125x125.gif"

    there are several of these.

• In css/screen.css, you need to change the references to graphics.  This is NOT necessary in this tutorial since there are NO graphics referenced by this particular css file, HOWEVER this is not simply a trouble shooting step!

  • Search for every instance of 'background : url(' and correct the url.  In this sample if there were any images, we could add an '../images' prefix to point to the new location of images.

• Refresh the sample page in the browser and you should see NO changes if everything went well.  Otherwise you need to check your edits.

Next we'll create the theme class file.  Copy the 'class.php' file from the simpletheme folder.

• Change the following line:
  

  if (class_exists('simpletheme')) return;

  to
  

  if (class_exists('blogtheme')) return;

• and change the following line:
  

  class simpletheme extends theme {

  to
  

  class blogtheme extends theme {

• Change the string in the name() function to "3-Column Blog Theme", you could also eidt the author() and description() strings as desired.

Now we'll convert the index.htm file into a theme template.

• Rename index.htm to index.php
• Replace the contents of <head>...</head> with expTheme::head() since Exponent handles this for us:

  <head>
      <?php 
      expTheme::head(array(
  	    "xhtml"=>false,
      	"css_core"=>array("common"),
      	"css_links"=>true,
      	"css_theme"=>true
          )
      );
      ?>
  </head>

• We'll also need to add the mandatory Exponent footer just above the closing </body></html> tags since this is what actually places the css and javascript on our pages

  <?php expTheme::foot(); ?>

You should now be able to select your new (useless) theme in Exponent, so log on to your site and Manage Themes and select your new "3-Column Blog Theme".  Don't expect too much just yet as we have NO dynamic content.  If you can select the theme and the site displays properly with the Exponent menu, we can proceed.  Otherwise you'll need to check the above steps and your editing for accuracy.

Next we'll clean the dead wood (static content) out of our template, index.php and replace it with dynamic content code.

• Delete all the lines between <div id="header"> and its closing </div> tag, about 13 lines and replace it with our header and menu 

  <h1>
      <a href="<?php echo URL_FULL; ?>" title="<?php echo SITE_TITLE; ?>"><?php echo ORGANIZATION_NAME; ?></a> <sub><?php echo SITE_HEADER; ?></sub> 
  </h1> 
  <?php expTheme::module(array("controller"=>"navigation","action"=>"showall","view"=>"showall_YUI Top Nav","source"=>"@top")); ?>

• Look for the <!-- Column 1 start --> comment and delete all the lines to the <!-- Column 1 end --> comment and replace it with our main container

  <?php expTheme::main(); ?>

• Look for the <!-- Column 2 start --> comment and delete all the lines to the <!-- Column 2 end --> comment and replace it with our left column container

  <?php expTheme::module(array("module"=>"container","view"=>"Default","source"=>"@left")); ?>

• Look for the <!-- Column 3 start --> comment and delete all the lines to the <!-- Column 3 end --> comment and replace it with our right column container

  <?php expTheme::module(array("module"=>"container","view"=>"Default","source"=>"@right")); ?>

• Finally, replace all the lines between <div id="footer"> and it's closing </div> with our footer text module

  <?php expTheme::module(array("controller"=>"text","action"=>"showall","view"=>"single","source"=>"@footer","chrome"=>1)) ?>

We're almost done, but need to add some styling to the .css file to ensure Exponent menus, etc.. are always in front of other items.

• The easiest way to do this is to create a 'base-styles.css' file in the /css folder.  We'll need to ensure the <div> id's match the one's used in the template.  Here's what our's would look like

  #header, #bd, #footer {
      position:relative;
  }
  #header {
      z-index:3;
  }
  #header {
      position:relative;
      z-index:5;
  }
  #bd {
      z-index:2;
  }
  #footer {
      z-index:1;
  }

At this point we should have a fully functioning theme suitable for use.  In most cases you may need to tweak the theme styles to override system styling or other conflicts resulting from the theme's styles.  This may be as simple as too much/little spacing to the menus don't work because most menus are actived by css styling or javascript which rests on using css styling.

The last thing we might want to do is to create a CKEditor css file.  You can find those details here.

(Updated Aug 2nd) We've had several requests lately to 'make forms look like they did in versions prior to v0.97.'  Meaning, place the label and input control on the same line instead of the label above the input control.  Since we're trying to move away from using tables to format the layout (the html5 way of doing things), it's not an easy fix, HOWEVER we can simulate the look using css styles.  (NOTE: we have implemented a Single column/Two Column form settings option in the next version 2.0.9 which will easily implement this feature)

Forms in 2.0

Forms in 0.96

Restyled Forms in 2.0

Though you won't necessarily end up with an exact reproduction, it will look similar.  One drawback is the width of the label is a hard width and will truncate long labels.  This more robust styling below prevents the label truncation.  Enter/Change this into your theme stylesheet: (updated Aug 2nd)

.control  {
    overflow: auto;
}

.control .label {
    display: block;
    float: left;
    width: 150px;  /* non-flexible part truncates label */
    text-align: right;
}

.control.radio .label {
    width: auto;  /* make radio buttons look normal */
}

.control.checkbox .label {
    width: auto;  /* make checkboxes look normal? may not be needed */
}

.datetime.date, .control table, .control.radiogroup table, .control.radio table, .control.checkbox table {
    display: inline;
}

.control-desc {
    margin-left: 160px;  /* make description fall directly under input */
}

.formmoduleedit .item-actions {
    display: inline;
    float:  right;
}

 

In recent conversations in the #exponent-cms irc chat on irc.freenode.net we’ve been discussing how best to maintain Exponent using the most current software technology.  Though Exponent has been based on YUI (Yahoo User Interface) for years, there are more commonly supported libraries which might be worth considering.  Some of these have familiar names in the developer community such as ‘jQuery’, ‘Twitter-Bootstrap’, and the ‘LESS’ css stylesheet compiler.  What’s more, several aspects of YUI are currently broken and unusable in Exponent (e.g., we ship v3.4.0 because newer versions such as v3.4.1, v3.5.x and the soon to be released v3.6.x break our displays).  (Rest assured, we'll maintain backwards compatibility) So here’s where Exponent MIGHT go within the next several releases.

The LESS css stylesheet compiler will likely be implemented and ship with v2.0.8, though not necessarily in its final configuration.  LESS allows a designer to create stylesheet templates with variables and other programming commands to allow the ‘machine’ to do most of the work rather than the designer needing to continually re-write redundant styles.  More information can be found at http://leafo.net/lessphp.  You will be able to fully use .less files in v2.0.8, however their location MAY have to be moved and their inclusion statements MAY need to be edited in future versions once we finalize support.

jQuery is a javascript library similar to YUI, but is designed for smaller projects.  However, it is more widely used and supported across the developer community.  If you were to browse the internet for examples of coding solutions, you’d most likely see several based on jQuery and very few solutions based on YUI.  There are tons of interface add-ons and other solutions available for jQuery.  More information can be found at http://jquery.com/.

Twitter-Bootstrap is a new user interface library of components and styles similar to YUI .  It uses both jQuery & LESS.  In many ways it is much simpler to implement than YUI and is more responsive to various display sizes without the need for multiple stylesheets or themes.  More information can be found at http://twitter.github.com/bootstrap/.
We already have locally running copies of Exponent using these technologies in the form of a custom theme which could easily be dropped into an existing v2.0.8 installation if desired.  So a future version of Exponent with a Bootstrap theme could look like this:

When Exponent v2.0.2 was released at the end of October 2011 it incorporated a fairly major change under the hood that could 'break' some custom themes or mods.  The template engine (what is used to display everything) was upgraded from Smarty v2.5.x to v3.1.x.  This was a major upgrade, but the syntax basically remained the same...the issue is that 'bad' template code which worked under previous versions will likely break with this version.  However, Smarty v3 adds many enhancements including the ability to use inline computations/math.  Details on how to identify problems and fixes is at the end of this post.

The Smarty v3 template engine adds a parser/lexer feature to better handle inline code (javascript and php) and also better parses commands such as handling inline math, etc...  However, because the parsing has changed slightly, it tends to choke when running across 'bad syntax' conditions that used to work (slipped by) in earlier versions.  So, if you have any custom templates you are using, you may have to update/edit them to work. 

• We'd recommend you first install v2.0.2 as a test installation on a server with php debug extensions loaded, and have DEVELOPMENT (Error Reporting) turned on (1).  This will point out which file and line number is causing any problems.
  • In most cases the error message will be somewhat descriptive of what needs changing e.g.,
    • Fatal error: Uncaught exception 'SmartyCompilerException' with message 'Syntax Error in template "C:xampphtdocsexp2frameworkmodulestextviewstextshowall.tpl" on line 49 "<a href="{link action=delete id=$text->id enabled=0}">{img src=`$smarty.const.ICON_RELATIVE`toggle_on.gif}</a>" - Unexpected "`"' in C:xampphtdocsexp2externalSmarty-3libssyspluginssmarty_internal_templatecompilerbase.php on line 617
    • This error tells you that the file '/framework/modules/text/view/text/showall.tpl' has a problem on line 49 which is an unexpected backtick
• When updating/changing Smarty versions or plugins, you MUST ALWAYS clear the smarty cache
• $smarty->_tpl_vars was deprecated without notice, so we MUST now use the getTemplateVars() method instead
• Smarty v2 automatically disabled error reporting in templates, not so under v3 therefore there are TONS of warnings (missing indexes, etc...) with our plugins and templates.
  • A partial interim solution is that we've turned off error reporting after creating the Smarty object
  • In future versions we may turn error reporting back on to ensure we have clean plugin code which will expose a lot of warnings.
• Smarty v3 allows expressions or variable references almost anywhere, and (apparently) isn't very tolerant of the backticks required to perform this in v2 (though this shouldn't be the case according to the documentation)...we use a lot of backticks for variables inside of plugin calls in templates.
  • In most cases you can simply remove the backticks in the 'offending' statement.
  • Look for any math statements in backticks such as rank=`$text->rank+1
    • Should be rank=$text->rank+1
  • This will NOT work in pre-2.0.2 since it handles math pretty poorly
• Because of the better parsing, some of the formerly unescaped characters in template strings will break. The fix is to escape them by adding a backslash before.
• You MUST enclose filenames containing symbols such as a period or dash, inside quotes now.
• Look for any unquoted filenames in the {icon call with the img param
  • Search for '{icon' in the *.tpl files in your theme folder
  • {icon img=image.png ...}, should be {icon img='image.png' ...}
  • This will also work well in pre-2.0.2
•  Concatenation of variables in strings can work by simply placing the text next to the closing brace {$variable}text, but you might best be served by using the 'cat' modifier such as $variable|cat:'text'
  • E.g., search for '{img' in the *.tpl files in your theme folder
  • Typically seen more in filenames such as {img src=`$smarty.const.ICON_RELATIVE`clean.png} or src={$smarty.const.ICON_RELATIVE}clean.png
  • Should be {img src=$smarty.const.ICON_RELATIVE|cat:'clean.png'
  • This will also work well in pre-2.0.2
  • In some server configurations, the $smarty.const.ICON_RELATIVE|cat:'clean.png' resolves literally to .const.ICON_RELATIVE|cat:'clean.png' instead of something like home/path/icons/clean.png.  Therefore it might be best to use the older backtick-delimted variation src='`$smarty.const.ICON_RELATIVE`clean.png'
• Variables for arrays and objects in Smarty MUST be preceded with the dollar ($) sign. This should be obvious, but even Smarty v3.1.3 still allows basic variables to be referenced without the $.
  • Sometimes shows up as error '...Unexpected "[", expected one of: "}" , " "' in...'
• And last, but not least...some of these required changes won't work under the older Smarty v2 (Exp v2.0.1 or older) so you'll have to wat least install a test using 2.0.2 to begin any updates.

(This article was originally a news post)

Here are some basics of using git and github to initially get or update the code to your site.  I've found this is an easy way to initial install, and the perform updates on my web sites.  There is a little bit of overhead (~105 MBytes), however the reduction in effort is worth it in most cases.

We’ll assume you have shell access to the server, and git is installed (‘git –v’ should work).

To (initially) Install ExponentCMS as your website:

• ‘cd’ to the root folder of your web (this folder should be empty since you are building a site from scratch.)
• To get the latest released code contained in the “master” or default code branch:

git clone git://github.com/exponentcms/exponent-cms.git .

• HOWEVER, the folder MUST be empty for the clone to work.  The work-around is to leave the "." off the end of that last command and then mv it to the root folder

  • git clone git://github.com/exponentcms/exponent-cms.git

  • mv exponent-cms/* .

• Launch the web site installer and complete the installation. (www.mysite.org/install/index.php)

• Install any custom themes or other local mods.

To update the code on your site to the most recent released version:

• ‘cd’ to the root folder of your web (this folder should be empty since you are building a site from scratch.)
• First save any local modifications to prevent any (merge) conflicts:

git stash save

• Next, download and merge the updated code:

git pull

• Next, restore any local modifications, if you choose (optional).  If you are (still) using a standard/shipped theme your theme configuration settings were reset to default unless you restore them):

git stash pop

• Then, log into your site as an admin user.  It's always a good idea to run an 'upgrade' so the database and any other changes are incorporated. (www.mysite.org/install/index.php)  In many cases, you'll see a message recommending the upgrade with a link to start the upgrade process.

To switch the code on your site to a development or pre-release testing version:

• ‘cd’ to the root folder of your web (this folder should be empty since you are building a site from scratch.)
• First save any local modifications in the current (master) branch:

git stash save

• Next, switch to and download the development/testing code:
• To get the bleeding edge code contained in the “develop” branch:

git checkout develop

• (or) To get and help test a version prior to its release contained in the “release/xxx” branch:

git checkout release/xxx

• (of course you’ll need to know the release tag or do a ‘git branch –a’ to list the branches)
• Please bear in mind the release/xxx branch is temporary and will only exist between code freeze and code release.  The “xxx” will be the actual release tag like “v2.0.8”
• If you’re having problems establishing the develop branch when working from an earlier clone:

git fetch
git checkout –-track –b develop origin/develop
git pull

• If you’re having problems establishing the release/xxx branch when working from an earlier clone:

git fetch
git checkout –-track –b release/xxx origin/release/xxx
git pull

• If you are using a custom theme or modifications (in the custom theme folder), your customizations remain intact.  However, if you were modifying system code, it'll have been replaced by the code from the git repo.
• Log into your site as an admin user and run the upgrade process (www.mysite.org/install/index.php)

To switch the code on your site BACK to the release version:

• ‘cd’ to the root folder of your web (this folder should be empty since you are building a site from scratch.)
• First save any local modifications to your development/testing branch:

git stash save

• Next, switch to the release code branch:

git checkout master

• Next, download any updated code:

git pull
git stash pop