BoltWire 3.0 to 4.0 Transition

Here is a summary of major changes introduced in the the 4.xx series:

There are lots of new features in BoltWire 4.xx, some of which were the reason for this massive code rewrite. Listed below are some of the more important ones:

  • Can now do full filtering of form posts using required, filter=filtername/regex pattern, case=, trim, and other options. Right in the input markup
  • Can now put arg parameters right in commands just like in functions. Note "session" replaced by "command" in markup. Makes it amazingly easier to simplify commands, and no name conflict between posts and commands. No more cumbersome boltcommands and things to solve recursive problems.
  • Powerful Box function which allows type=code,html,markup,comment rule= lines= etc and other parameters. Fully stylable. Rules can be used in comment boxes to limit markups very effectively
Improved Conditionals
  • If statements are now fully nestable up to 9 levels. :)
  • If parameters can be put in commands, functions, searches, etc.
  • Completely revised indexing system to create smart indexes
  • Indexes are now insite, using info page formats.
  • Allows for incredibly fast data crunching reports.
  • Many commands and functions enhanced for many powerful effects
  • Completely redesigned and simplified. Cut out the problematic diff code. Now can access stamped data or content directly, and easily.
Help System
  • Deleted old clunky help system and replaced with a simple help action. Added several help pages to ease new users into BoltWire. May expand this via a plugin.

A real effort was made to drop out peripheral functions that only complicated the code or could be handled fine in a plugin. This list is probably not exhaustive:

  • Can no longer have config arrays like skin:color: blue. Just use skin_color: blue
  • Code pages and others no longer configurable. Can put in subfolders.
  • Field folders: files, pages, etc no longer configurable. Removing these options just simplifies the code significantly.
  • Blacklisting and Whitelisting removed (can be done as plugins).
  • Caching switched to a clever little plugin.
  • Various functions and commands are deleted. You'll have to look to see which.
  • Interwiki is no longer in the core
  • Wikiwords is no longer supported.
  • Stripped out changelogs, author and other unnecessary data variables from pages to keep pages lean. Add back if you want them.

  • Major reworking of skin to have and
  • No skin PHP. Call in config.php or add to config.php if you want it.
  • By default, uses page in shared/skins folder. Not copied over to site/pages (making them editable) unless you set in site.config localskins: true.
  • Settings on code.settings are available in skin or on site as simple {vars}. Anchors not available. Note code.snippet no longer works.

  • No more << or >> for large and small, now use <size= ></size>
  • Use + text+ to tap into translations (instead of ugly >>text<<)
  • Eliminated some styles like ^^superscript^^ (kept citations)
  • Pre was integrated into html function.
  • Only h1 to h3 defined.

Plugins can be run out of the shared/plugins directory or your local config directory. For the latter set localPlugins: true in site.config and they are automatically copied over.

Plugins now must be installed manually via site config and extracting zip pages. IE, no plugins command, backup, restore, overwrite, etc. Keep it simple!

Note: Numerous functions, processes, variables names, etc., in BoltWire have been changed. Many, if not most plugins will probably need to be revised. :(

If you develop plugins or write custom scripts for your site, you should know 4.xx represents significant change. I've tried to document some of the changes above but there were also many changes under the hood. Be prepared to test all existing scripts for functionality, esp in any kind of mission critical website. If you discover a script no longer works, post it to the mailing list and we'll see if we can spot what needs to be upgraded. Likely it is something very simple.

Upgrading from 3.xx to 4.xx

BoltWire made a pretty impressive leap between 3.xx and 4.xx, including many new features and changes to the core. (Click here for a overview). As a result, however, upgrading a site from 3.xx to 4.xx can be a bit of a challenge. Plan on it taking an hour or two. This tutorial will give some help--but can't promise it will cover everything.

Reasons to Upgrade

  • The new features are really cool!
  • The core engine is small and yet more powerful
  • It runs faster
  • 3.xx is no longer being supported
  • The plugins and skins are all being upgraded to 4.xx
  • The docs are all being rewritten for 4.xx

Actually, right now, our site is in a bit of confusion as we are in that transition process. But pretty soon the dust will settle, and 4.xx will be everywhere...

The Upgrade Process

Normally upgrades are pretty painless, and we try to keep them that way except when there is a jump between versions--and we pull out all the stops on improving the core. This is definitely the case in the 3.xx to 4.xx transition.

Because it takes several steps, and a lot of testing I would suggest upgrading a copy of your site offline first, work out the kinks, and then upgrade your live site second. It should go faster.

Here are the basic steps I would suggest:

1. Down and extract the BoltWire 4.xx zip file, and put it in a directory called boltwire4 if you want.

2. Next, go through your sites, one by one and make a copy of your entire site folder. Call it site2 or something similar. Point the index.php file in site2 to the boltwire4 installation. Keep the original site going to the boltwire (3) folder to avoid interrupting service.

3. First, work on the skins. Take some time to look at the new skin directory structure (boltwire/shared/skins/...), note how the html and css pages are named, open them up in a text editor and look inside. The main change is $$var was changed to {var} in the skin and css files. Possibly some variable names were updated. You will need to put your files in the right place, give them the right name, and update the content. Tinker with them till you get the skins right. If you are using code.snippets in your current skin, open it up in your browser, paste the values you want in code.settings, and save. Multiline values no longer work, so you will have to use the include function or something similar if you need that feature in your skin.

4. Update all site pages with the new markups. I've written a new script that will automate a lot of this. Download it here. fix.php. If you are a programmer, peek inside. It's got a lot of comments, and you may find this script useful for other kinds of fixes. Simply save it to your new field folder (site2) and then call fix.php in your browser. It does 100 pages at a time, so you may need to refresh it several times to do your entire site--but it's quite fast. It will fix several of the markup changes automatically, and then create a log of pages you need to look at afterward and examine by hand. No promises it will catch everything!

The main changes it makes are:

<code> => <box code>
[session => [command
[if* => [if
target= => 'page=

The log is saved in the main site2 folder and is called fix.log. You may want to print its contents out so you can go through the pages and check them. It will alert you to any pages with <<, >> or [form. The latter is just to give you a list of all your sites forms. See below.

The translate markup was changed from >>translate<< to + translate

The large and small/large markup was changed from >>>small and <<< large to <size=80%>small</size>.

5. Check your forms. Forms were significantly reworked, so you will want to at the very least test all your forms. The main changes are the commands now take parameters so that instead of

[session target]
[session create {=content}]

you would use

[command create content={=content} arg1= arg2=]

Many of the functions require different syntax now, to take advantage of this change. Try your forms out, study the system action pages for examples. Look at the code. Ask questions on the mailing list if you get stuck. Make sure all your forms are working properly.

6. Plugins may need upgrading. Some may come through unscathed, others are going to need major reworking. Test them out and make sure they work as intended before going live with your upgrade. The last thing you want is to upgrade your site, think everything looks good, only to discover a week in that your plugin is not working and site data has all been corrupted. You can't test too much.

7. Reindex your site. Look for the tutorial on how the new indexing system works. Delete your entire index folder. Create any custom index rules you want, and reindex everything. None of your search functions will work without the new indexes. For that matter, if you have any functions that do data, text, or link searches, they will need to be rewritten to use the appropriate index. There's also an updated doc on using queries.

8. If you've done steps 1-7 your site should be pretty well set to go. But there may be some function that has had its syntax changed, or some markup rule that has been modified or deleted. The more testing you can do, the better.

9. Upload the new site. Upload the new BoltWire (4) installation. Check the live site to make sure no content has been changed since you started working on the upgrade (so you don't lose the latest content). Lastly upload the new site to a new directory. Test the new location online. Then lastly change the names of the old and new site directories to actually make the switch. Whew... You're done!