Blog items tagged with "tutorials"

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:

Tutorials: How to Convert a Generic Theme to Exponent

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.

Tutorials: How to Insert an Image into an Exponent CMS Text Module

To insert an image from the Exponent CMS File Manager into a Text module, you must first click the edit icon on the text module to begin editing the module.

Exponent CMS Text Editor

Once you've clicked the edit icon, you will be directed to Exponent's text editor:

Exponent CMS Text Editor

To insert an image into a text module, you must first place your cursor before the sentence in which you want the photo to flow.

Exponent CMS Text Editor

Once you've selected where in the text you want the image to flow, you can then go and select the image you want by clicking on the Insert/Edit Image button in the text editor tool bar.

Exponent CMS Insert/Edit Image Button

Once you've clicked the Insert/Edit Image button, you will be prompted with an Insert/Edit Image dialogue box. To select the image you want to insert into the module, you must then click the “Browse Server” button.

Exponent CMS Insert Image Configuration

After you click the “Browse Server” Button, the Exponent CMS File Manager will open, allowing you to navigate to the image you want to insert (Read more information on how to upload new files to the Exponent CMS File Manager):

Exponent CMS File Manager

To select the image you wish to insert into the text module, you must find the image in the File Manager and then click on the Green arrow next to the image underneath the “Actions” Column of the File Manager:

Exponent CMS Insert Image Configuration

After you've selected your image, the Exponent CMS File Manager will automatically close and your image will be inserted into the Insert/Edit Image dialogue box where you can select positioning, linking and padding for your image as well as giving your image an Alternative text title:

Exponent CMS Insert Image Configuration

The Image properties dialogue box also has two tabs called "Links" and "Advanced" where you have other image configuration options. If you want to embed a link into the image, click on the "Link" tab. Here you can define the URL you'd like to link to and also determine whether that link should open up into a new window.

Exponent CMS Insert Image Configuration

On the Advanced tab, you have the option to type in a pre-determined CSS style class for your image such as "border" if there has been a CSS style sheet created that puts a border around your images. Here you can also add an Advisory title for the search engines to let them know what the image is that's being displayed.

Once you've finished configuring your image, click the “OK” button. You will now see the image pop into your text editor in the position you've defined:

Exponent CMS Text Editor

After you've clicked save, you're all done! Your image has successfully been inserted into the module and will appear on the page:

Exponent CMS Image Editing

Tutorials: How to Create Password Protected Pages on your Exponent CMS Website

Exponent CMS offers a robust permissions system giving Site Administrators the power to easily grant Viewing and Editing rights on a granular level. It is very easy to create these Password Protected pages using any combination of usernames, passwords, and group rights.

The permission system for Exponent CMS allows Site Administrators to create both User and Group accounts with varying levels of administrative and viewing privileges.

For example, Site Admins have the ability to create a “Members Only” group and grant that group permission to view a certain set of Password Protected pages on your website. It is also possible to grant that same group of people or an individual user on the website the right to administrate a particular page or piece of content on the website.

The process Site Administrators must follow in order to achieve this powerful feature in Exponent CMS is:

  1. Create the Individual User Accounts necessary
  2. Create the Group Account that will receive the special Viewing or Editing permissions
  3. Assign the Individual Users to the Group Account
  4. Configure the Page or Set of Pages that you want protected to allow these permissions

Creating Individual User Accounts

The first step in creating Password Protected pages on your website is creating Individual User Accounts for users to login with.

Site Administrators can access Exponent's User Account Manager by clicking on the Exponent CMS logo on the Administrative Tool Bar at the top of the website. After clicking on the Exponent CMS logo, one of the drop down menu options is “User Management”. When hovering your cursor over “User Management” there are additional flyout menut options, one called “User Accounts”. To create an Individual User Account, select this menu item.

Exponent CMS User Accounts

Once Site Administrators have clicked “User Accounts” they will be redirected to the “Manage Users” page. Here, the Site Administrator can not only create new user accounts but can also:

  1. Reset passwords
  2. Edit Usernames and Email Addresses
  3. Delete User Accounts

Exponent CMS User Management Page

For the purposes of Creating Password Protected Sections on your Exponent CMS Website, this tutorial will highlight how to Add a new User Account. To do this Site Administrators must first click the “Add” link above the User Accounts table.
Once the Site Administrator selects the “Add” link, they will be directed to the “Create New User Account” form. Here, the Site Administrator will configure the new account with:

  1. A Username
  2. A Password
  3. An Email Address
  4. A First and Last Name
  5. Whether or not the new Account has Full Administrator Privileges.

Create New User Account Exponent CMS

The Site Administrator will need to create an Individual User Account for all users who will need to be assigned to the Group Account to view the Password Protected Section on the website.

Creating User Group Accounts

After creating each of the Individual User Accounts, the next step in creating Password Protected pages on your website is creating a User Group Account for the Individual Users to be assigned to.

Site Administrators can access Exponent's User Group Account Manager by clicking on the Exponent CMS logo on the Administrative Tool Bar at the top of the website. After clicking on the Exponent CMS logo, one of the drop down menu options is “User Management”. When hovering your cursor over “User Management” there are additional flyout menut options, one called “Group Accounts”. To create a User Group Account, select this menu item.

Exponent CMS Group Accounts Management

Once Site Administrators have clicked “Group Accounts” they will be redirected to the “Manage User Groups” page.

Here, the Site Administrator can not only create new User Group Accounts but can also:

  1. Manage Group Membership
  2. Edit Group Names, Descriptions and Settings
  3. Delete User Groups

Exponent CMS Group Management Page

For the purposes of Creating Password Protected Sections on your Exponent CMS Website, this tutorial will highlight how to Add a new User Group Account. To do this Site Administrators must first click the “Create a New User Group” link above the User Group Accounts table.

Once the Site Administrator selects the “Create a New User Group” link, they will be directed to the “Create User Group” form. Here, the Site Administrator will configure the new Group with:

  1. A Group Name
  2. A Description of the Group
  3. Whether or not new Individual User Accounts should automatically become members of the group with their new account is created.

Create New User Group Account Exponent CMS

Once the Site Administrator has created the new User Group, they must next Manage Group Membership.

To manage Group Members, Site Administrators must click on the Member Management icon next to the particular Group they want to Manage:

Exponent CMS Manage Group Membership

Once the Site Administrator has selected to manage the membership of a particular group, they will be directed to the Group Management Page.

Here, the Site Administrator can select Individual User Accounts to be members of that group, or grant certain Individual Users permission to Manage Users for that Group.

Manage User Group Members Exponent CMS

Now that Individual Users have been assigned to the Group Account, the Group account can now be assigned permission to View a section of Password Protected pages.

Assigning Group Permissions to a Page

The first step when assigning Groups with permissions to view or edit a page or set of pages on a website is for Site Administrators to go to Exponent's Page Manager.

To access the Page Manager, click on “Pages” on the Administrative Tool Bar at the top of the Website. Once “Pages” has been selected, click on “Manage All Pages.”

Exponent CMS Manage All Pages

This will direct Site Administrators to the Page Manager. Once the Site Administrator has arrived at the Page Manager, they must first make sure that the page(s) they wish to Password Protect is marked as “Non Public” and is not able to be viewed by just any site visitors.

To configure a page as “Non Public”, the Site Administrator must Edit the page configuration for that page by right clicking on the page and selecting “Edit this Page.”

Edit Pages Exponent CMS

After the Site Administrator has selected “Edit this Page” they will be redirected to the page configuration form where they can uncheck the Public box and resave the page so it is no longer available to the general public.

Make Pages Non-Public Exponent CMS

Next, the Site Administrator must then go back to the Page Manager and again right click on the page they want to assign the permissions to. This time after right clicking on the page, the Site Administrator will select “Manage Group Permissions.”

Assign Group Permissions to Exponent CMS pages

Once “Manage Group Permissions” has been selected, the Site Administrator will be directed to the Group Permission Management form where they can select which group has Viewing or Management rights on that particular page.

Assign Group Permissions

The Site Administrator also has the ability to assign Individual User Accounts the ability to View or Edit a particular section on the site by Assigning User Permissions to that page.

To do so, the Site Administrator must go to the Page Manager and right click on the page they want to assign the permissions to. After right clicking, the Site Administrator will select “Manage User Permissions.”

Manage User Page Permissions Exponent CMS

Once “Manage User Permissions” has been selected, the Site Administrator will be directed to the User Permission Management form where they can select which Users have Viewing or Management rights on that particular page.

Assign User Permissions to Exponent CMS Page

Once the appropriate permissions have been assigned to their pages, the Users will be able to login to the Website with the Individual User Accounts created by the Site Administrators and will be able to View or Edit those select pages.

Tutorials: How To Upload Files to the Exponent CMS File Manager

The first in our series of my How To tutorials for Site Administrators starts with the process of how to upload files to the file manager on an Exponent CMS website.

To get started, the Exponent CMS administrative tool bar at the top of the page has a tab called “Files”

If you click on “Files” you have two options. If you want to immediately upload files to the file server, you can select “Upload Files”. The other option is to select the “File Manager” button which allows you to view all the files on the file server in the File Manager.

Exponent CMS Admin Tool Bar Upload Files

If you've selected to view all of the files and clicked the “File Manager” option, you can see a paginated listing of all the files on your site's file server.

The Exponent file manager gives you the option of being able to search for a particular file based on keywords. For example, if you are looking for a particular file on the server and you know that it has the word “presentation” in it then you can type in “presentation” into the search box and the file manager will filter all files that have the word “presentation” in the file name or in the Meta Title or Alt Text Title of the file.

Exponent CMS File Manager Searc Filter Results

If you want to upload new files to the file server, there is a button in the upper right hand corner of the File Manager that says “Upload Files” ... You can also access the “Upload Files” page by selecting “Upload Files from the administration tool bar as well.

Upload Files to Exponent CMS File Manager

Once you've selected “Upload Files” you must select the files from your computer that you wish to upload to the file server. To do this click on the “Select Files” button in the upper right corner of the “Upload Files” page.

Select Files to Upload to Exponent CMS File Manager

Once you've clicked on the “Select Files” button you will be given a dialogue box to navigate to the files you want to upload on your computer's Desktop. From there, you can select as many files as you want to upload. In the Exponent CMS 2.0 codeline, you're no longer limited to uploading just one file at a time! Click “Open” once you're done selecting your files.

Select Files From Desktop

Once you've selected your files, you will now see them listed in the files queue to be uploaded. To finish uploading the files, now click on “Upload Files” in the upper right hand corner.

Exponent CMS File Manager Uploader

Once your files are done uploading, all of the bars underneath “Upload progress” will be red.

Finished Uploading Files

And now you know how to upload new images, PDFs and word documents to your Exponent CMS website!