Skin Creation

Documentation > Extending BoltWire > Skin Creation

Note: this page is largely a cut and paste from a couple emails and may need some editing. Two other pages with important information are Layout and Skins which may have some inaccuracies. Perhaps the content in the skins tutorial can be separated out to this tutorial and the introductory one on site.layout... Better to have the right information in the right places.

General Process

To create a custom skin, here is the general process:

In your browser, rename code.skin and code.style to code.skin.newname and code.style.newname.
Go to site.config and set skin: newname.
Create a folder in the farm/skins folder called newname. Use it to store your graphics, js, and the like.
Edit the new skin/style pages to look like what you want. Use links to the skin folder for your graphics. ($$skin/img.jpg)
Copy the skin/style files and any other wiki pages you wish to include from your pages directory to the skin folder you created.
Test it on a fresh installation. Set site.config to skin: newname. If it works, all is great! Otherwise repeat steps 4-6
Zip up the folder and upload the file to BoltWire.

Actually, it's probably best to email it to me so I can upload and enable it both. We have pretty strict upload limits on BoltWire. I can loosen those if it's easier.

I just pulled this tutorial together off the top of my head. If someone could give it a try and make any corrections, that would be helpful. Maybe we can develop this into a nice tutorial.

It probably would also be a good idea to offer a few tips on how to take an existing skin from some other source and convert it into a BoltWire template. Perhaps those of you tinkering with skins can note what challenges you have/questions not immediately intuitive, so we can make it easier for the next person.

Markup in Skin

You can put them in the skin directly. Use syntax like ==[(breadcrumb)]== to inject markup directly into the skin file.

Custom Skin Zones

You can include any wiki pages you like in your skin folder and all will get imported and overwrite anything in the wiki. Of course your risk alienating some user if you overwrite their custom side bar. The solution is to rename the skin side bar to side.myskin (or whatever your skin is named). Same with any other zone. Do not put wiki pages in your skin zip like right or top, or header, but right.myskin, top.myskin and header.myskin. These will be used before the normal zone page if the skin is "myskin", but not overwrite what they already have. Plus you can easily switch between multiple skins in a site without having problems between them wanting certain features or layout in a specific zone page. To get a quick list of all skin pages, you can also just do a search with type=myskin to get so named pages.

So I would actually encourage you to create your own action lists, zone pages, etc.

Skin Action Pages

You can also do custom action pages, like action.edit.myskin that will take precedence over action.edit if the skin is myskin. Or even action.forum.edit.myskin with will take precedence in the forum hierarchy when the skin is boltwire. Here's the full progression

1. action.forum.edit.myskin
2. action.edit.myskin
3. action.forum.edit
4. action.edit

Skin Vars (Snippets)

Here's another helpful tip:

Where possible try to use snippets (also called skinvars) in your skin and css to make them work on any BoltWire configuration. So for example:

$$page/some.page
$$skin/background.gif
$$img/boltwire.gif

(theres also $$farm and $$pub)

And then there are four places BoltWire looks to fill a general variable in the following order (looking at the code right now...)

$$author =>
1. {some.page:author}
2. {author}
3. code.snippets.myskin::author or code.snippets.myskin#author
4. code.snippets::author or code.snippets#author

So you could create a code.snippets.myskin page for all the system variables in your skin, which would get overwritten by anything in their normal code.snippets page, and could overwritten by a data var on a specific page. This could be helpful for things like meta tags or footer copyright lines. All that. But because you can use whole anchored sections you could also but a BoltWire search form or login block or whatever directly into the skin without having to use a special zone.

Updating Skins

The skin is copied over immediately upon changing the skin setting in site.config if code.skin.myskin does not exist in the wiki. All in-wiki editing affects the copy not the original. And any changes to the original is ignored. There have been requests for different ways of handling this but they all have their pro's and con's. We have kind of settled on this, but I'm open to other possibilities. We could possibly make it configurable in some way...

The main reason is upgrades. If you are running multiple sites using a couple favorite skins, you can freely download updated skins to your farm and they will not affect existing installations, except perhaps graphics or js scripts. Files called directly from the skin folder... So new sites can take advantage of the changes, without disrupting existing sites. Again pro's and con's to that I suppose. To upgrade your existing site, you have to delete code.skin.myname from the wiki. Once gone, BoltWire will immediately reinstall the new skin, overwriting all existing files in the skin folder immediately. I think the important thing is to understand how the process works. I've never felt fully comfortable with this system, but it works... And there are plenty of other ways to configure things if desired.

Everything is changeable in BoltWire...

BoltWire

Innovative Ideas :: Radical Results!

INFORMATION

DOCUMENTATION