User:Whiteknight/Visual Book Designer

From Wikibooks, open books for an open world
Jump to navigation Jump to search
Visual Book Designer
Use the outlining tool below to create a new book. Click the book title to rename it. Click Subpages to add new pages to the book. Click Headings to add page headings.

You must install User:Whiteknight/designer.js to interact with this element. Installation instructions located at User:Whiteknight/Book Designer Gadget.

How To Install[edit | edit source]

This script is a Gadget. You can install this script by going to Special:Preferences, going to the "Gadgets" tab, and checking the box labeled Whiteknight's Visual Book Designer.

Once you save your javascript, you may need to clear your cache, typically by pressing + , or some other key combination, depending on your browser.

IE7 IE6 FF2 FF3 Safari Chrome Opera9
Works Not Tested Works Works Works Works Works
Browser Test Codes
Broken: The script does not work in this browser.
Partial: Some (but not all) features of the script work in this browser. Problems may be minor and will probably be listed.
Works: The script works as expected in this browser, and no obvious bugs or errors are present.
Not Tested: I have not tested this script on this browser. It might work, it might not. If you test it, let me know the results.
Browsers not listed here have not been tested or are known not to work

Known Issues[edit | edit source]

All
Opening two or more edit windows may cause problems because div id's won't be unique and some function calls will fail.

Feedback[edit | edit source]

Do you have some feedback, feature requests, suggestions, or questions? Let me know at my talk page.

Updating Gadget[edit | edit source]

For Admins
To update this gadget to the most recent version add the following code to MediaWiki:Gadget-wkdesigner.js:
{{subst:User:Whiteknight/designer3.js}}

{{subst:User:Whiteknight/bookpage.js}}

{{subst:User:Whiteknight/pageheading.js}}

About This Gadget[edit | edit source]

This gadget is designed to be a high-level, user-friendly way to automate the process of creating a new book here on Wikibooks. This gadget, the Visual Book Designer, works like a regular outlining tool. For each point in the outline, you have the option to add subpoints (subpages or page headings), or to modify the point (rename, delete, etc). When the gadget page loads, you should see something similar to this:

New Book - Templates - File - Options - Clear
Headings [+] - Subpages [+] - Wikitext - Edit
[Click here to edit page text]

This looks like a lot of options! Creating a book does require an author to make many decisions, although luckily a lot of decisions have default values that you don't need to change. The sections below will discuss these options and how they can be used to shape your new book. You should feel free to experiment with this tool, in addition to reading this documentation. However, you should be careful because some buttons can have consequences. Some parts of this tool will open an edit window where you are able to save changes to pages elsewhere in the wiki.

Warning: This tool allows you to make edits to other pages in the wiki without first viewing those pages. Do not save page changes if you are not sure you want to create a new page or possibly overwrite an existing page. Abusing this tool is no different from abusing the edit function on any other page, and will be taken very seriously.

Note on Terminology[edit | edit source]

Outlines are shaped like "trees" from computer science fields, or "graphs" from mathematics fields. Each page or heading in the outline is a point called a "node". A node has a single "parent", and multiple "children". For a page node, the children can be headings or subpages of that page.

The top node, the node that has children but no parent, is called the "root node". In terms of books, the root node is the main page of the book, the table of contents. Children nodes of the root node are the pages and headings that appear on the table of contents.

Book Menus[edit | edit source]

Naming your Book[edit | edit source]

Naming or renaming your book is very easy. In fact, renaming any page or heading is easy too: Click on the page title to open an edit box. Enter the new name and click rename. If you want to delete the page instead, click delete instead. You cannot delete the book itself, but you can click Clear to delete your entire outline and start over from scratch.

Templates Menu[edit | edit source]

The Templates menu gives the option to create and specify templates for categorization and navigation.

Provided with this gadget are a list of 5 pre-made navigation templates. These templates are very simple and plain, but they are effective and customizable. They provide a good starting point for your book, and from there you can get more creative once your book has been created. You don't need to use these premade templates in your book, but it's one less thing to worry about up front. This is a wiki, so things can always change later as your book evolves.

Select a template from the drop-down box and click Make Template. This will open an edit window where you can view and possibly modify the template text before you save it. Clicking Save page, like usual, will save this text and create your new template. For more documentation about these templates and how they are used, see Whiteknight's Book Foundry page.

Simple Header
Header with forward/back links
Page 1 —  My Book —Page 3
Page List Header
Page list header with forward/back links

In addition to these header templates you can specify the book's reading level and select categories that the book is in, for organization.

File Menu[edit | edit source]

The file menu gives a number of options for loading in pre-made books in a number of formats, and saving your outline into a number of formats.

Outlines
If you are working on your outline actively and it is incomplete, but you need to save it for later, you can save the outline to a page in your user namespace. In the file menu on the line marked "Saved Outlines", you can Save your current outline or Load a previously saved outline. Saved outlines will come with a link you can click to open the editor and load the outline in again.
Warning: Saved outlines are not perfect, they do not reproduce most configured options and they are not guaranteed to reproduce your outline perfectly.
Collections
You can load an outline from a personal or public collection page, or you can create a new collection page from an existing outline. Click Save to create a saved collection page, and click Load to load an outline from an existing collection page. Collections can be personal (in your user namespace) or they can be public (at Wikibooks:Collections).
Existing Books
You can load the TOC from an existing book into the gadget for manipulation. Once you have an outline you can use the wikitext options on each page, or you can click Create to active the book creation automator. The automator will create all the pages in your book automatically, using the structure and text in the outline.
Warning: Only administrators can use the Create feature. This is for testing purposes now, and may be opened up to a wider audience of editors later.
Print Versions
Print versions are deprecated now that we have collections. However, you can still create them if you want. Click Save to create a new print version for an existing book from the outline, and click View to see the wikitext without opening an editor.

Notice that this tool can be used for more then just creating new books. Using the Load TOC feature, existing books can be loaded into the gadget and then used to create collections and print versions for the book.

Options Menu[edit | edit source]

The options menu gives you control over a number of options about the book.

inherit page text by default

collapse nodes by default
When you create nodes, they start collapsed by default. This means you have to open them to see subpages and headings.
add a resources page by default
Automatically create a page named "Resources" in the book, even if it's not in the outline.
add a licensing page by default
Automatically create a page named "Licensing" in the book, even if it's not in the outline.
add an introduction page by default
Automatically create a page named "Introduction" in the book, even if it's not in the outline.
add Wikibooks:Collections Preface to Collections by default
When saving a collection, add the page Wikibooks:Collections Preface to it.
use page comments to create talk pages
NOT USED. I haven't implemented this behavior, so it doesnt do anything.
make edits in an external tab or window
When checked, all editors will open in an external tab or window. If unchecked, editors will be created inline in the gadget.

Clear Outline[edit | edit source]

Clears the outline so you can start fresh. If you have something that you want to keep in the gadget, make sure you save it first before you clear the outline. Once cleared, there is no way to undo or go back.

Page Menus[edit | edit source]

Pages are the fundamental part of any book. Each page in your outline has a number of options.

Creating Page Headings[edit | edit source]

Each page may contain headings to break up content into smaller blocks. To create a new heading on your page, click the [ + ] link next to the word "headings". This will create a new heading in the outline with a default name that you can change later. If you would like to create multiple headings at once, you can click the word headings to open an edit box. Enter the names of all the headings you want to add in the box, one per line, and click Save.

Creating Subpages[edit | edit source]

Creating subpages is the same as creating page headings. Click the [ + ] link to create a new subpage in the outline. Click Subpages to open an edit box where you ca enter the names of subpages, one per line, and then click Save.

Viewing Wikitext[edit | edit source]

To view the wikitext of a page, click the Wikitext link. This will display the wikitext for the current page for review.

Editing and Saving[edit | edit source]

If you like what the wikitext looks like, you can actually create the page using the Edit link. This will open an edit window preloaded with the text of the page. Review and possibly preview the text, and then click Save page to save the page.

Text and Comments[edit | edit source]

Under each page and heading node there are two lines of text, "Click here to edit page text", and "Click here to edit comments". Clicking on either of these two lines will open an edit box where you can edit the text of the page directly, or where you can post comments.

The page text is the text that will actually appear on the page when it is edited and saved. If the "inherit?" checkbox is checked, the page will also include text from it's parent page too. This is a good way to add basic text to all pages, or all subpages of a given page at once. Keep in mind that this is not intended to used for creating the complete text of a page. This editor is simply not robust enough for large-scale text and collaborative editing. What it does do, however, is allow you to create some basic stub text to get the page started. Once the page is created on the wiki, you and other editors will be able to edit and expand the pages as normal.

Comments are notes which are visible in the outline, but which do not appear in the book when you create it. Comments are used to help you, the author, stay organized while outlining. At any time, you can click the text or the comments to edit them again.

Loading an Outline[edit | edit source]

You can load a previously-saved outline at any time, when you want to continue working on it. Click the load link to open a text box where you can enter the name of the page to load the outline from. Once you have entered the name, click Load to load the outline into the gadget automatically. if the load operation fails for any reason, nothing will be loaded and an error message will be displayed.

On an outline page, you will see a message similar to the following:


This outline is a saved state for use with Whiteknight's Visual Book Designer gadget. Do not edit the outline on this page directly unless you understand the syntax. Improper editing here could make it impossible to load this outline into the gadget again.
Edit This Outline In The Gadget

Clicking the "Edit This Outline In The Gadget" link will open the Visual Book Designer and automatically load that outline.

To Do[edit | edit source]

FEATURE: Add a "Design!" link, or similar, to the upper-right corner of the page
FEATURE: Add some kind of roll-over effect. If you rest your mouse over a page name, display a floating box with options about the page including: the fully-qualified page name, the fully-qualified name of the parent page, a status check to determine whether the page currently exists or not, etc.
FEATURE: Add Drag-n-Drop node reordering.
SUGGESTION: Add timeouts on some of the AJAX requests, and callbacks to use on failure. Will probably require massive changes to the wkgadgetscore library
SUGGESTION: Consider using JSON as a storage format for new outlines
FEATURE: "Full Screen" mode
SUGGESTION: Port this gadget to use JQuery
SUGGESTION: Modify this to be an extension, in addition to a gadget. Create a Special:BookCreator page instead of having a page here in my user namespace
FEATURE: Make menus into normal "dropdown" menus
FEATURE: Improve UI all around

Version History[edit | edit source]

  • 3.73 Refactored handling of "Loading..." messages
  • 3.72 Some simple refactoring, and improved rendering of subpage text
  • 3.71 Add basic ability to load from collections pages
  • 3.70 All edit functions in core now take either a text string or a filter function. Refactored core to be consistent about handling nodes. Added external editor option. Refactored editor code.
  • 3.68 Add "[ + ]" links to create a new subpage or heading without an edit box.
  • 3.67 Refactor Options menu
  • 3.66 Added Options menu. Made Introduction, Resources, and Licensing pages optional
  • 3.65 Fixed detection of existing pages during rename. Added detection of existing pages during automate. Merged print version and file menus, improved file menu. Added deprecation note about print versions.
  • 3.60 Fixed automation, tested in FF
  • 3.53 Fixed wikitext formatting problems in IE7 and Opera
  • 3.52 Added error message if an older version of gadgetscore is used.
  • 3.51 Added timestamp to User:Whiteknight/SavedOutlineStart to tell when the outline was last edited.
  • 3.50 Broke gadget into three separate code files, one for each class.
  • 3.40 Added support for public and private collections, and a few small changes.
  • 3.39 added basic drag&drop (needs debugging)
  • 3.31 Improved some loading messages.
  • 3.30 Added collapse/expand buttons to pages and headings.
  • 3.25 Added ability to load an outline from an existing book.
  • 3.20 Updated "Print Version" menu, condensed "Save" and "Load" into a single "File" menu.
  • 3.11 Added basic "Print Version" capabilities from an outline.
  • 3.10 Added ability to "autoload" an existing outline using a query string
  • 3.01 Added an "HTML" mode, that saves the raw HTML of the outline for later display.
  • 3.00 First official release of this new gadget for public consumption. All important features have been added and tested.