Posts from "2015"

Exponent provides an excellent environment for writing and sharing articles or 'blogs'.  A site where the 'back-end' is on the front-end and a variety of what-you-see-is-what-you-get WYSIWYG editors take away some of the creative hassles with writing.  Another nice convenience for writing articles which is found on other blog applications (like WP), is editing the articles offline by using an application to manage and edit multiple blog articles.  Though there was preliminary support for this feature in the v0.99beta1 release (before v2.x), it has not been available to the v2.x code line...until now.  

Why would you want to use a desktop application to edit articles instead of simply using the browser?

• Submitting the same or similar articles to multiple blogs or sites
• Simultaneously working on many draft articles (beginning a new article while have several unfinished articles)
• Not having immediate, unrestricted access to a reliable high-speed internet connection, but you have your PC

The new offline blog editing feature will be available in the next release (currently at v2.3.4patch1).  It will be turned OFF by default, but can be turned on using 'Site Configuration' under the 'Security' tab.  It has been tested with several offline blog applications (mostly Windows based) such as Windows Live Writer, Zoundry Raven, Blog2Post, Windows 2007+, and ScrybeFire running in the Chrome browser.  Most of these interface with the blog site by adding an account.  This account creation process attempts to determine the type of blog, but all require the following information.

• user logon name (with create/edit permission to a blog module)
• user password
• url to the blog web page - www.mysite.org/my-blog
• url to the blog xmlrpc interface (blog post url) - www.mysite.org/xmlrpc.php
• type of blog - Metaweblog API (NOT WordPress, nor Blogger, etc...)
• image/picture uploading handled by - the blog provider

During the process, the offline application attempt to determine the type of blog, but will likely need some assistance in completing the process.  You should be shown the list of all the blog modules on the site.  Most applications will require a separate account be created for each blog module on the site, where others may only display the first blog module listed from the site.

Many of these applications provide support for publishing the article or posting it as a draft, tags (adding new tags or selecting from existing tags), categories (adding new categories or selecting from existing ones), setting the article publish date, inserting graphics, boilerplate templates, downloading the site 'theme' for better offline previews, and turning off user comments.  Some of these features require they be turned on within that blog module.  You may even be able to pull down recent or all blog posts from that blog to edit or archive.

All-in-all, another tool in the Exponent CMS arsenal to assist you in maintaining and managing your web site.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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