Introduction to 3.3 – part 2
Just a heads up to anyone thinking about trying to start a blog post series just before summer: not a good idea. Anyways, I’m back with another update on new and upcoming features in 3.3. Many of you may not use the wiki, either because of its limited abilities to format and organize content in it, or just because you use another system for documentation or don’t have wiki content to put in. Fair enough, but in 3.3 a huge push has been made to make it possible and desirable for you to put your documentation and text content in the Bug Genie wiki! How so?, I hear you whisper in the shadows – oh, I’ll tell you.
The 3.2 wiki – while staying compatible with the Mediawiki (Wikipedia) syntax – only contains a minor subset of the full syntax available in Mediawiki installations. The goal with using the Mediawiki syntax is both to make it easy to use the Bug Genie wiki for Mediawiki users and authors, and to not introduce yet another wiki formatting syntax for you to learn. The mediawiki syntax is straight-forward, feature-rich and easy to understand. About time we started supporting more of it!
So, what have the wiki got in store for you for 3.3? Read on!
As you can see from the image above, the default wiki layout has gotten a facelift with cleaner fonts and lines, as well as some useful features and additions:
- The title header has been cleaned up with a thinner font that behaves more like a header title. This font is also re-used for the different article sections such as attachments, sub-pages, sub-categories and comments.
- The tabs have been rearranged and merged. Article attachments are no longer shown as a top tab, but instead as a list inside the article itself.
- The table of contents has been slimmed down and is now displayed by default. It can be collapsed:
- or made sticky (fixed):
- as you wish. A sticky table of contents will scroll with you as you scroll down the page. This is different from previous versions where it would be collapsed by default and expanded when you hover over it, but without the possibility to make it sticky (fixed).
- The table of contents has been slimmed down and is now displayed by default. It can be made sticky (fixed) or be collapsed, as you wish. A sticky table of contents will scroll with you as you scroll down the page. This is different from previous versions where it would be collapsed by default and expanded when you hover over it, but without the possibility to make it sticky (fixed).
- Similar to other places in The Bug Genie, wiki pages now also have a more actions button. The wiki “more actions” button lets your permanently delete the article and attach a file. The attach file action is also available next to the “Article attachments” header inside the article.
- When logged in, you can now subscribe to updates for a wiki article by clicking the header star, just like with issues. Whenever an article is updated or commented upon you will be notified, and you can check the notification status by looking at the star (yellow star means you’re subscribed) or hovering it (please ignore the hover tooltip being misaligned, that has been fixed). There are also new settings for these notifications in your account settings. Article authors are automatically subscribed to updates, including comments.
New editing features
So, these features are all nice and dandy, but what about actual wiki editing capabilities? Oh, there’s tons.
Basic html tags
Starting with 3.3, you can now use basic html tags as wiki content. Similar to the Mediawiki syntax most basic tags are allowed, including div, span and strong. These tags can also have two properties – style and class. Included in the basic stylesheet are six classic “shadowed box” styles that blend in with the regular theme, named greybox, redbox, lightyellowbox, yellowbox, greenbox and bluebox. You can see the greybox in use in the special pages and template screenshots shown below.
Implementation-wise, the html syntax is resolved using the php dom extension, so if there’s a syntax error, it will default to showing the html tag code, unparsed. This means you must make sure your html is valid, but also prevents unwanted styling.
3.3 also has support for wiki templates. Templates are wiki articles that are included in other articles, to allow for reusable sections such as navigations, information blocks and more. In the screenshot above, the “About the bug genie” box is a template. A template can be anything from just a string of text (“Copyright 2013 Your company”), or advanced blocks including html formatting such as above (the grey box is created using a div with the greybox class).
You can also specify parameters with and without default values, which allows you to create dynamic templates that can be re-used. Although the template above is simple it allows you to show a dynamic block of text with a custom alignment, defaulting to right-aligned. Anyone familiar with Mediawiki templates will be instantly familiar with TBG templates, as the syntax is identical. Here’s the syntax for including that same template in the category page shown above:
The Bug Genie wiki supports both named and numbered parameters (not shown above), and allows you to pass in values for any number of parameters available. Again, just as the Mediawiki syntax allows you.
Noinclude and includeonly
You may be familiar with the <nowiki> and <code> tags (which lets you specify unparsed text and pieces of code, respectively). With the inclusion of templates in 3.3, we’ve also had to add support for <noinclude></noinclude> and <includeonly></includeonly> tags.
This specifies text that is shown only when the article is being displayed as a standalone article, using the article’s url. This means that any text between these tags is not shown when the article is used as a template, but is shown when the template is shown standalone. This is usually used to provide template usage instructions on-page which are not shown when the template is being used.
This specifies text which is shown only when the article is included as a template. This may be useful to reduce the information shown when the template is shown standalone or because there are parameters that needs to be parsed that does not make sense when the page is shown on its own.
Table syntax improvements
Also added is much improved table syntax – actually, the full table syntax as described in the Mediawiki formatting page. Notable improvements are:
- Table caption – this lets you specify the table title (caption) which is shown as a proper table caption. This can also be styled via css.
- Table, row, header and cell class and style support. Similar to the basic html support, you can also specify a custom style or custom class per cell, row, header or table. In table cells, this also includes the align property to control alignment (can also be done using style and text-align).
- Merging – you can merge both rows and cells using the merge syntax.
This makes for drastically more usable and flexible tables!
HTML special characters
Also added is support for html special characters (© and similar). Any html entity can be used, and TBG will parse it as well as show a hover title that says what the code for that special character is.
Other new features
In addition to the features listed above that should make your wiki editing much more powerful and easier, there’s also a bunch of other features to help you organize the contents of your wiki. Read on!
Classic style vs. manual style
In 3.3, we’ve introduced two ways of showing your wiki content – classic style and manual style. As the name implies, classic style is the traditional wiki view, with the left boxes with wiki shortcuts, and the manual style is a new way of showing your wiki articles. Any of your articles can be in classic or manual style (specified per article), and you can switch between manual style and wiki style whenever you feel like.
There is really nothing special to say about this. This is how wiki articles have traditionally been shown, with the wiki menu on the left side and wiki toolboxes below it, including “what links here” and similar.
This is the cool new mode. An article set to display in manual style has an auto-generated wiki-wide table of contents shown on the left! Specifying this mode as the article mode also lets you specify a parent article, which means you can organize your content into chapters and sections, just like – a manual! Manual style articles that have parent articles are shown under their parent article in the manual tree, and articles that doesn’t have a parent article are shown as top-level elements in the tree. Note that there is still only one top element per project.
Any manual style article that has child articles (linked as parent articles by any of the child articles) are shown as chapters in the tree, whereas articles that doesn’t have child articles are shown as articles in the tree. Here’s a screenshot of how that looks:
The last cool, new feature in 3.3 are special pages. Special pages are special, auto-generated pages that serves a specific purpose.
As you can see from the list of global special pages above, this includes listings for orphaned articles, all categories, all templates and more. These pages cannot be edited, but will automatically show the specified content. Special pages live in the Special: namespace, which from now on is reserved for special pages.
All project also have their own Special: namespace which is identical to the global special namespace, only that it is project-specific – meaning it will list pages in that project’s namespace only:
That’s all for this time. I hope to write another summary of other notable features soonish. Comments and feedback are most welcome!