Wagn 1.17 uses the latest version of recaptcha.  For security reasons, they now require that each domain have its own set of keys, so if your site has been using old "global" keys, and you want to continue using Recaptcha, you will need to update your "*recaptcha settings" with new keys, which you can obtain from Google.

The software update procedure is the same as usual:

Updating

help edit space_dashboard

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.

 

Older versions - Updating to a Gem Wagn

help edit space_dashboard

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

help edit space_dashboard

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:

{{mycard|core}}

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:

{{mycard|titled;hide:menu}}

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!

If you're already at Wagn 1.13, this should be a  pretty standard upgrade.  However, do expect the migration to take a while; it's doing a lot of work restructuring the entire revisions table!

If you're not already at Wagn 1.13, have a look at this before proceeding:

upgrading to Wagn 1.13

help edit space_dashboard

Wagn 1.13 is Wagn's first minor release in the form of a ruby gem.

 

If you are upgrading from a site that is not already using the Wagn gem, then you will need to upgrade to the Wagn gem before following the new standard upgrade procedure or the notes below.

 

If you are upgrading from a pre-1.13 version using the Wagn gem, there are several things to keep in mind:

• Make sure you are in the folder where your Wagn web site is located (usually 'cd /var/www/your_wagn_website' will do)

1. Wagn 1.13 moves all javascript into cards, which means you'll need an Execjs.  If you're using a mac, then no worries; it's already built-in.  Otherwise, you need to add this line to your Gemfile:

   gem 'therubyracer'

2. You should no longer have to run `rake wagn:migrate`.  The main command is now:
   

   wagn update

   which runs the migrations in additions to some other helpful commands.  See the Updating card for more details.
3. If you're running wagn in production, you may have been running a symlink from your deck's "public" directory to the one in the gem directory.  This symlink is no longer needed and should be removed. However, you can still improve performance of certain requests with a similar symlink to public/assets.  This symlink is automatically generated when you run `wagn update` and can be generated directly (with no other side effects) by running `rake wagn:update_assets_symlink`.
4. If you were using any mods, you may need to singularize some directory names.  For example:

   mods/mymod/sets/right/address.rb

   would become

   mod/mymod/set/right/address.rb

5. If you're interested in developing Wagn mods or the Wagn core, please contact us directly.  Wagn 1.13 adds a lot more support there, but the documentation is lagging!

Wagn 1.13 is Wagn's first minor release in the form of a ruby gem.

If you are upgrading from a site that is not already using the Wagn gem, then you will need to upgrade to the Wagn gem before following the new standard upgrade procedure or the notes below.

If you are upgrading from a pre-1.13 version using the Wagn gem, there are several things to keep in mind:

• Make sure you are in the folder where your Wagn web site is located (usually 'cd /var/www/your_wagn_website' will do)

1. Wagn 1.13 moves all javascript into cards, which means you'll need an Execjs.  If you're using a mac, then no worries; it's already built-in.  Otherwise, you need to add this line to your Gemfile:

   gem 'therubyracer'

2. You should no longer have to run `rake wagn:migrate`.  The main command is now:
   

   wagn update

   which runs the migrations in additions to some other helpful commands.  See the Updating card for more details.
3. If you're running wagn in production, you may have been running a symlink from your deck's "public" directory to the one in the gem directory.  This symlink is no longer needed and should be removed. However, you can still improve performance of certain requests with a similar symlink to public/assets.  This symlink is automatically generated when you run `wagn update` and can be generated directly (with no other side effects) by running `rake wagn:update_assets_symlink`.
4. If you were using any mods, you may need to singularize some directory names.  For example:

   mods/mymod/sets/right/address.rb

   would become

   mod/mymod/set/right/address.rb

5. If you're interested in developing Wagn mods or the Wagn core, please contact us directly.  Wagn 1.13 adds a lot more support there, but the documentation is lagging!

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.  

Updating

help edit space_dashboard

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.

 

Older versions - Updating to a Gem Wagn

help edit space_dashboard

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

help edit space_dashboard

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?

Please note:

As of this release, you will need to run to the following command for migrations:

rake wagn:migrate

(it used to be rake db:migrate).  For complete upgrade steps, see:

Updating

help edit space_dashboard

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.

 

Older versions - Updating to a Gem Wagn

help edit space_dashboard

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

help edit space_dashboard

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.

 The benefit of the new process is that it separates the structural migrations from the card migrations, which should prevent the need for incremental upgrades in the future.

Updating

help edit space_dashboard

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.

 

Older versions - Updating to a Gem Wagn

help edit space_dashboard

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

help edit space_dashboard

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.

Updating

help edit space_dashboard

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.

 

Older versions - Updating to a Gem Wagn

help edit space_dashboard

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

help edit space_dashboard

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.

1. Be sure to perform the 1.6.1 upgrade and migrations first before upgrading to 1.7.0.   It will not work to upgrade directly from older versions.
2. There are several gem updates, so be sure to run `bundle install` before running the new code.  See using bundler with Wagn.
3. It is recommended that you schedule downtime before this upgrade because the old permissions must be migrated into the new system using `rake db:migrate`.

The Wagn 1.6 upgrade involves three key tasks:

1. You must run database migrations for Wagn 1.6 to work.  Please backup your database before migrating in case there are any issues.  

rake db:migrate

Why are migrations necessary?  Because we've updated the handling of "built-in" cards, like *navbox, *now, *version, *account links, etc.  They are now real cards that use the new "card pack" views API.

2. You will need to install, configure, and run "bundler" if you are using git.

 

using bundler with Wagn

help edit space_dashboard

1. Install bundler

   gem install bundler

2. Use bundler to install / update your other gems.

   bundle install  #WAIT!  This is the basic command, but read the following before running it.

   If you just run that command, bundler will install all the gems Wagn ever uses, including many that you probably don't need, upping the odds that you'll encounter problems.
   
   So it's best to specify which groups of gems you DON'T need:
   

   # sample install command for wagns using mysql
   bundle install --without test hosting sqlite postgres
   
   # sample install command for wagns using postgres
   bundle install --without test hosting sqlite mysql
   

   Bundler sometimes stumbles on the mysql gem because it doesn't know where the database is stored.  You may find this bundler configuration document helpful in resolving that issue, especially this command:
   

   bundle config build.mysql --with-mysql-config=XXXXX

FAQ - Foolhardily Anticipated Questions

Why is this necessary?  Wagn is a Ruby-on-Rails application, and it needs gems to run.  Gems are specially-packaged independent ruby programs/libraries.  Bundler is the gem management system used in Rails 3 (on which Wagn will soon run), and it dramatically improves gem maintenance.

Why is this worth it?  Installing gems with bundler can sometimes take a little extra time upfront, but saves a ton of time in the long term.  Bundler stores your configuration preferences in a .bundler file and uses that file to keep your gems up to date with Wagn. It may be hard to notice the headaches you're not having, but this is an investment in many non-headaches in the future.

Do I want those extra "gem groups"?  Not unless you're feeling hard core.  The "test" group is recommended for programmers interested in modifying or extending Wagn.  They are needed to run Wagn tests (rspec, cucumber, etc).  The "hosting" group is not needed to host a wagn site; it includes gems that we use on our hosted wagns and are not needed in most hosting scenarios.  The database groups are only needed if you're using that database.

 

git submodule update --init

CSS classes have been reworked to be more like sets:

• All cards have the ALL class.
• Cards of a given cardtype used to have a class .type-|original cardtype name| but now have a class .TYPE-|cardtype key|
• Plus cards didn't used to have a unique class, but now have one: .RIGHT-|key of right part|
• In addition, plus cards have a class of the form .TYPE_PLUS_RIGHT-|key of left part's cardtype|-|key of right part|
• Individual cards used to have a class .cardid-|card number|, but now have a class .SELF-|card key|.

A key is the same as a card's name, but all lower case, punctuation replaced with spaces, multiple spaces replaced with a single space, and spaces replaced with underscores. For example, a cardtype "Joe's Blog Entries" would have a key of "joe_s_blog_entries". (this may be described elsewhere better). The way to be sure to get it right is to look in the HTML of a card you want some CSS to apply to, and see what follows 'class="card slot'

*notify+*from no longer specifies the address following emails come from. All system emails come from the email address for the Decko Bot 1 account.

• The raw view no longer works at all (it's been deprecated for a while; use naked to get the effect raw used to give).  it will be reintroduced with its intended meaning in the next release. See http://www.wagn.org/wagn/views
• Due to layout changes, we have changed the names of some things in CSS:
  • page-left is now primary
  • page-right is now secondary
  • ...
• many configurations have been patternized

Be sure to run your migrations!  1.2 adds a number of new cards.

• be sure to run migrations (rake db:migrate) to add some new cards important to notification
• if you're using git you'll need to either upgrade to rails 2.3 or copy application_controller.rb to application.rb for running under rails 2.2

CSS changes

• Pointers' css used to use ul's and li's, but to work with Internet Explorer we changed to div's.
• all css classes that begin with "w-" are now safe from html stripping.
• left margins were fixed on help text
• input boxes look was made more consistent - light yellow in almost all cases except for "name"

Migrations

• updated content of the *account card
• *thanks cards' content now starts with a "/"  (allowing external redirects)

Strongly deprecating raw — in favor of naked — for views inclusion, WQL and URL. Planning to reuse raw as of Wagn 1.0 as a view returning the actual text (with link/inclusion markup and HTML) of a card.