Like most other applications of its size and purpose, we didn't write everything ourselves. We're indebted to members of the open source community like jQuery, TinyMCE, ADODB and others. They're integral to what we do, and have been with us since the very beginning. But just recently we've started using several new third party libraries to help us accomplish some impressive things and move us toward wider adoption and greater performance.

What libraries? Those would be some choice components of the Zend Framework. Yes, we've been using the Zend Framework since the very beginning as well, but its usage has become even more important in the latest release, concrete 5.4.

Why'd we start using the Zend Framework?

Trusted

Before we even take a look at the documentation for a particular library, we check out its history, its place in the web development world, and its track record. It's hard to go wrong with the PHP framework blessed by the language's founders. It also helps that every single proposal for each component of the framework can be found online, with feedback addressed publicly.

Documented and Understandable

In the first version of concrete5, we needed a solution for search that could be packaged up and shipped simply and quickly. We chose Zend_Search_Lucene, because its results were demonstrable and its code samples and API were easy to read and understand.

While we've since moved away from Lucene as a packaged-in solution – and instead have embraced search as a custom problem for custom sites – the lessons learned still resonate.

Modularity

Integrating Zend_Search_Lucene took all of an afternoon. While the Zend Framework is large and potentially imposing, it's a huge benefit that its components are modular and can be incorporated without also including everything and the kitchen sink.

Localization and Caching in 5.4: concrete5's Primary Use of the Zend Framework

Version 5.1 of concrete5 introduced localization of the concrete5 core, allowing translation of the application into other languages. It wasn't until version 5.4, however, that we provided a way for add-on developers to translate their add-ons as well, and provide their translations independently of the core. We wanted add-on developers to be able to make their add-ons translation-ready with the exact same syntax that the core team uses, and – if at all possible – be able to use strings already translated in the core.

This simply wasn't possible using PHP's built-in gettext localization library. So we switched to Zend_Translate and the Zend Framework, which worked like a charm. I was able to make it happen inside of a day. When finished, all our existing translation files still worked, and new ones for specific add-ons could be easily loaded at runtime.

Moving to Zend_Translate meant ditching our quickly-written, effective but inflexible cache backend for Zend_Cache, which instantly gave concrete5 support for many modern cache backends like APC, XCache, memcached, as well as standard file-system-based caching. This meant that, right out of the box, concrete5 installations on certain servers could receive significant performance improvements just by enabling some runtime options.

As we move forward toward concrete 5.4.1, the benefits are even clearer. With some application tuning and new caching options, plus the benefit of Zend_Cache working with an APC cache backend, preliminary local testing shows concrete5 5.4.1 performing nearly five times faster at rendering the default home page than under 5.3.3.1, all while providing much greater localization flexibility and supporting many more caching layers than we ever could have on our own.

Other Uses of the Zend Framework in concrete5

While caching and localization are the most front-and-center uses of the Zend Framework in concrete5, we employ it elsewhere. Any time you import a file from another web server into concrete5, you're using Zend_Mime. And switching to Zend_Mail has allowed us great flexibility in the mail department, including the ability to process inbound messages, connect to external SMTP servers, and even send HTML mails with attachments, all without worrying about how to connect to different mail servers or speak POP/IMAP.

That's really the promise of the Zend Framework: we can't be experts in everything, and it's to our benefit that there are those out there willing to develop modular, tested frameworks for interacting with the things that are ancillary - but still important - to our applications. concrete5 isn't a caching application, a localization application or an email application: it's a system for building useful, attractive websites and providing a simple means to edit them. But in order for it to be effective at meeting this goal, it needs to be able to connect to mail servers, read mail, send mail, cache its data objects and translate its core and add-on files. Using the Zend Framework means we can more effectively focus on the things we have experience with, and spend our time working on what really matters to us as application architects, interface designers and web developers.

Andrew Embler thinks it's freaking awesome his software is in use all over the world.

Code

This how-to references a reset script and permissions overrides. You can download these files here:

Reset Script and Permissions Overrides

Database Setup

It's important that you setup your demo install with its own database, database user, and database access. That way, if anything is ever disclosed or compromised, there is at least that sandbox in place. My demo will use the "concretedemo" user account, with the password "concretedemo," in the "concretedemo" database.

First I create the database:

CREATE DATABASE concretedemo;

Then I grant permissions to the user on the database:

GRANT ALL ON concretedemo.* TO concretedemo@localhost IDENTIFIED BY 'concretedemo';

Install concrete5

Download the latest version of concrete5, unzip it to the web directory that will house your demo, and install it.

Lockdown Dashboard

We want our demo user to be added to the Administrators group, so they can access the dashboard, but we don't want to give out full and complete access. We don't want sitewide settings to be looked at, or file access permissions to change, for example. Fortunately there's a little-used feature that allows us to lock down single page permissions at the time of their creation: access.xml files. These files live in the specific controllers/ directory for the given single page.

A sample access.xml file looks like this:

<access>
   <node handle="dashboard/files/access">
      <guests canRead="0" ></guests>
      <registered canRead="0" ></registered>
      <administrators canRead="0" canWrite="0" canAdmin="0" ></administrators>
   </node>
</access>

This locks the admnistrators group out of accessing the /dashboard/files/access page.

In the .zip file above, you'll see a controllers/ directory. Copy the contents of this controllers/ directory into your root controllers/ directory. The next time your demo site is reset, these access restrictions will be in place.

Install "Reset" Script

Also contained within the .zip file above is a reset script. When run, this script does the following:

1. Removes config/site.php
2. Removes all files in the files/ directory
3. Removes all tables in the demo database
4. Reinstalls concrete5 with the values specified in the reset script, and the database information that you originally installed concrete5 with. Permission overrides described in "Lockdown Dashboard" are applied
5. Creates a second administrative user in the Administrators group
6. Locks down file permissions
7. Disables site emails
8. Installs specified add-ons into the site.

Before you install

Please, rename the reset script! Anyone who hits the URL of the reset script will be able to reset your demo.

Configuration

There are a number of values at the beginning of the script that deserve explanation.

• DEMO_SETUP_SITE: This constant will determine the name of your site.
• DEMO_DB_SERVER: Your demo's MySQL server. Typically "localhost".
• DEMO_DB_USER: The username for your demo's MySQL user. e.g. "concretedemo".
• DEMO_DB_PASSWORD: The password for your demo's MySQL user. e.g. "concretedemo".
• DEMO_DB_DATABASE: Your demo's MySQL database. e.g. "concretedemo".
• DEMO_ADMIN_EMAIL: An email address for the admin account that will be created when your site is reset.
• DEMO_ADMIN_PASSWORD: The password for your "admin" user account.
• DEMO_USER_USERNAME: The username for your "demo" account. This is the account you will give out to users who wish to demo your software.
• DEMO_USER_PASSWORD: The password for the "demo" user.
• PASSWORD_SALT, MANUAL_PASSWORD_SALT: A long string that needs to be in place in this script.
• PACKAGES_TO_INSTALL: A comma-separated list of package handles of all add-ons in the local packages/ directory you wish to install every time the demo site is reset.

Scheduling this Script

It is easy to cron this script so that it will clean out data every hour. Something like this can be entered into a crontab on a Linux server. For example, if your reset script is

http://www.yoursite.com/reset_128273282.php

You can can make it run every hour on the hour with

0 * * * * /usr/bin/wget -T 0 -q http://www.yoursite.com/reset_128273282.php
 

in your crontab file.

Finished

That's it! Now you should have a fully functional concrete5 demo with a full admin account, a limited admin account, and any add-ons preinstalled that you wish to demonstrate.

While you may not be familiar with the amusingly-named Das Keyboard specifically, if you have any kind of affinity for touch typing you'll recognize what sets it apart from other keyboards: Das Keyboard is a rugged, good-looking keyboard with mechanical switches. This means serious speed for serious typists, and serious noise for anyone else (more on this later.) This keyboard clicks, both literally and figuratively. I took it for a test drive at SXSW, enjoyed it, and ordered it. It arrived awhile ago, and I've been putting it through its paces since.

Background

This isn't the first keyboard of its kind that I've owned. My favorite keyboard of all time was the Apple Extended keyboard, which used to be the standard keyboard to ship with Macs back in the mid-1990s. That keyboard featured mechanical switches and exceptionally rugged construction: I dropped it multiple times, and my college roommate spilled a 32oz soda on it, and it kept working til the end (although some keys were broken off and lost – and there was stickiness.) I suppose it's a testament to my fondness for that keyboard that I kept using it even in that state. It's to this high standard that I'm going to hold Das Keyboard. 

Appearance and Unboxing

Once the shipping container is opened, I took stock of the box that Das Keyboard comes in. No, this isn't Apple-level artistic packaging, but it's functional and nicely protects and presents your investment. 

Along with the keyboard itself, you get a USB cable, simple instructions and a cleaning cloth. This comes in handy, as the keyboard's shiny glossy finish will become marred by dust and fingerprints.

Setup

In 2010, setting up a keyboard shouldn't warrant a section in a review, but Das Keyboard makes some strange choices which I find fault with.

What's up with the USB?

The first thing I noticed that was strange about this keyboard is its USB cable. For some reason, Das Keyboard doesn't behave like every single other USB peripheral I've ever used. Instead of having a simple USB cable that extends from the keyboard and is plugged into your USB hub/computer/laptop, Das Keyboard's USB cable is actually two USB cables bound together.

Why? I have no idea - but without plugging in both cables to the host machine or hub, the keyboard's second USB port doesn't work. Ok, ok - what's the big deal? If you get a second powered USB port on the keyboard itself, what does it matter that you have to use two ports on the host machine or hub? I'll show you why it matters. Check out the initial setup of Das Keyboard on my MacBook Pro:

My MacBook Pro has two USB ports. Das Keyboard wanted both those ports to be used by the keyboard cable, leaving no ports on the computer free. Thankfully, my USB thumb drive fits well into the keyboard's second USB port, but I'm confused as to why this is even necessary. I had to purchase a USB extension cable in order for Das Keyboard's combined cable fit the MacBook Pro comfortably, and this means extra setup each time I connect and disconnect the machine. Obviously, not a huge deal, but mistifying and worthy of mention.

Keyboard Settings

My MacBook Pro runs OS X 10.4 Tiger. In order to get the keyboard to work with proper key placement (with the Control, Option and Command/Apple Keys in that order) I have to change settings every time I plug in the keyboard:

Then I reverse those when I unplug the laptop and take it home with me.

Windows Key

Finally, as a Mac a user, I feel a slight twinge when I glance down at my keyboard:

Yes, Das Keyboard sells keyboard kits, but I didn't feel like paying more than $20 (when including shipping) to add it to my order, which already cost north of $100.

Overall

Setup overall is a mixed bag. It's an area of keyboard usage that I had blithely anticipated wouldn't matter, but it actually accounts for most of my gripes with the product. Granted, they are small – quibbles, really – but a little irritating and confusing for a product that gets so much else right.

Construction and Looks

The construction of Das Keyboard seems sturdy enough. I haven't done anything foolish like spill a full soda on it, drop it in the ground or turn it over and bash it into a desk, but I have carted it a few places and been somewhat rough while cleaning it, all without incident. The lights on the keyboard are a satisfying blue, and the whole package is a very attractive one.

Usage

Speed (and Sound)

Here's where we get down to it. This keyboard is fast. Really fast. But it is not quiet. Check out this audio file of me speaking in a normal voice, and then as I continue to speak, I type the same sentence:

This will make enemies in an open office. Sadly, concrete5's office space is probably the absolutely worst work environment for this sort of keyboard, as we all inhabit one large room, but I think everyone puts up with it because I like it (which I very much appreciate.) There has been a noted increase in the use of headphones throughout the office, however.

Yes, Das Keyboard comes with a quiet version, but when I tried it at SXSW I didn't like it. It didn't seem as satisfying. Go loud or go home.

Results

My results are anecdotal in nature, but I think they're still impressive.

Typing Maniac

Typing Maniac is a Facebook game where the goal is to type words as they appear on screen, before they fall from the top of the screen to the bottom. As the game progresses, the speed increases and the words become more complex.

Prior to Das Keyboard, my highest score was in the 400,000s. Once Das Keyboard arrived, I more than doubled it, in my first try:

I will get to 1,000,000 points.

Das Keyboard Typing Test

Das Keyboard promotes its own typing test, and this was the test used at SXSW when it crowned the fastest touch typist in the world. This test is also available online at any time. Check out my results.

Not too shabby.

Cost

The results don't lie. This is a keyboard for those who type. As a bonus, it looks great and has a nice, satisfying weight. With a premium product comes a premium price. Das Keyboard Professional lists for $129, with a quieter version costing $135. Don't forget to add shipping to that, too. I was fortunate, however, to be able to grab the keyboard for 25% off, with free shipping, thanks to a SXSW-only deal. Scour the web for coupons – you'll likely find some.

Price-wise, this isn't much more than the cost of classic mechanical switch keyboards like the IBM Model M or the Apple Extended. But there's a reason those keyboards went out of fashion: they're expensive! Keyboards have gotten much cheaper since, and for those who are happy with a $19.99 keyboard found at a local superstore, paying more than six times as much is going to be a tall order. If you can afford it, and you're a touch typist, you'll be willing to make the sacrifice.

The Verdict

If you're a great touch typist, you find yourself typing frequently during the day, and you have an enclosed office (or tolerant, headphone-wearing co-workers), buy buy buy.

Andrew Embler can probably type faster than you. He apologizes for the noise.

Note: this isn't meant to be the one tutorial to rule them all: this is merely an overview to show you some of the ways concrete5 integrates and works well with JavaScript, how you can start exploring further.

jQuery: concrete5's JavaScript Framework

Much of concrete5's interaction model would simply not be possible without jQuery. One of the most popular extensions to JavaScript available, jQuery relieves much of the incompatibility and verbosity that has typically plagued the scripting of complex web applications.

We didn't always use an intermediary JavaScript framework (and – gulp – for a little while we flirted with Prototype), but jQuery makes so much about complex scripting easier than it used to be. And even better: jQuery's plugin model has been used to create great additions to the core library, including effects libraries and new widgets. Several of these plugins are also included in concrete5 core.

An Overview of All jQuery Components Included in concrete 5.4

The following jQuery libraries included with concrete 5.4:

• jQuery Core (1.4)
• jQuery UI (1.7.2)
• jQuery Scroll-To (1.3.3)
• jQuery Rating (3.0)
• jQuery Metadata
• jQuery LiveUpdate
• jQuery Form (2.12)
• jQuery Cookie
• jQuery Color Picker

jQuery UI

The following jQuery UI components are included in jquery.ui.js.

• jQuery UI Draggable
• jQuery UI Droppable
• jQuery UI Selectable
• jQuery UI Sortable
• jQuery UI Accordion
• jQuery UI Slider
• jQuery UI Progressbar
• jQuery UI Effects
• jQuery UI Datepicker

How to include jQuery and its Components in your Block or Single Page

Single Pages

Including jQuery in your single pages or pages of a certain type is as easy as calling addHeaderItem in your page's controller method. Let's say you have a page accessed at

http://www.yoursite.com/index.php/your_special_page/

That means you have a controller here at

controllers/your_special_page.php

or

controllers/your_special_page/controller.php

And within that controller file, in your view() method, the following will include the jQuery UI library, its required stylesheet, the concrete5 dialog class (more on this in a moment) and its required stylesheet.

public function view() {
   $html = Loader::helper('html');
   $this->addHeaderItem($html->css('jquery.ui.css'));
   $this->addHeaderItem($html->css('ccm.dialog.css'));
   $this->addHeaderItem($html->javascript('jquery.ui.js'));
   $this->addHeaderItem($html->javascript('ccm.dialog.js'));
}
 

The HtmlHelper class takes care of locating the correct file and printing out the proper tag. The Controller::addHeaderItem() function makes sure only one instance of a given header item is added, and is properly output in the HEAD tag of the page.

Blocks

Calling CSS and JavaScript in your blocks is even easier. If you'd like a particular block's view layer to require certain JavaScript and CSS, simply add it to the block controller's on_page_view() function:

public function on_page_view() {
  $html = Loader::helper('html');
  $this->addHeaderItem($html->css('jquery.ui.css'));
  $this->addHeaderItem($html->css('ccm.dialog.css'));
  $this->addHeaderItem($html->javascript('jquery.ui.js'));
  $this->addHeaderItem($html->javascript('ccm.dialog.js'));
}

Note: this is not the block's view() function. on_page_view() runs before the page is rendered, ensuring that the CSS and JavaScript files are added in the HEAD tag.

Once jQuery and jQuery UI are included in your page (and jQuery is typically included in themes by default) you'll be able to use all the great functionality described at jQuery.com.

How to use the built-in concrete5 Dialog Class

The built-in concrete5 dialog class is responsible for rendering all modal and non-modal dialog windows (not the slide-downs) that are positioned in the middle of the screen. This library is not the same as the jQuery UI dialog class. It was created before jQuery UI Dialog, and as such, currently conflicts with it.

Example 1: Loading an external url into a dialog using on-link attributes

The easiest way of calling a dialog window is by specifying certain attributes in the link you wish to use to call the window, and then calling the .dialog() function on that link.

<a 
   dialog-title="This is the dialog title." 
   dialog-modal="false"
   dialog-width="550" 
   dialog-height="380" 
   id="myDialog" 
   href="yourpage.php">This is the link</a>

Now, run the dialog function:

<script type="text/javascript">
   $(function() {
      $("#myDialog").dialog();
   });
</script>

This will load yourpage.php via AJAX, create a new 550x380 dialog window with the proper title, make it non-modal, and load the content into it.

Example 2: Loading an external url into a dialog from within a JavaScript function

The same operation above can be run from within a JavaScript function

<script type="text/javascript">
loadMyDialog = function() {
   jQuery.fn.dialog.open({
      title: 'This is my title',
      href: 'yourpage.php',
      width: 550,
      modal: false,
      height: 380,
      onClose: function() {
         alert('This will fire when the dialog is closed.');
      }
   });
}
</script>

Simply run loadMyDialog() and the proper dialog will open. Note the "onClose" function that will run when the dialog is closed.

Example 3: Loading the contents of an on-page element into a dialog from within a JavaScript function

If you'd rather load a dialog and populate it with in-page content, you can do so using the syntax below:

<div id="myDialogContent" style="display: none">
   This is the content of my dialog window.
</div>

<script type="text/javascript">
loadMyDialog = function() {
   jQuery.fn.dialog.open({
      title: 'This is my title',
      element: '#myDialogContent',
      width: 550,
      modal: false,
      height: 380,
      onClose: function() {
         alert('This will fire when the dialog is closed.');
      }
   });
}
</script>

AJAX

If you want to use jQuery to integrate some server-side processing into concrete5 (AJAX), it can be a little difficult to know where to start. There are basically two approaches available: 1) use a controller action and then exit from the action before rendering the page, or 2) use a tool script.

What's a tool script? A tool script is a simple PHP script either in your local tools/ directory or your block's tools/ directory. This script has no UI wrapped around it. It's lightweight, and simply loads a number of concrete5 objects and connects to the database. Otherwise, you're free to do what you wish inside it.

Using an Action for Server-Side Processing in a Block

From within the block's view layer, make the HREF of the link you wish to tie to the backend equal the value of an action method in your controller:

$action = $this->action('like');

This will create a link that will pass through to the block when the form is submitted, and then "action_like" action will be run.

Now, in HTML, we create the link:

<a href="<?=$action?>" id="myActionLink">Like!</a>

Now, in JavaScript, we make it so that the link in question submits to the backend:

$('#myActionLink').click(function() {        
   var url = $(this).attr('href');
   $.get(url, function(r) {
      alert('Success!');
   });
   return false;
});

Finally, the action_like() method in the block's controller processes, and then exits at the end.

Tools

Tools are another way to enable server-side processing. Using tools outside the block level is easy. For example, the JavaScript function ccm_dashboardRequestRemoteInformation runs every time the front page of the dashboard is hit:

ccm_dashboardRequestRemoteInformation = function() {
   $.get(CCM_TOOLS_PATH + '/dashboard/get_remote_information');
}

This simply loads the "dashboard/get_remote_information.php" tool through AJAX. The tools path takes care of making sure the script in the correct location is loaded.

Loading a block-specific tool is nearly as easy. From within a block's view layer, the following will automatically load information from a tool found in the block's tools/ directory:

<?php
$th = Loader::helper('concrete/urls'); 
$bt = $b->getBlockTypeObject();
?>
 
<script type="text/javascript">
$(function() {
   $.get('<?=$th->getBlockTypeToolsURL($bt)?>/load_information?>');
});
</script>

This will automatically find the "load_information.php" script within the block's tools directory, and load it silently. You can pass query string arguments to the script to obtain more functionality, and process them silently from within the script.

JSON

If you'd like to return JSON to your AJAX function, it's as easy as defining a simple PHP object within your tool or action function, instantiating the properties you want to pass back, and using the concrete5 JSON helper.

$obj = new stdClass;
$obj->favoriteColor = 'red';
$obj->name = 'Andrew';
$obj->isAwesome = true;
$js = Loader::helper('json');
print $js->encode($obj);
exit;

This will print out

{"favoriteColor":"red","name":"Andrew","isAwesome":true}

and exit, leaving you to use jQuery's $.getJSON function to parse the string into JavaScript objects that you can do with what you will.

Putting it All Together: Building a "Like This!" Block

Getting a feel for this functionality is hard without a concrete example. That's why I'm releasing a free "Likes This!" block, similar to one we use on concrete5.org. This is a very simple block: it allows logged-in users to say that they "like" a certain page. They are tied to the page, and a page attribute is also incremented to allow pages to be sorted easily by the number of likes that they have received.

This is the default view for those not logged in.

Logged in users receive the ability to like the page.

If they click the link, the result happens inline, dynamically populating the view area and highlighting the div.

Finally, you can view the full list of users who've favorited a page.

This block is available for free from the marketplace here:

http://www.concrete5.org/marketplace/addons/likes-this/

This block is a good demonstration of concrete5's JavaScript abilities, because it features:

1. jQuery UI and concrete5's dialog functionality are included intelligently on page load
2. The block view template intelligently references tools and controller actions.
3. The block automatically includes JavaScript by including view.js in its directory. This JavaScript is used by the block view template.
4. The dialog class is used to pull data in from a tools script, through AJAX.
5. The response from the block's controller action is loaded into the page seamlessly.
6. jQuery UI effects are used.
7. Everything will degrade gracefully even when JavaScript is disabled.

Including the Proper Header Items

The following code in the block's controller file is responsible for including the dialog and jQuery UI code in the header.

public function on_page_view() {
   $u = new User();
   $html = Loader::helper('html');
   $this->addHeaderItem($html->javascript('jquery.js'));
   $this->addHeaderItem($html->javascript('ccm.dialog.js'));
   $this->addHeaderItem($html->css('ccm.dialog.css'));
   if ($u->isRegistered()) {
      $this->addHeaderItem($html->javascript('jquery.ui.js'));
      $this->addHeaderItem($html->css('jquery.ui.css'));
   }
}

Notice, we only include the jQuery UI code if the user who is viewing the page is logged in. Why? Because user's who aren't logged in won't have the ability to "like" a page – so why should we slow their page loading down?

The Block View Template

The block view template is here:

<?php $userLikesThis = $controller->userLikesThis($u); ?>
<?php $c = Page::getCurrentPage(); ?>
<div class="ccm-block-likes-this-wrapper">
   <p>
 
   <? $action = $this->action('like'); ?>
   <? if (!$userLikesThis) { ?><a href="<?=$action?>" 
         class="ccm-block-likes-this-link"><? } ?>
   <img src="<?php echo $this->getBlockURL()."/images/heart.png"; ?>"
       style="float: left; margin-right: 4px" />
   <? if (!$userLikesThis) { ?></a><? } ?>
   <? if ($count > 0) { ?>
      <? $th = Loader::helper('concrete/urls'); 
      $bt = $b->getBlockTypeObject();
      ?>
      <a class="ccm-block-likes-this-link-list" target="_blank" 
         title="<?=t('View User List')?>" 
         href="<?=$th->getBlockTypeToolsURL($bt)?>/list?cID=<?=$c->getCollectionID()?>">
      <?php if($count == 1) {
         echo number_format($count);?> person likes this page.
      <?php }  elseif($count > 1) {
         echo number_format($count); ?> people like this page.
      <?php } ?>
      </a>
 
   <? } ?>
 
   </p>
 
   <p>
 
   <?
   if ($controller->userLikesThis($u)) { ?>
      <strong><?=t('You like this!')?></strong>
   <? } else if ($u->isRegistered()) { ?>
      <a href="<?php echo $action;?>" 
         class="ccm-block-likes-this-link">I like it<?php echo ($count > 0?" too":"");?>!</a>
   <? } else { ?>
      <?=t('You must <a href="%s">sign in</a> to 
         mark this page as one you like.', $this->url('/login', 'forward', $c->getCollectionID()));?>
   <? } ?>
   </p>
 
</div>

The function of this template should be fairly self-explanatory. Basically, we don't include links to like the page if the user is not logged in, or if the user has already said they like the page.

Including JavaScript when the Block is Included

The "Likes This" includes view.js in its folder. By doing so, it ensures that the functions within the view.js file will be automatically included in the page when the block itself is. Here are its contents:

ccm_blockLikesThisSetupList = function() {
   $('a.ccm-block-likes-this-link-list').each(function() {
      $(this).unbind();
      $(this).click(function() {
         var url = $(this).attr('href');
         jQuery.fn.dialog.open({
            href: url,
            modal: false,
            title: $(this).attr('title')
         });      
         return false;
      });
   });
}
 
$(function() {
   $('a.ccm-block-likes-this-link').each(function() {
      $(this).click(function() {       
         var url = $(this).attr('href') + '&ajax=1';
         var elem = $(this).parent();
         $.get(url, function(r) {
            $('div.ccm-block-likes-this-wrapper').before(r).remove();
            $('div.ccm-block-likes-this-wrapper').effect("highlight", {}, 800);
            ccm_blockLikesThisSetupList();
         });         
         return false;
      });
   });
 
   ccm_blockLikesThisSetupList();
});

There is one function defined, and one block of code that automatically runs whenever this block is included in a page. The ccm_blockLikesThisSetupList function locates all links on the page with the ccm-block-likes-this-link class, and finds their URL, and loads them into a concrete5 dialog box. This uses the tools script referenced in the view template.

The automatically loaded event looks for all links with the class ccm-block-likes-this-link, and finds its URL. It appends &ajax=1 to the end of the link, which is then used in the action_like() function to separate those requests called through or AJAX or simply through a POST, and then uses jQuery's $.get() function to submit to the actionlike() method defined in controller.php. Then the HTML rendered by the actionlike() function is inserted into the page, allowing for an instant in-page update of the block itself. Finally, jQuery's highlight effect is used to inform the user that something has changed successfully when they say that they "like" a page.

Learn More

This is a quick introduction to using jQuery and JavaScript with concrete5 on the front-end, but hopefully it should pique your interest and help you start understanding what's possible with such a combination. Here are some links to further sites of interest

http://www.jquery.com

http://www.jqueryui.com

http://www.concrete5.org/marketplace/addons/likes-this/

I'll also be happy to answer questions in the comments.

Andrew Embler wonders how many precious, precious bytes were saved by the switch to jQuery.

Version History of this How-To

• 1.1 - Fixed the $bt->render() to $bt->render('view')
• 1.0 - Initial version

What Does It Do?

The Auto-Nav block is designed to create lists of pages on your site. Based on your criteria, it determines where to pull pages from, how many pages to pull, and in what order to place them. Its stock templates display these pages in a simple unordered HTML list.

Understanding Auto-Nav's Options

The Auto-Nav block exposes the following options:

Pages Should Appear

This option determines the ordering of pages in the Auto-Nav block. The following options are available:

• In their sitemap order / In reverse sitemap order 
  This lists all pages in every level of the resulting tree in the same order (or reverse order) that they are listed in the Dashboard sitemap. This is the most flexible option, as site administrators may reorder pages in the sitemap, and have those changes immediately take effect in all Auto-Nav blocks that are ordered by this option. 
• With the most recent first
  This option lists pages in descending order, with the page that has the greatest public date first. (Note: Public date is the date that the user may change in the Page Properties pane. It is *not* the date that the page was originally added.) 
• With the earliest first
  Like the previous option, except pages are displayed in ascending order, starting with the earliest public date.
• In alphabetical order / In reverse alphabetical order
  Pages are displayed alphabetically (or in reverse alphabetical order) by page name. 

Display pages to users even when those users cannot access those pages

By default, the Auto-Nav block hides any reference to pages that the current site visitor cannot access. This means that a page accessible only to registered users will not appear in an Auto-Nav block for users who are not logged in. This setting will override that behavior.

Display Pages

This option determines the first level at which the Auto-Nav begins showing pages. 

• Top
  The Auto-Nav will begin at the top level of the website. These are the pages directly added beneath the home page (which will automatically be prepended to the results.)
• Second Level / Third Level
  The Auto-Nav will begin at the second or third level of the website. (Note: This only produces results when the page to which the Auto-Nav block is added is at or below the specified level. )
• Above
  The Auto-Nav will begin at the level above the current page.
• Current
  The Auto-Nav will begin at the level of the current page.
• Below
  The Auto-Nav will begin at the level below the current page. 
• Beneath a particular page
  A sitemap selector widget will allow the administrator to determine where this particular Auto-Nav block starts.

Sub Pages to Display

This option controls which sub-pages of the current level will be shown. 

• None
  Pages at the current level (selected in the "Display Pages" section) will be shown, but no sub-pages beneath any of those pages will be displayed.
• Relevant sub-pages
  Any pages that lead to the current page will be shown, but no others will be. *Note*: This option is only valid and useful when beginning the Auto-Nav at a level greater than the current page.
• Display breadcrumb trail
  Only the direct parents of pages that lead to the current page will be shown. (Note: This option is only valid and useful when beginning the Auto-Nav at a level greater than the current page.)
• Display all
  All sub-pages for all pages shown in the nav will be shown. (Note: The pages will still only be shown for as long as the "Sub-Page Levels" option (see next) is valid – so make sure that property is set correctly.)

Sub-Page Levels

For Auto-Nav instances that display sub-pages, this parameter controls how many levels of sub-pages are shown.

• Display sub pages to current
  Displays as many sub-pages as it takes to get to the current page.
• Display sub pages to current + 1
  Displays as many sub-pages as it takes to get to the current page, and then displays the next level of sub-pages beneath the current page.
• Display all
  Displays all sub pages for as long as "Sub Pages to Display" is valid.
• Display a custom amount
  Allows the administrator to set a custom level of sub-pages to display.

Auto-Nav's HTML Markup

The markup created by the regular Auto-Nav is simply an unordered HTML list.

<ul class="nav">
   <li class="nav-path-selected"><a class="nav-path-selected" href="/">Home</a></li>
   <li><a href="/index.php/about/">About</a>
   <ul>
      <li><a href="/index.php/about/press-room/">Press Room</a>
      <ul>
         <li><a href="/index.php/about/press-room/re/">April 1st, 2010 - 5:27 PM</a></li>
         <li><a href="/index.php/about/press-room/white/">April 8th, 2010 - 12:38 PM</a></li>
      </ul>
      </li>
      <li><a href="/index.php/about/guestbook/">Guestbook</a></li>
      <li><a href="/index.php/about/cool-page/">Cool Page</a></li>
   </ul>
   </li>
   <li><a href="/index.php/search/">Search</a></li>
   <li><a href="/index.php/awesome-test/">Awesome Test</a></li>
   <li class="nav-selected nav-path-selected">
      <a class="nav-selected nav-path-selected" href="/index.php/sitemap/">Sitemap</a>
   </li>
</ul>

A few classes of note:

• ul.nav
  The outer UL tag gets the "nav" class in the stock Auto-Nav template.
• ul.nav-header
  The outer UL tag in the "Header Menu" custom template.
• li.nav-path-selected, a.nav-path-selected
  These classes apply to any nodes that contain the current page, from the top on down.
• li.nav-selected, a.nav-selected
  These classes apply to the LI and A tags for the currently active page.

Practical Examples

Here are some common use cases for the Auto-Nav block.

Header Menu

The goal - to list all pages at the top level of a website, in sitemap order, toward the top of a page.

Here is the current setup of the example site in question:

That means we'll want our navigation to list About, Search and Awesome Test, in our Header Nav area. To do this, setup the Auto-Nav block in this way:

That creates the proper menu, but it is styled incorrectly (since our styles are setup to use the "nav-header" unordered list class, and the Auto-Nav typically outputs a list with the class "nav." 

Fortunately, the Header Nav custom Auto-Nav template is setup to output a list with the proper classes, so we change the custom template:

And we get nice results:

Sidebar Sectional Navigation

If we have an "About" page at the top level of our site, and a large amount of content beneath it, it makes sense that we might want to list all pages within the About section on pages beneath it. This is what I refer to as Sectional Navigation. Within this section, we want to show all pages and sub-pages to whatever current page we're on.

Here is an example of some sectional navigation on concrete5.org:

This is a screenshot taken within our About section. Check out the right sidebar. Here we display all sub-pages of our current section (About), all the way on down to whatever current page we happen to be viewing ("concrete5 Adds eCommerce.") Here's how we accomplish that:

Breadcrumb

That same page also contains a breadcrumb navigation element, which the Auto-Nav takes care of. We've wanted to setup the breadcrumb so that it displays parent pages down to the current page, but not the current page itself. 

For that, we start the pages at the top level, display only breadcrumb sub-pages, and display sub-pages to the current page. 

There is a problem, however: that option would *also* display the current page, which is something we don't want to do. Additionally, it would display the items in an unordered list, which – unless we have special styling setup – doesn't look good with a breadcrumb.

The key, then, is to use the included "Breadcrumb" custom template. This will do two things:

1. Ensure that the current page is *not* displayed in the navigation.
2. Print out pages in a row, with pipe signs between them:

Full Sitemap

The Auto-Nav block is frequently used to print out the sitemap for an entire site. 

Just display pages at the top level, and all sub-pages/sub-page levels beneath:

Alphabetical Reference

The following example will show one level of sub-pages directly beneath the current page, sorted alphabetically. 

The result:

News Archive

Let's say we want to show all pages beneath the Press Room section of our website, sorted with the most recent first.

The Result:

Since this block is pulling pages beneath a particular sub-page, it can be added to any area of the site.

Page Attributes

There are two page attributes which affect the behavior of the Auto-Nav. In general, these are all boolean/checkbox types, and are applied directly to the pages you wish to affect (whether from the page in question, or from the Dashboard Sitemap)

• Handle: exclude_nav
  When applied to a page, this page will not appear in the Auto-Nav block view template. It will still be passed to the template, but it will be skipped over.
  
  
• Handle:  replace_link_with_first_in_nav
  When created and applied to a page, if this page is ever encountered in an Auto-Nav view template, the link to the page will be replaced with a link to the first child of the page in question. This is useful for creating pages where you wish to link into a section of a site, instead of being forced to create landing pages for your content. 

Auto-Nav's Block Item Class

At its core, the Auto-Nav block retrieves an array of concrete5 Page objects and makes them available to various templates to display. Each page object is wrapped in the Auto-Nav's custom AutonavBlockItem class, which adds a few extra methods, including the retrieval of which level the current navigation item exists, and the number of pages beneath it. These methods are

• AutonavBlockItem::getName()
  Returns the name of the page.
• AutonavBlockItem::getDescription()
  Returns the page's short description.
• AutonavBlockItem::getURL()
  Returns the URL of the page.
• AutonavBlockItem::getLevel()
  Gets the current level of the navigation item within the nav itself.
• AutonavBlockItem::hasChildren()
  Returns true if the navigation item has children within this navigation (note: currently this will return true even if the item does not display children since they have their exclude_from_nav flags set (see below.))

(Note: Some of these methods did not work properly prior to concrete 5.4.0.6.)

The array of these AutonavBlockItem objects is made available through $controller->generateNav() in the Auto-Nav view template.

Embedding the Auto-Nav Directly into Templates

As with most other concrete5 blocks, the Auto-Nav can be embedded directly into your theme's templates. This can be useful when you'd like to force a header nav or a sidebar nav into your site without having to worry about adding it to every page. Before we switched to using the Superfish Menu, here's how we embedded the header into concrete5.org

$bt = BlockType::getByHandle('autonav');
$bt->controller->displayPages = 'top';
$bt->controller->orderBy = 'display_asc';
$bt->render('templates/header_menu');

And here's another example, embedding the breadcrumb menu:

$bt = BlockType::getByHandle('autonav');
$bt->controller->displayPages = 'top_level';
$bt->controller->orderBy = 'display_asc';
$bt->controller->displaySubPages = 'relevant_breadcrumb'; 
$bt->controller->displaySubPageLevels = 'enough';
$bt->render('templates/breadcrumb'); 

To use the stock view (rather than a custom template), just call render() with no arguments:

$bt->render('view'); 

Further Experimentation

For those who want to experiment further with the Auto-Nav, I recommend doing the following.

1. Create this file in your local blocks directory
   
   
   blocks/autonav/templates/testing.php
2. Open concrete/blocks/autonav/view.php and copy its contents into the file above.
3. Add a new Auto-Nav block somewhere on your site, and apply the "Testing" custom template to it.
4. Hack away at testing.php and at the Auto-Nav block options for as long as you'd like!

Seriously, that's probably the best advice I can give: this how-to should give you some background on the purpose and functionality of the Auto-Nav, but real experimentation is probably the only way you're going to get comfortable with it. But while it may take a little while to become familiar with, it will undoubtedly prove useful (after all, it's been there since the very beginning.)

Andrew Embler hopes your next sitemap can build itself.

One of concrete5's greatest strengths is the way that its pages support in-context editing. This mode is not an afterthought or a bolted-on feature; it is the way that concrete5 has always worked. Site administrators need only visit a particular page, put the page in edit mode, and click and edit to make changes to a page. Changes are made instantaneously. No administrative panel needs to be understood out of the gate.

However, there are times when this approach is not the best way to manage content. For example, when adding pages concrete5 presents itself much like a blank canvas. While this freedom is powerful, certain applications require a bit more structure, and concrete5's approach may take longer than necessary. The solution isn't to ignore concrete5's built-in objects like pages, attributes or page types, but instead to craft a custom interface for creating these pages in a more efficient manner. This tutorial will show you how to do just that.

Required Version

While this tutorial uses screenshots from concrete 5.4.0.5, its approach should work on concrete 5.3.3.1 and above.

Download Code

If you want to skip the tutorial and download the code, you can do so from here.

http://www.concrete5.org/files/2012/7309/4756/example_faq_code.zip (10 KB)

This code is also available as a free add-on in our marketplace.

http://www.concrete5.org/marketplace/addons/example-faq/

Components

I'm going to show you how to build a simple FAQ system for your website. Here are the components of it:

Multiple FAQ Sections

Using a custom attribute, administrators can specify different sections of their site as possible FAQ Entry holders. 

Dashboard Add/Edit Interface

Administrators will be able to use a simplified dashboard interface to add FAQ Entries beneath these categories. 

These FAQ Entries can be pages of any type, leaving their presentation very flexible. Since they are pages, they can be returned in search results and have additional blocks attached to them.

Dashboard List/Filter Interface

The dashboard single page interface lists all FAQ entries added to the site, and allows filtering by section:

Custom Page List

A custom page list template allows administrators to display these pages in an attractive, FAQ-esque way.

Specifying FAQ Sections

The Example FAQ code detailed here uses a custom attribute to determine where FAQs can be added to a particular website. You'll need to create this attribute, then set it to true at one or more pages in your site. Then, those pages will show up as places where FAQ entries may be added.

Create and Assign Required Custom Attributes

From Dashboard > Pages & Themes > Attributes, create a checkbox attribute with the handle "faq_section"

Now, create a select element with the handle faq_tags. (Note: this attribute isn't used in any of our custom views - it is simply here to detail how you can include custom attribute forms in your single pages.)

Finally, assign the FAQ Section attribute to at least one page in your site.

Creating the Single Page

Our dashboard interface for listing and editing FAQ entries will be found at

http://www.yoursite.com/index.php/dashboard/example_faq/

The first thing we'll want to do is register this URL with concrete5. To do so, first we create code files for the single page's view layer, and its controller. These files can be empty at first – they just need to exist.

Create the View Layer

Within your site's single_pages/ directory, create a folder named "dashboard," then a folder named "example_faq", and within it, place an empty view.php file.

Create the Controller

Within your site's controllers/ directory, create the same structure, but instead of creating a file named view.php, name it controller.php

Add Controller Code to Your Controller

Some code needs to be added to your controller file before we can proceed with the installation of your new single page. Add this code to your empty controller file:

<?php
    class DashboardExampleFaqController extends Controller {
 
    }

This code simply tells concrete5 the name of the controller class. It must be named and capitalized this way! (Note: capitalization is important.) Simply take the path of the directories you're using, replace any underscores with additional punctuation, and add Controller on the end of the class. Make sure it your class extends the Controller class.

Install the Single Page

Now that the code files are in their proper place, you need to register the single page with concrete5 before it shows up in the dashboard. This is done in the Dashboard > Pages & Themes > Single Pages area of your dashboard. Simply scroll to the bottom and enter the path to your new single page in the form field:

Submit the form, and your page should show up in the dashboard in the left menu. Click on it, and you should have a blank page in the dashboard available to you.

Controller Code

Now it's time to populate the DashboardExampleFaqController class with real code.

Setup

Now that you have blank controller and view files, it's time to add code to them, so that they can do things like retrieve pages, list pages, and add pages. Add the following methods to the controller.php file:

    public $helpers = array('html','form');

This declaration loads the Html and Form helpers found in concrete/helpers/, and sets them in the view.php file. This means that helper objects named $html and $form, respectively, will be available. (This is simply a shorthand way of specifying which helpers are available in a controller's associated view.)

    public function on_start() {
        Loader::model('page_list');
        $this->error = Loader::helper('validation/error');
    }
 

The on_start() method fires automatically every time the associated controller is run. (Note: this is slightly different than the __construct() method - on_start() will only ever be run when the page is actually rendered as a view. Here we load the PageList class, and setup ValidationErrorHelper object within our controller.

View

    public function view() {
        $this->loadFAQSections();
        $faqList = new PageList();
        $faqList->sortBy('cDateAdded', 'desc');
        if (isset($_GET['cParentID']) && $_GET['cParentID'] > 0) {
            $faqList->filterByParentID($_GET['cParentID']);
        } else {
            $sections = $this->get('sections');
            $keys = array_keys($sections);
            $keys[] = -1;
            $faqList->filterByParentID($keys);
        }
        $this->set('faqList', $faqList);
        $this->set('faqResults', $faqList->getPage());
    }
 
    protected function loadFAQSections() {
        $faqSectionList = new PageList();
        $faqSectionList->filterByFaqSection(1);
        $faqSectionList->sortBy('cvName', 'asc');
        $tmpSections = $faqSectionList->get();
        $sections = array();
        foreach($tmpSections as $_c) {
            $sections[$_c->getCollectionID()] = $_c->getCollectionName();
        }
        $this->set('sections', $sections);
    }

The first two methods we include in our controller are responsible for loading data within the view layer. The Controller::view() method is automatically run when a particular single page is viewed. That means the moment we come to index.php/dashboard/example_faq/, our view() method is run. First, it runs the loadFAQSections() method, which sets a $sections array filled with all pages that have been marked as FAQ Sections (using the faq_section attribute detailed earlier.) Then, it creates a new PageList object that retrieves all pages within any of these sections, and sets up paging on it. Finally, the list of pages and the PageList object itself are set within the view using Controller::set(), so those variables will be accessible within view.php

Edit

The edit() function will be fired when we edit a particular FAQ entry using this single page interface (e.g. http://www.yoursite.com/index.php/dashboard/example_faq/edit/200)

    public function edit($cID) {
        $this->setupForm();
        $faq = Page::getByID($cID);
        $sections = $this->get('sections');
        if (in_array($faq->getCollectionParentID(), array_keys($sections))) {
            $this->set('faq', $faq);    
        } else {
            $this->redirect('/dashboard/example_faq/');
        }
    }
 
    protected function setupForm() {
        $this->loadFAQSections();
        Loader::model("collection_types");
        $ctArray = CollectionType::getList('');
        $pageTypes = array();
        foreach($ctArray as $ct) {
            $pageTypes[$ct->getCollectionTypeID()] = $ct->getCollectionTypeName();      
        }
        $this->set('pageTypes', $pageTypes);
        $this->addHeaderItem(Loader::helper('html')->javascript('tiny_mce/tiny_mce.js'));
    }

First, we run setupForm(), which takes care of loading available FAQ sections, as well as getting an array of all page types installed on a site, and adding our rich text editor JavaScript. Then, we get information about the requested FAQ Entry, validate that it appears in the proper location, and set the $faq object in the view layer.

Add/Update

The add() function is fired when the add interface is displayed and/or submitted (e.g. http://www.yoursite.com/index.php/dashboard/example_faq/add/). 

    public function add() {
        $this->setupForm();
        if ($this->isPost()) {
            $this->validate();
            if (!$this->error->has()) {
                $parent = Page::getByID($this->post('cParentID'));
                $ct = CollectionType::getByID($this->post('ctID'));             
                $data = array('cName' => $this->post('faqTitle'), 
                'cDescription' => $this->post('faqDescription'), 
                'cDatePublic' => Loader::helper('form/date_time')->translate('faqDate'));
                $p = $parent->add($ct, $data);  
                $this->saveData($p);
                $this->redirect('/dashboard/example_faq/', 'faq_added');
            }
        }
    }
 

First, we setup the form. If we're not posting the form, then no further action is required. If the form is a post, however, that means we're submitting a new FAQ Entry into our system. That means we need to validate it using the validate() function (which will be shown later.) If the validate function passes, that means we're posting valid information, so we grab the parent page specified, grab the page type specified, and add a page of the specific type. Then we call a custom saveData() method (shown later) which takes care of setting up custom attributes like tags, and body content. Then we redirect the user to http://www.yoursite.com/index.php/dashboard/example_faq/faq_added/

The update() function is run when an existing FAQ Entry is updated. It is very similar to add() but takes an existing page ID:

    public function update() {
        $this->edit($this->post('faqID'));
 
        if ($this->isPost()) {
            $this->validate();
            if (!$this->error->has()) {
                $p = Page::getByID($this->post('faqID'));
                $parent = Page::getByID($this->post('cParentID'));
                $ct = CollectionType::getByID($this->post('ctID'));             
                $data = array('ctID' =>$ct->getCollectionTypeID(), 
                    'cDescription' => $this->post('faqDescription'), 
                    'cName' => $this->post('faqTitle'), 
                    'cDatePublic' => Loader::helper('form/date_time')->translate('faqDate')
                );
                $p->update($data);
                if ($p->getCollectionParentID() != $parent->getCollectionID()) {
                    $p->move($parent);
                }
                $this->saveData($p);
                $this->redirect('/dashboard/example_faq/', 'faq_updated');
            }
        }
    }

First we run the edit function on the posted faqID variable, then we run validate. If there are no errors, we update the page, move it if necessary, and handle redirection.

Validation

    protected function validate() {
        $vt = Loader::helper('validation/strings');
        $vn = Loader::Helper('validation/numbers');
        $dt = Loader::helper("form/date_time");
        if (!$vn->integer($this->post('cParentID'))) {
            $this->error->add(t('You must choose a parent page for this FAQ entry.'));
        }           
 
        if (!$vn->integer($this->post('ctID'))) {
            $this->error->add(t('You must choose a page type for this FAQ entry.'));
        }           
 
        if (!$vt->notempty($this->post('faqTitle'))) {
            $this->error->add(t('Title is required'));
        }
 
        if (!$this->error->has()) {
            Loader::model('collection_types');
            $ct = CollectionType::getByID($this->post('ctID'));             
            $parent = Page::getByID($this->post('cParentID'));              
            $parentPermissions = new Permissions($parent);
            if (!$parentPermissions->canAddSubCollection($ct)) {
                $this->error->add(
                    t('You do not have permission to add a page of that type to that area of the site.')
                );
            }
        }
    }
 

The validate function is run by both add() and update(), and checks the post array to ensure that the FAQ entry in question has valid properties. First, we check to ensure that a parent ID is passed through post, a valid page type ID is passed, a valid title, and then we check permissions to ensure that the user has the ability to add to the particular location. If any of these fail, we add a text error to the $this->error object we instantiated in on_start() above (more on this below.)

saveData($p)

This function is run by both add() and update(), and is responsible for saving body content, and setting custom attributes on the page in question. It is passed the page object.

    private function saveData($p) {
        $blocks = $p->getBlocks('Main');
        foreach($blocks as $b) {
            $b->deleteBlock();
        }
 
        $bt = BlockType::getByHandle('content');
        $data = array('content' => $this->post('faqBody'));
        $p->addBlock($bt, 'Main', $data);
 
        Loader::model("attribute/categories/collection");
        $cak = CollectionAttributeKey::getByHandle('faq_tags');
        $cak->saveAttributeForm($p);        
    }

The first bit of code is responsible for clearing out any existing blocks in the Main area. The second saves a block of type content into the Main area array, and the third is responsible for grabbing the submitting 'faq_tags' attribute form, and saving it against the page.

Error and Success Display

The following methods are those that display success and error messages to the end user.

    public function faq_added() {
        $this->set('message', t('FAQ added.'));
        $this->view();
    }
 
    public function faq_updated() {
        $this->set('message', t('FAQ updated.'));
        $this->view();
    }
 
    public function on_before_render() {
        $this->set('error', $this->error);
    }
 

The faq_added() and faq_updated() methods are automatically run when the user is redirect to http://www.yoursite.com/index.php/dashboard/example_faq/faq_added or http://www.yoursite.com/index.php/dashboard/example_faq/faq_updated/, respectively. They simply set the $message variable in the view layer, which is automatically displayed in a nice fashion by our dashboard theme. Beyond setting this variable, no further action is required. Finally, the on_before_render() function will be called immediately prior to exiting the controller and rendering the view. It sets the $error variable in the Dashboard theme. If this error object has any errors – such as those tripped by the validate() function above – they will be displayed in a nice list automatically.

View Code

The following code goes into view.php. It directly interacts with any variables set within the controller.

Create view vs. add/update sections

The same view.php file will be displayed whether a user is listing all FAQs or add/updating one. That means we need to create a single outer loop which displays certain content depending on the current task.

    <? if (($this->controller->getTask() == 'update' || 
         $this->controller->getTask() == 'edit' || 
         $this->controller->getTask() == 'add')) { ?>
 
    <? } else { ?>
 
    <? }?>
 

The top half of the if statement will show in add/edit/update mode, and the bottom half will show in all other cases. We place the adding/editing form in the first section, and the listing form in the second.

Add/Edit/Update Form

This code should be pasted within the first section of the loop above.

    <? 
    $title = $this->controller->getTask() == 'add' ? t('Add') : t('Update');
    $df = Loader::helper('form/date_time');
 
    if (is_object($faq)) { 
        $faqTitle = $faq->getCollectionName();
        $faqDescription = $faq->getCollectionDescription();
        $faqDate = $faq->getCollectionDatePublic();
        $cParentID = $faq->getCollectionParentID();
        $ctID = $faq->getCollectionTypeID();
        $faqBody = '';
        $eb = $faq->getBlocks('Main');
        if (is_object($eb[0])) {
            $faqBody = $eb[0]->getInstance()->getContent();
        }
        $task = 'update';
        $buttonText = t('Update Entry');
    } else {
        $task = 'add';
        $buttonText = t('Add FAQ Entry');
    }
 
    ?>
 
    <div style="width: 760px">
 
    <h1><span><?=t('FAQs')?></span></h1>
    <div class="ccm-dashboard-inner">
 
    <h2><span><?=$title?> FAQ Entry</span></h2>
 
    <form method="post" action="<?=$this->action($task)?>" id="faq-form">
    <? if ($this->controller->getTask() != 'add') { ?>
        <?=$form->hidden('faqID', $faq->getCollectionID())?>
    <? } ?>
 
    <strong><?=$form->label('faqTitle', t('Question'))?></strong>
    <div><?=$form->text('faqTitle', $faqTitle, array('style' => 'width: 730px'))?></div>
    <br/>
    <strong><?=$form->label('faqDescription', t('Brief Answer'))?></strong>
    <div><?=$form->textarea('faqDescription', $faqDescription, 
              array('style' => 'width: 730px; height: 100px'))?></div>
    <br/>           
    <strong><?=$form->label('cParentID', t('Section'))?></strong>
    <? if (count($sections) == 0) { ?>
        <div><?=t('No sections defined. 
            Please create a page with the attribute "faq_entry" set to true.')?></div>
    <? } else { ?>
        <div><?=$form->select('cParentID', $sections, $cParentID)?></div>
    <? } ?>
<br/>
 
    <strong><?=$form->label('ctID', t('Page Type'))?></strong>
    <div><?=$form->select('ctID', $pageTypes, $ctID)?></div>
    <br/>
    <strong><?=$form->label('faqDate', t('Date/Time'))?></strong>
    <div><?=$df->datetime('faqDate', $faqDate)?></div>
    <br/>
    <strong><?=t('Full Answer')?></strong>
    <?php Loader::element('editor_init'); ?>
    <?php Loader::element('editor_config'); ?>
    <?php Loader::element('editor_controls', array('mode'=>'full')); ?>
    <?=$form->textarea('faqBody', $faqBody, 
          array('style' => 'width: 100%; height: 150px', 'class' => 'ccm-advanced-editor'))?>
    <br/>
    <? 
    Loader::model("attribute/categories/collection");
    $akt = CollectionAttributeKey::getByHandle('faq_tags');
    if (is_object($faq)) {
        $tvalue = $faq->getAttributeValueObject($akt);
    }
    ?>
    <div class="faq-attributes">
        <div>
            <strong><?=$akt->render('label');?></strong>
            <?=$akt->render('form', $tvalue, true);?>
        </div>
    </div>
 
    <br/>
 
    <?
 
    $ih = Loader::helper('concrete/interface');
    print $ih->button(t('Cancel'), $this->url('/dashboard/example_faq/'), 'left');
    print $ih->submit($buttonText, 'faq-form');
    ?>
    <div class="ccm-spacer"> </div>
 
    </form>
 
    </div>
    </div>

This code is responsible for creating the add/update interface. It is unified for both add and update, meaning that if a valid $faq object is present, the fields will be loaded in, otherwise they will be blank. This code provides good examples of using our form helper to create textarea and text elements, loading the rich text editor, and rendering the form view for a custom attribute. While we include just the FAQ Tags custom attribute, any number and any type of custom attribute can be included in a single page interface. The code provided here will display any of the attribute types, and save them properly against the page automatically.

Finally, we load the concrete interface helper to present submit and cancel buttons to the user in the concrete5 style.

View List

The second bit of code in view.php is responsible for listing all existing FAQs. Paste this code within the second half of the loop created above.

    <h1><span><?=t('FAQs')?></span></h1>
    <div class="ccm-dashboard-inner">
    <h2><?=t('New FAQ')?></h2>
    <a href="<?=$this->action('add')?>"><?=t('Click here to add a new FAQ Entry >')?></a>
    <Br/><br/>
 
    <h2><?=t('View/Search FAQs')?></h2>
 
    <form method="get" action="<?=$this->action('view')?>">
    <?
    $sections[0] = '** All';
    asort($sections);
    ?>
 
    <strong><?=$form->label('cParentID', t('Section'))?></strong>
    <div><?=$form->select('cParentID', $sections, $cParentID)?>
    <?=$form->submit('submit', 'Search')?>
    </div>
    </form>
    <br/>
    <?
    $nh = Loader::helper('navigation');
    if ($faqList->getTotal() > 0) { 
        $faqList->displaySummary();
        ?>
 
    <table border="0" class="ccm-results-list" cellspacing="0" cellpadding="0">
        <tr>
            <th class="<?=$faqList->getSearchResultsClass('cvName')?>">
                <a href="<?=$faqList->getSortByURL('cvName', 'asc')?>"><?=t('Name')?></a>
            </th>
            <th class="<?=$faqList->getSearchResultsClass('cDateAdded')?>">
                <a href="<?=$faqList->getSortByURL('cDateAdded', 'asc')?>"><?=t('Date Added')?></a>
            </th>
            <th class="<?=$faqList->getSearchResultsClass('cvDatePublic')?>">
                <a href="<?=$faqList->getSortByURL('cvDatePublic', 'asc')?>"><?=t('Public Date')?></a>
            </th>
            <th><?=t('Page Owner')?></th>
            <th> </th>
        </tr>
        <?
        foreach($faqResults as $cobj) { ?>
        <tr>
            <td><a href="<?=$nh->getLinkToCollection($cobj)?>">
                 <?=$cobj->getCollectionName()?></a>
            </td>
            <td><?=$cobj->getCollectionDateAdded()?></td>
            <td><?=$cobj->getCollectionDatePublic()?></td>
            <td>
                <? 
                $user = UserInfo::getByID($cobj->getCollectionUserID());
                print $user->getUserName();
                ?>
            </td>
            <td><A href="<?=$this->url('/dashboard/example_faq', 'edit', 
                  $cobj->getCollectionID())?>"><?=t('Edit')?></a>
            </td>
        </tr>
        <? } ?>
 
        </table>
        <br/>
        <?
        $faqList->displayPaging();
    } else {
        print t('No FAQ entries found.');
    }
    ?>
    </div>

Here we can see links to the add interface, a list for filtering, and finally a table that shows all selected pages and offers some basic sorting.

A Custom Page List Template

Finally, let's create a custom FAQ-styled template for the Page List block. That way, anywhere we add the Page List block, we'll be able to style it like this:

By clicking on the title of a FAQ entry, the short description will display, along with a link to the full answer.

Create a Custom Template Directory

In the root of your site, create a directory named blocks/page_list/templates/example_faq_page_list/, and within it a file named view.php

The following code goes into view.php

    <?php
 
    if (count($cArray) > 0) { ?>
 
    <table border="0" cellspacing="0" cellpadding="0">
    <? foreach($cArray as $cobj) { ?>
 
    <tr id="f<?=$cobj->getCollectionID()?>">
        <td valign="top">
            <div style="width: 20px; text-align: center"><strong>Q.</strong></div>
        </td>
        <td valign="top" style="width: 100%">
            <a href="javascript:void(0)" onclick="toggleFAQEntry('<?=$cobj->getCollectionID()?>')">
                <?=$cobj->getCollectionName()?>
            </a>
        </td>
    </tr>
    <tr id="fa<?=$cobj->getCollectionID()?>" style="display: none">
        <td valign="top"><div style="width: 20px; text-align: center">
                <strong style="color: #666">A.</strong></div></td>
        <td>
        <div class="faq-entry-description">
            <?=$cobj->getCollectionDescription()?>
            <a href="<?=$nh->getLinkToCollection($cobj)?>" 
                style="font-weight: bold">Read More ></a>
        </div>
        </td>
    </tr>
    <tr>
        <td colspan="2"><br/></td>
    </tr>
 
    <? } ?>
 
    </table>
 
    <? } ?>
 

Followed by

    <script type="text/javascript">
    toggleFAQEntry = function(item) {
        var desc = $('#fa' + item);
        if (desc.css('display') == 'none') {
            desc.fadeIn(200);
        } else {
            desc.hide();
        }
    }
    </script>
 

This is simply a repurposed view.php from the existing core Page List block. Instead of showing the description, we keep the description hidden and create a custom JavaScript method that fires when clicking on the FAQ question.

Add a Page List and Apply the Custom Template

Add the Page List block on your various FAQ Section pages, configure them to show their child pages, and then assign this custom template to them. 

And that's it!

Conclusion

At this point you should see easy it is for a developer to create a fully interactive, full-featured editing interface for pages, using the concrete5 single page approach. Your administrative users will be able to add and edit FAQ entries without interacting with the front-end interface at all. Pages are still created, meaning that they can be moved, updated, tweaked and customized using existing concrete5 editing interfaces, themes and add-ons. 

Download

Click here to download the code found in this example. (10 KB)

This code is also available as free add-on in our marketplace

http://www.concrete5.org/marketplace/addons/example-faq/

Andrew Embler likes showing off what can be done with concrete5.

I use Disqus web comments on this site. They're great: they handle threading, login from multiple sources, monitoring and post by email, user avatars, and some other things that I'm glad I don't have to deal with. Each page contains a snippet of JavaScript that, when loaded, sends the page's URL to the Disqus servers, and retrieves any comments posted against that URL.

I'd had no problems with this setup until just the other day, when I received notification of a new comment to an article, and I could not for the life of me locate the comment on the page. The article had fourteen comments, and yet only thirteen displayed, the latest from a month or two ago. I was apparently dealing with a phantom comment. Frustrated, I logged into the main disqus.com website, where I was able to locate the comment, alongside all the others. According to Disqus, it was approved and active on the page. But where was it?!

The clue came when I looked at the story to which the comment was attached. All fourteen comments were attached to "andrewembler.com :: Optimizing your concrete5 Website for the iPhone" – but the thirteen that displayed linked to that story here:

http://andrewembler.com/concrete5/optimizing-your-concrete5-website-for-the-iphone/

While the orphaned comment linked to it here:

Sure enough, when I visited that URL, the same article rendered, but with one comment – the new comment – instead of the other thirteen. Since Disqus provides no move tools, this comment is stuck on this page. But I can make sure that this doesn't happen again.

Background: the cID

Every page of content added to a concrete5 website has one unique ID attached to it. This is referred to as the collection ID, and is frequently abbreviated in functions and URLs as "cID." Why "collection" ID, rather than "page" ID? Originally, when concrete5 first came into being in late 2003, its pages were referred to as Collections – since they were thought of as collections of blocks. As concrete5 matured and started using attributes, themes, page types and more complex objects, we thought just calling them pages – which is, after, what they are – was less of a barrier to entry. The "cID" parameter is still actively used, however, and it's this cID which makes its unsightly appearance in the URL above. 

Basically, my concrete5 iPhone article can be accessed at two URLs. The cID URL, which loads the article based on its ID in the database, and the full SEO-friendly URL. (Note: you may have more than one URL as well, but since concrete5 5.3 they redirect to the canonical URL.) Why? In concrete5, pages can be created well before their actual canonical URL is chosen. Most concrete5 navigation and linking tools will link directly to the canonical URL, but somehow, if a user stumbles on the cID URL, the page will still render without redirection. Usually this isn't a problem, but as we've seen in my example, it can lead to some very undesirable situations. I'm going to show you how to fix that.

The Task

I want to ensure that a comment can never be mis-posted again. I've already fixed as many areas in the concrete5 core that link to the cID URL of pages, but there's still no telling what people might accidentally link to or stumble upon. I need something that will redirect them if they land on a page via its cID URL.

This can't be too greedy, however: the cID-powered URL is used very, very frequently while concrete5 sites are in edit mode. What I really want is this: if a user comes to any page on my site by way of the cID URL, and they are not logged in (i.e - they're not editing a page), they should be redirected to that page's canonical URL via a 301 redirect.

Step 1: create config/site_post.php

There are a number of ways to accomplish our goal. I've already mentioned concrete5's events system in previous articles, so here I'm going to take an even simpler approach, and introduce you to config/site_post.php. This is an optional file that site owners may create in their local config/ directory that will automatically be loaded after all configuration files and database connections have been made. This lets us hook into concrete5's loading process relatively early. Note: theme information and some other core information about a request will not be available this early, but for our purposes it should work nicely.

Step 2: Add Code

Once you have an empty file at config/site_post.php, add this code to it:

<?php
   $req = Request::get();
      if ($req->getRequestCollectionID() > 1 && $req->getRequestPath() == '' 
         && $_SERVER['REQUEST_METHOD'] != 'POST') {
      // This is a request that is directly for the cID, rather than the path
      $u = new User();
      // If the user is logged in we do NOT redirect
      if (!$u->isRegistered()) {
         // Get the page object for the current cID
         $c = Page::getByID($req->getRequestCollectionID());
         if (!$c->isError()) {
            $nav = Loader::helper('navigation');
            header ('HTTP/1.1 301 Moved Permanently');
            header('Location: ' . $nav->getLinkToCollection($c, true));
            exit;
         }
      }
   }
 

Let's walk through exactly what's happening here:

• Lines 1-4: First, we grab the concrete5 Request object. Then, we check that object to see if the current request is for a cID, and the current request has a null path. We ensure that the current request's cID is greater than one, so that our home page (which is always a cID request, since it has no path) will be ignored in this check. Update: we also check to make sure we're not doing a POST (see note in the comment).
• Lines 5-8: If this is the case, we want to proceed with our redirection. We then instantiate the User object, and check to see that the current User object is not logged in. If the user is not logged in, we proceed with our redirection routine.
• Lines 9-11: Now, we grab the page object for the current requested page ID, and check to ensure that there's no error associated with this page object. Additionally, we make sure that the page object does, in fact, have a valid path (since if it didn't, we'd get stuck in an infinite redirect loop.) If that's the case, then...
• Lines 12-15: We load up our navigation helper, issue a permanently moved header (for the benefits of any search engines following these links) and we redirect the URL to the canonical URL for the page.

Step 3: Profit!

Try it for yourself:

This is the URL that was causing so many problems before. Hopefully the orphaned comments are a thing of the past.

Yes, we ought to include something like this in the core – but as you've seen here, it's not a perfect solution, and could cause problems for certain sites. For example, this wouldn't work on sites that include community functionality that use logged-in users frequently. But on a blog or a site where the only logged-users are those who edit the site, it should be a nice, useful snippet of code to keep you, your readers and your search engine robots happy.

Andrew Embler hopes you're reading this at one – and only one – URL.

Apple and its iTunes App Store have been getting a lot of negative press amongst developers lately. Its stance against the use of private APIs, the introduction of its own ad network, and its rewording of the iPhone Developer agreement to exclude third party runtimes and cross-compilation tools has gotten a lot of people angry. Gizmodo calls ads an iPhone user's "worst enemy"; an official Adobe representative invited Apple to "go screw itself". Apparently, even Steve Jobs could sense something was brewing, and he actively responded to one of the more reasonable pleas regarding the situation. 

Do I agree with all of the criticism coming Apple's way? Hardly. In fact, I just published an article in which I defend Apple on its stance regarding private APIs. I'm sympathetic to what they're trying to do, and I understand the challenges inherent in it. I don't dismiss advertising out of hand. Additionally, I'm not one to blindly dismiss a company's choices without trying to understand why they make them. 

In fact, I was going to let the situation blow over without comment, content that the entire thing was a ginned-up controversy for the sake of page views (*cough* Gizmodo *cough*), until I stumbled on to this:

Ars Technica: Apple's Wager, by John Siracusa

I didn't agree with everything in it, and many of the comments attached to it are inane, but I felt compelled to read it regardless, as its by the estimable Siracusa. He's always been one of Apple and Mac OS's greatest ambassadors and thoughtful technology writers, a fact to which anyone who's read his fantastic reviews of every OS release can attest. And yet, in this article he describes the development environment created by Apple as "shoddy" and full of "hardships." 

That, my friends, is troubling. When the reasonable and thoughtful defenders of your platform start to become concerned with your direction and methods, it may not matter whether your concerns are ultimately right. Apple would do well to take a step back and listen to the concerns of some of these folks. It's not like they haven't done so before. 

Andrew Embler still wants an iPad.

In the wake of the generally positive iPad reviews circulating the web, a light developer backlash has occurred, in the form of grousing about private APIs. Of course, developer backlash around recent Apple products is not new: the moment the iPhone was announced, developers went ballistic that the recommended platform of choice was web apps; after a native app store was released, the protests turned to the byzantine and often arbitrary nature of its approval process. Now, with the iPad, it appears that there is something new to contest. 

Background: what are "Private APIs" ?

Software systems that open themselves up to third party development provide ways by which developers may use built-in frameworks and libraries to build their applications. These are "application programming interfaces," or APIs. Public APIs are publicly accessible and documented, whereas private APIs – while still perhaps technically available to third party developers – are not. 

It's important to note that there is very little that separates a public API from a private one, beyond the fact that the public is documented, and "blessed." By blessed, I mean that that interface has been documented and described in the hopes that developers will use it, and with the implicit understanding that it is not likely to change in an incompatible way any time soon. Private APIs offer no such guarantee. If developers can find them, they can technically use them – but there is nothing stating that they won't just disappear the next time the core software is updated. For their own safety, third party developers ought to tread lightly. Private APIs are generally regarded as unfinished, half-baked, and likely subject to change.

Software products that encourage add-ons don't want their third party developers to use private APIs, because that frequently leads to third party software that requires frequent updates, any time the underlying core is changed. For example, on Mac OS X there are a number of "haxies" – software programs which modify OS X's appearance or low level behavior in ways Apple hasn't foreseen or blessed. Users install this software because they aren't completely happy with the way OS X functions. To do what they do, these programs take advantage of functionality that Apple hasn't documented for the outside world. The result? Whenever updating OS X, make damn sure you check to see that there's an update to all this third party software first, because it's quite likely that the private APIs have changed in some way, and updating the core will lead to an unstable or unworking system.

Enter the App Store

The micromanagement of the updating process as described above is tedious. Even worse, most computer users will fault the OS for breaking their favorite extensions, when in fact their extensions are built on a shifting foundation. But with the iPhone and iPad app store, Apple has implicitly guaranteed that their device is more an appliance than a typical computer system, and appliances can't require this same level of maintenance. They have to "just work." That's why Apple has rejected apps from the app store which use private APIs. Most developers will tell you that's reasonable. 

Do as I say (not as a I do)

Then what's the problem? Apple has apps, within the app store, which use private APIs! Why does Apple get to play by a different set of rules than third party developers?! 

This seems like a reasonable complaint, right? Obviously, Apple can do what they want with their store, but isn't that somewhat skeezy (for lack of a better term?)

No. It's necessary.

If you'll permit me, I'm going to proceed with a tangent. In concrete5 version 5.2, we introduced a new class named PageList. This class was meant to provide an object-oriented and extendable way to search and filter pages, and replace the ailing, old and poorly thought-out CollectionSearch class. While we did have portions of the PageList class documented when it was released, we didn't release official documentation for it until just recently.

Why? Simply put, the class wasn't ready. It was 80% of the way, but we knew that underlying frameworks that the class referenced weren't totally stable, and that the class and its API were likely to change. It wouldn't be smart for us to recommend third party developers use and rely on this API when we know its still in flux. 

And yet, did that stop us from using the class in production and throughout the core, where applicable? No. Why? Two reasons: 1) we needed to put it through its paces, and 2) real artists ship! We needed to get 5.2 out there, and we couldn't spend the time exhaustively documenting and planning the entirety of the class, especially as we knew it would eventually interact with entire libraries and objects that hadn't even been planned yet. We needed to use code in projects and add-ons to see where the class fell short, and what it needed.

Fundamentally, I imagine Apple – and the iPad project in particular – is no different. When the word comes from on high that the project, including its apps, must be ready, who's going to tell Steve Jobs that the APIs used by the iBooks app need to be completely set in stone, documented, and shared with the developer community? Heh, you first! Instead, the team packages up what they have and uses it as a starting point, and the private APIs evolve organically into the public ones! Ship first, refine, improve, and then publish. That way, you'll see where you application interface needs tweaking and fixing. Far better to iron out the kinks before the API is published and made available to third party developers, than release the documentation too early, and have a slew of apps that require updates when an update to the API breaks them. 

In Conclusion

To the developers bashing Apple over this, I'd ask you to consider the position of the framework manager, or the manager of the entire iPhone OS ecosystem. Step outside of the ideal world and start thinking pragmatically. Yes, there are some very valid concerns regarding Apple and its handling of the app store, but I don't think this is one of them. Besides – it sounds like there's already something brewing that makes this seem like small potatoes.

Andrew Embler loves having enough time to completely and thoroughly design every single aspect of concrete5's third party interfaces – but rarely, rarely gets it.

Make Time for Lunch

So, we get into Austin on Friday. We set up. Everything is ready. Saturday, the trade show opens, and we're rocking it. Giving away stickers. People are interested in our CMS. Making connections. Truly, having it all. Well, with the exception of lunch, which completely dropped off our radar. 

This was a mistake. Yeah, we had some energy bars, but those don't count. In spite of all the material we'd read, the trade show actually ended at 6:00 PM, rather than 5:00 PM. Turns out this extra hour matters: at 6:30 we were so tired that we ate in silence. Didn't derail the entire evening, but it came damn close.

However, with this in mind, note the following sub-tip:

Monster® Brand Energy Drink is not an Acceptable Substitute for Lunch or a more Modest Cocktail Mixer

It will, however, totally fulfill its intended purpose. But this blast of energy comes with a terrible price (and not just the $5.50 an entire can costs from the vendor): when the time comes that you want to sleep, you will be unable to do so. And should you actually fall into some semblance of slumber, your dreams will be dizzying, frenetic affairs replete with visceral altercations. After the opening night party, during which I drank a fair amount of Vodka mixed with this crazy chemical, I had no fewer than four dreams featuring fights, brawls, wrestling, slamming and generally boorish behavior. At least, I'm pretty sure those were dreams. 

Mark my words: nights after enjoying this concoction are no respite. 

Wear Comfortable Shoes

This seems obvious, but I'm going to state it anyway. There's going to be a lot of standing around in your future, and your feet will thank you. Again: comfortable doesn't mean that you can wear them without them causing problems. Comfortable means comfortable. I wore some shoes that I didn't think twice about, and at the end of the first day my legs were nothing but knots. By contrast, throughout the rest of the trade show I wore shoes I actively consider comfortable (but still stylish, natch), and these problems were greatly lessened.

I'm going to retreat from the general advice and get deep into some business. Some might disagree with me on this, but hear me out: your pitch doesn't really matter. For example, we had some carefully scripted demos planned, including a scheduled time to show off the interface to a larger group of people. We never did this. And even the individual demos became something we worked with as a last resort. Instead, it's better to engage with a person, figure out what they do, and inform them how your stuff can improve that experience. If it can't, be honest and move on. 

I know this advice isn't terribly insightful, but given my stroll around the trade show floor, I know there are those out there who'd benefit from it. 

If you can, Stay Near the Action

This year, the four of us stayed at a vacation rental about five miles outside the city center. I'd consider this a mistake. In truth, I'm torn on this, because the rental was nice. But I feel like we made this choice considering Austin similar to Portland, which, when it comes to transportation, it definitely is not. The website for the bus is pretty nice, but the actual buses themselves looked a little dubious to our eyes. Additionally, the traffic during rush hour is maddening, as are the highways themselves. Staying in downtown gives you so much flexibility that next time I'd really have to be persuaded to do otherwise. 

Granted, we needed a car to ferry equipment to the exhibit hall, which means we couldn't get by without renting one. Additionally, I am (thankfully!) fairly removed from the specifics of the financials as they differ from hotel to rental, but I can imagine the savings were substantial. I will however still state that they are not without their own alternate cost.

Try and Catch a Session Or Two

We were busy. Actually, hold on: we were very busy. So it's not surprising that I wasn't able to make it to any of the sessions. But I do have a bit of regret regarding that decision. True, we are pretty certain we have this industry figured out, especially regarding our own corner of it, but that's no excuse to get complacent. Companies do that, and they get beaten. So keeping an open mind, an open calendar, and taking a chance to network outside of the exhibit hall probably would have been valuable in some way.

Be Flexible

This relates to my previous point: please, please, please, above all else, be flexible. I didn't go to any sessions, even though I had specifically marked them in my handy SXSW calendar. But you know what? I didn't do anything that I had put in my calendar! Not various keynotes, nor the parties. Yes, we went to parties, met some great people and generally had a great time, but nothing seemed to ensure me not doing something quite as well as me taking the time to put it in my calendar. 

The lines are long, and there's so much to do that if you try and stack up a calendar to catch everything, you're either going to spend very little time at each of the things you want to do, or you're going to miss certain things. It's going to happen. Roll with it and enjoy yourself. We did.