bootstrap support, improved following, new "card" gem


Due out this Friday (March 26, 2015), Wagn 1.15 includes several major improvements.


The first and most obvious is support for Bootstrap.  Whether you're creating a new "deck" of Wagn cards or updating an old one, you will now be able choose from one of 16 pre-installed professional Bootstrap themes.  And, because Bootstrap has become quite popular, you can readily find thousands of more themes on the web (not all of them free, of course!) that you could apply to your Wagn site.   Bootstrap is known for its "mobile-first" approach, so not only will these themes make your site look better, they'll help ensure your Wagn site is responsive to many different kinds of displays.   Please be sure to pay close attention to +Upgrade Notes when you update, especially if you have heavily customized your site's layout/styling.


The second major improvement is to "following" cards.  It is now possible to follow any Set of cards: all cards, all User cards, all +discussions, etc.  Moreover, you can also restrict those sets to only cards that you have created and/or edited. 


The third one is a bit more subtle, but it gets us closer to a key functionality that many have requested: the capacity to install Wagn as an extension to an existing Rails application.  To the Rails geeks, this means "Wagn as an Engine".  The major improvement in this direction is that we've rearchitected Wagn to make this possible: all the card handling is in a separate "card" gem, the core routing has been abstracted into a separate engine within the "wagn" gem (soon to be renamed to "decko"), and the support for adding engines to rails sites will be housed in a new "decko-rails" gem.


The software update procedure is the same as usual:

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.

...but there are several things you might want to do after the update...


1. You may want to revisit your site's layout and "skin".


The update includes 1 new Bootstrap-friendly layout  and 16 new professional Bootstrap skins.


The new layout is called "Default Layout", as it will now be the default layout on all new Wagn sites.  The update automatically renames the old layout to "Classic Layout".


If you haven't customized your site's layout or styling, the update will automatically update your site to use the new Default Layout and a Bootstrap skin (called "classic bootstrap skin") that has a similar look to the old default (called "classic skin").


If you have customized your site's layout and/or styling, the update will NOT automatically change either, because we did not want to override your customizations.  However, we did attempt to create a new skin for you ("customized bootstrap skin") that copies over the *css card, traditionally the most common card for styling customizations.


In either case the easiest way to change both is to navigate to your *all card, where you can edit your broadest *layout and *style rules.  (You may want to navigate to your *layout and *style cards to see if you have other, narrower rules to update.


In most cases, editing the *layout rule won't involve much though: you'll just change to "Default Layout".  But the *style rule editor will provide you many more options (each with a thumbnail preview).


In addition to being more professional looking than our old styling, the bootstrap skins are also highly responsive, meaning they look good and work well on a wide variety of devices.  While there are further mobile improvements coming soon, upgrading to a Bootstrap skin should mean your site is much more mobile-friendly.


2. You may need to do some CSS fixes


We worked very hard to minimize this, but to get Bootstrap working we had to make some HTML changes in core wagn views.  While most of those just involved adding CSS classes that should not break your current styles, some could potentially break some of your styling customizations.


Whether or not you upgrade to the Bootstrap layout, the following changes could affect your site:

  • card headers used to be based on an <h1> tag, but now they are entirely <div> based  (with several useful classes)
  • card editors used to have a fieldset around each subcard editor, but those have been replaced with <div class="form-group">, <label>, etc.
  • the *account links card that appears in the upper right of most wagns has been restructured to use bootstrap's menu patterns.

If you upgrade to the Bootstrap layout,

  • The top bar is now framed by a <header> tag, not <div id="menu">
  • The main section of the page is now framed by an <article> tag, not <div id="primary">
  • The sidebar is now framed by an <aside> tag, not <div id="secondary">

If your styling is based on any of the above, it may need to be updated.


3. You may need to specify "core" view in certain nests if you have significant layout customizations.


Suppose I have a nest like this: {{mycard}}.  What view would Wagn use when it shows me that nest?  (Note: some of you old-school Wagneers may be more familiar with the term "inclusion" than "nest"; they're the same thing!


The answer to that used to be quite complicated:  "content" in most places, but "open" for the main card, and "core" in most layout contexts.  That last one was especially complicated, because at some point after you nested a card in "open" view, it would go back to using "content" as the default.


Now the answer is much simpler: wherever a nest like that (with no view specified) appears on your existing Wagn site, the view will always be "content".  (The reason I emphasize "existing" is that this is now configurable, and on new Wagn sites the default is "titled").


For updating purposes this should not matter to most of you: the update automatically migrates all layouts to specify "core" view where no view was previously specified.  This will retain the old behavior.


HOWEVER, it's possible that your layout nests other cards that themselves have nests without specified views.  These would always have been rendered in "core" view but will now show up in content.  You will need to specify "core" view by hand, like this:


If you don't know what any of this means, odds are you haven't done enough customizations for this to apply to you!


4. You may choose to restore old menu behavior


After the upgrade, the menu gear for a given card appears only when that card has the focus (ie mouse overs).  This behavior now applies by default to titled view, as well, even though previously menus had to be explicitly turned on in titled view, like so: {{mycard|titled;show:menu}}


If you want to show menus all the time, you can add some CSS like this:

.card-menu-link { display: inline-block !important }

If you want to hide menus in titled view (or any other header, for that matter), you can do something like this:



5. You may want to create some new following rules


The improved support for "following" cards means that users can now follow any Set of cards  (all cards, all users, all +discussions, etc).  It also lets you narrow those sets only to ones you've created and/or edited.


So, not only might you want to update what you're following, you might want to configure what your community members follow by default.


We're working to get out some good documentation for all this, but in the meantime, know that there's a lot of power there!


+tickets by status


in progress






should really document how following works now.

--Ethan McCutchen.....2015-03-26 19:24:06 +0000