new skinning support and events API make wagns more customizable than ever.


Wagn helps savvy web users do things previously only developers could do.  With its new skinning system and key improvements to handling of inclusions, Wagn 1.12 takes this pattern even further.  But it also empowers developers in vital new ways with its new events API and RESTful Web API.


All of these are bringing us much closer to Decko 1.0, which is focused on two key goals:

  1. discoverability and usability for readers, editors, and Wagneers
  2. extensibility for developers

The roadmap to 2.0 now includes just one more minor release (Wagn 1.14) and a final round of polish.  Part of that polish will include adding new skins.  (We're hoping you'll help with that part!)  The new skinning system brings many improvements:

  1. dropdowns: new wagneers will simply be able to edit their *style rules and choose from a list of skins. (though, of course, we have to create those new skins first!)
  2. site areas: Different cards can have different style rules.  So, for example, you can use different skinning for different cardtypes.
  3. stylesheet cards: Skin developers have a much improved interface that includes syntax highlighting, SCSS support, and stylesheets organized into cards for easy reuse.
  4. control: You also have complete control over the CSS on your site (whereas much of it was previously hard-coded).  Some stylesheet cards do pull their CSS from code, but you can choose not to use those cards.
  5. readable HTML: by moving menus to javascript, adding slot comments, moving inclusion data to JSON, and cleaning up the head tag, we've made wagn's HTML tighter, w3 compliant, and far easier to read.  This drastically simplifies skin building!
  6. speed:  all style rules are automatically compiled, concatenated, compressed, and cached automatically upon update.  When combined with the more efficient HTML, this should make page and editor rendering considerably faster.

That last improvement ("cached immediately upon update") is just one example of the "events" that are possible now with our new events API. Almost all of Wagn's core behaviors have now been refactored into events and make use of this new API.  There is some early documentation of the API at present, but there is much more to be done there.  In the meantime, those interested may find it most useful to explore the events defined in built-in modules.


Events are central to the MoVE architecture, which we've been working to articulate more clearly.  The recent Blog post outlines the architecture in more detail, but the short of it is that we're exploring the space of handling data atoms in increasingly fractal ways.  Cards can be built out of cards, views built out of views, and, now, events out of events. 


The current release also makes inclusion handling more fractal.  Old inclusion syntax let you configure display details for the included card.  The new syntax lets you specify those details for the included card as well as cards included by the included card, cards included by cards included by the included card, etc. We've wandered into wonky land, clearly, but know that this simple improvement adds very little syntax yet adds great power for making pretty lists :)


If upgrading to Wagn 1.12, make sure you refer to the upgrade notes.  We've done a lot of work to make this a smooth upgrade experience (including migrating the old "*css" card into a new custom skin for you), but the upgrade may take a tweak or two if you've done a lot of styling work on your Wagn.


Upgrading to Wagn 1.12 requires card migrations and may require some minor CSS tweaks for those who have customized their look and feel with the "*css" card.  

Standard Upgrade

1. Backups

Always back up your database and uploaded files.

2. Update Libraries

From your decko root directory run:

bundle update

3. Update Database

Run the following:

decko update

4. Restart your server.


Upgrade to Decko from Wagn

1. update references to “wagn” in file content

In your decko's root directory, edit Gemfile, config/application.rb, and config/routes.rb, and script/wagn, replacing “wagn” with “decko”. (Keep the same capitalization pattern.)

2. update references to “wagn” in file names.

From your decko root directory run:

mv script/wagn script/decko

3. continue as with Standard Upgrade


See above.


If your Wagn was NOT installed from a gem, then first check the Wagn version of your existing installation:


For version 1.10 through 1.12.6


  1. Create a new Wagn app using steps 1 and 2 from the installation section above.
  2. Copy config/database.yml from the old site to the new one.
  3. Copy the old local/files contents to the new files directory.
  4. If you have edited config/wagn.yml in your old site, make the corresponding changes to the new config/application.rb file.
  5. Follow the standard upgrade procedure above.


Upgrading pre-version 1.10

First update your Wagn to version 1.10 via the old update mechanisms, and then follow the directions above to then upgrade to the wagn gem.

Rails people, please note that the command is `rake wagn:migrate`, NOT `rake db:migrate. There are no database structure changes in this release, so `rake db:migrate` won't do anything when upgrading from Wagn 1.11.x. 


If your *css card is invalid


Wagn now compresses CSS with a compiler that does not look kindly upon invalid CSS.  If your *css card has invalid CSS in it, it will not compile correctly, and your wagn will default to a style rule that uses the classic (uncustomized) skin.  To fix this, you will need to go to the *css card, see the errors reported, fix them, and  then update your *style rule to use the "customized classic skin", which includes your *css card.


If your CSS images aren't working


Chances are you just need to add a "/" to the beginning of the url.  Wagn CSS will not handle directory-relative urls properly.  The issue is a nuance of wagn file handling, which allows you to retrieve files in different ways with different addresses. You can, for example, do something like /*all+*style.css to get a freshly rendered version of the file, and you can do something like /files/*all+*style-12345.css to get a cached / compressed version.  Since the two are interpreted as having different directories, using directory-relative urls won't work.


If your header styling has gone wrong


For the most part, we have avoided changing the HTML and CSS in ways that will affect customized styles.  However, in the process of making our HTML completely valid and more idiomatic, we altered our handling of headers.  A standard card used to look something like this:


<div class="card-header">(...)<h1><span class="card-title">...


That much is fine, but the header often involved a bunch of inline elements (eg the open/close toggler and help text), which meant we needed to change the display property of the h1 tag to inline (or inline-block) to get things to work.  This is all more unconventional than necessary.  It got this way because there used to be a lot more text in the header.  Since that's been cleaned up, we can now clean up the header as well to look more like this:


<h1 class="card-header">(...)<span class="card-title">...


We also formalized the concept of a "card frame".  We'll soon be introducing visualizations to explain the concept, but the short of it is that whenever you're looking at a view of a card with its standard visual wrapper (like an "open" or "edit" view), it has a card frame.  Views without a frame (like "titled" or "labeled") tend not to reveal as obviously that they are separate cards.


This is relevant because the old CSS defined a default view for card-headers and then made exceptions for unframed views.  But since the card-frame itself is a CSS class, it makes more sense to go the other way.


What does all this mean?  Well, if you used to have something like this:


.card-header { background: #000 }
.card-header h1 { color: #fff }
.titled-view > .card-header { background: inherit }
.titled-view > .card-header h1 { color: #000 }


...you'll need to change it to something like:


.card-frame > .card-header {
background: #000
color: #fff

Cleaner, right?





+tickets by status


in progress