The Absolute Beginners Guide 2.0

From one to the next

Created by: kinderlehrer, Last modification: 19 Mar 2009 (22:41 UTC)
{backtotop min=3 max=4}
Sometimes, technical documentation can be perfectly accurate, but the facts are not explained in plain English! That's why the following page is written by beginners for beginners, in the way that questions would be asked. Please note: This documentation is under development. It is not yet as reliable as the official documentation.

The solutions here may not be perfect but will get the result. They may change over time, as the beginners who contribute find a "better" way. Everybody is welcome to contribute, even Experts! (Remember, plain English.) Please note that there is a tab in your installation of Bitweaver, called Wiki Help where you can find some TikiWikiSyntax.




Before


Can you describe the structure of Bitweaver?


Bitweaver has a core (required packages) - Kernel, Liberty, Storage, Themes, Users.

Then it has packages that you can choose to activate or deactivate - Wiki, Blogs, Newsletters, Articles etc.

Plugins can be added to enhance the package or core functionality.

Modules are what gets positioned in the layout of your site.



How to install Bitweaver


Bitweaver is very easy to install. The installer checks your server details, sets up your database, lets you choose packages and features, and can also add sample data. To see what the installer does, before installing Bitweaver yourself, you can watch this video: Bitweaver Installation (Screencast).

Note: the installer can be used to un-install packages and database content too. Its technical name could be a runinstaller instead, to avoid confusion.




After


General


Can I make my site any faster?


See What is caching? in this guide.



How do I add my own HTML code to a box/widget?


Go to Admin > Themes > Custom modules. Give the new module a name (reference only), a title (that appears on the site) and enter your code (HTML or Javascript). Preview and save.

Click on the assign icon (paperclip) down the bottom of that same page to jump to the Layout page to place the box/widget/module where you want it. There is a tab for Modules which holds a drop down menu to choose between all available modules of all active packages.



How do I add my own drop-down menus to the navigation bar?


Copy /yourbitweaver/kernel/templates/top_bar.tpl to /yourbitweaver/themes/styles/yourstyle/top_bar.tpl and edit this file. Knowledge of HTML is required.



How do I allow users to send messages to each other?


This package must be 'checked' in Admin > Kernel > Packages (see both installed and uninstalled tabs).

Then the permissions need to be set for who is allowed to send messages to each other.

Admin > Users > Permissions Maintenance



How do I block people (registered users) from seeing menu's and assign permissions?


What I did was to edit one of the groups that have already been assigned permissions (the ability to do or see certain things on the site) so that they could see the items in the menu bar that I wanted to be public, but if they were not admin, they couldn't see 'my' menu (more on that later).

To do this go to Kernel > Users > Groups & Permissions and you will see what permissions are the default.

What I did was change the registered users group, by clicking on the edit icon in the top right section of the page where registered users list is, and going to the Assign Permissions tab.

I striped most things out, as I am rolling out the site in stages. So I launched the forums (installed phpbb) first. Then the wiki/image galleries/file galleries will come next, along with newsletters, rss etc.

At each stage I can change the permissions for the registered users group - adding more as I choose.

Now about the admin menu. I used the nexus package to make a totally separate menu from the one that is displayed to the registered users (or the anonymous group).

The Nexus menu is not the same as the drop-down global menu. Each item must be added individually and they do not expand and collapse.

Go to the Admin menu > Nexus and slide across to Nexus menu. It takes you to a page where you set up a few of the parameters for your custom menu. For arguments sake call it 'admin menu' and save settings.

Now I am going from memory, but I think it automatically takes you to the next screen where you choose what to have in your menu.

Most of what you will need will mean that you choose "URL" as the resource type. Don't get too overwhelmed by this page. Enter a title, choose "URL" and enter the url in the next box.

Save the item. Add as many as you need to use on your site.

The urls are fairly intuitive. They follow the loose rules of:


<?php
[nameofpackage]/[function].php
?>

Therefore
fisheye/upload.php
wiki/list_pages.php
treasury/edit_gallery.php

So once you are happy with the menu items you have for your menu, there is one last thing for you to do.

Go to Admin > Theme > Configure layouts

You will see the default setting for the layout of your site, and any others you have installed.

Choose to Edit this layout(s) you want to have the menu on. Scroll down to the bottom of the page, to the assign column module tab.

In the drop down field for Module you should see the name for your admin menu.

Select it, choose a position, and order if this is important to you.

The key here is to select administrators in the groups box almost at the bottom of the page, and my recommendation is to apply it to all layouts - because you don't want to go off and work on one of the packages and either not be able to get back or not be able to insert images or whatever you feel is necessary that you added to your admin menu.



How do I change what boxes/widgets/modules are showing on my site?


First let me say that you can have a different layout for (at least) each different core package that you choose to install (wiki, blogs, boards etc).

You would go to Admin > Themes > Configure Layout Options

Here you will find the layouts of all the packages that you have installed.

Scroll down to the one you want. Click on 'edit this layout' above the section.

You will see the various parts of your page - column(s), top area and bottom areas.

  • To delete a module - click on the shredder
  • To change the position of a module - use the arrows
  • (If it is a custom module (see above 'How do I add my own html code to a box/widget?') then you will see an edit button too.)

To add a new module scroll down to the bottom of the page

Choose your Module from the drop down box

  • Choose where you want it to go in the Position field.
  • Give it a title
  • Choose the order in which it will appear in the section that you would like to add it to.

  • Select the groups of users who can see this module if you want to.

NOTE:
Admins by default see all modules. If you want to change this see Is there any way to turn off modules for Admins

Registered users inherent Anonymous permissions too. See Registered users can still see modules



How do I create my own menu?


See: How do I block people (registered users) from seeing menu's and assign permissions? in this guide.



How do I escape code?


See: How do I get code to show in a page instead of activating?



How do I get messages sent to my email (without always having to log in to the site to read them)?


Go to your user profile by clicking on your user name under the log in box or via Home page > List Users click on your name; choose preferences (the cog icon) and User Messages. Select your choice for send an email.



How do I get help?


This will depend on what type of help you need. Leaving a post in the forum's at present may not be the most expedient method of communication.

If you have something that you think is going wrong with your site that shouldn't be (ie you are receiving error messages, White Screens etc) then register this 'Bug' at SourceForge. There are so many varieties of computers, databases and servers that the developers can't really test on all platforms. You will be helping the community by reporting your anomaly - just make sure you give as many details as you can.

Or if you are more technically savvy, login to the Bitweaver Chat at Freenode. This is where the developers hang-out but be warned its predominantly tech-speak.



How do I find out how many visitors my site has?


Included in Bitweaver is a statistics package. The data collection starts from the day the programme is installed.

Administration > Stats > Site Stats for statistics about your site packages and views or

Administration > Stats > Referer Stats for information about which sites refer to yours.

If you want to start your statistics collection again, you can run the installer to de-install the package and choose 'delete package content' too (which cleans out your database) and then re-install.



How do I know if someone has changed something on my site?


To get noticed via email, go to Admin > Kernel > Notification and select the event that you want to be notified for, choose the email address and you're done!

To see what happened on your site, go to Bitweaver's 'Action Log' in Admin > Liberty > Action Logs. This table lists all changes made to content.



How do I translate words that still show in English on my site?


Go to Admin > Languages > Edit Languages. Select your language, check the only untranslated box, and click on the edit translations button. This will bring up a list indexed by letter. Make your changes on each/any page and save.

At the end of your changes you will be prompted to clear the language cache - this is important so that the changes show on your site. You may also need to clear your site cache as well: Admin > Kernel > System Cache

To edit words or phrases that you wish to be translated differently simply leave the 'untranslated' field unchecked and you will get a very big listing of all the words/phrases.

If you'd like to help other users by your translation efforts, please see Bitweaver's translation tutorial.



Is there anyway to turn off modules (for Admins)?


Yes! First go to Theme Settings > Modules require membership and check the box. Then when you configure your layout assign the groups to any/all except admins. See How do I change what boxes/ widgets / modules are showing on my site?



Registered users can still see modules


This is because registered users inherent the anonymous group permissions (for modules at least).

To work around this:

Create a new group in Admin > Users > Groups and Permissions (perhaps calling it "Not registered")

Edit the group in Admin > Permission Maintenance to assign the same permissions to it as 'anonymous'.

Go to 'List User' in your home menu and click on the 'Assign Permissions' icon for 'guest'. Then click on the 'Assign Permission' icon for the new group you created from the list at the bottom and change the default group to the same.

There is one more step, and that is to go (back) into Admin > Themes > Configure Module Options, and amend any modules that you want visible to the new unregistered user group (de-selecting 'Anonymous').




The group permissions have changed


Have you recently upgraded from 2.0 to 2.1? If so there have been a few changes in the databases and tables.

This means that the permissions that are in the Admin > Users > Groups & Permissions are only for the packages you have chosen. The global list got too big to have everything itemised out, and lets face it, it gets tedious to have to wade through stuff you don't need.

So now when you select a new package to include in your Bitweaver site, you will then ALSO need to go to the 'Groups and Permissions' area and assign the relevant permissions.



What about anonymous visitors to my site?


To allow/disallow actions for anonymous visitors: see How do I block people (registered users) from seeing menu's and assign permissions? in this guide for where in Bitweaver the permissions etc are.

To set the homepage of your site: This was already possible to set during the installation of Bitweaver, but can be changed any time: go to Kernel > Kernel settings > Homepage Settings and choose a package from the home page drop down box. The home page of your site will now be the starting page of chosen package. Then, some packages allow for a more specific setting on their respective settings page.

To choose a specific page as home page of your site: Kernel > Kernel settings > Homepage Settings. I chose custom home in the home page drop down box, and then entered the internal URL for the single standalone page that I had made as a front page for my site. In this case: wiki/Welcome. Remember to click on the change preferences at the bottom of the page.

To allow anonymous visitors to see one page that belongs to an generally "forbidden" content type or package: Go to the page that is your home page and click on the Assign permissions icon (usually in the top right). This allows you to assign permissions that override the global permissions for this one page.



What are those words in parentheses/ curly brackets? And how do I use them?


These are helpful commands that are already programmed into the code so you don't have to. In Bitweaver, they are called Data Plugins. They are inserted in Wiki pages. For example:


<?php
{COUNTDOWN}
?>


If you simply type this in your Wiki page as it is, a 'help' will pop up when you preview that page alerting you to the things that you need to add to it for it to work the way that it was programmed to do. This information is also present at your Wiki help tab during editing that page. So lets say that we wanted a countdown since the day we installed Bitweaver, then we would add details inside the parentheses, after the word 'countdown', to end up with:


<?php
{COUNTDOWN enddate='Jul 16 2008' localtime='on' text='since I started to use Bitweaver'}
?>


A full list of what you have installed is on the Wiki Help page in the Data Plugins box. To install or uninstall these plugins, go to Admin > Liberty > Plugins.

(Note: {COUNTDOWN} will not work if you have chosen to cache your site.)



What do all the terms mean?


Bitweaver has a core (required packages) - Kernel, Liberty, Storage, Themes, Users.

Then it has packages that you can choose to activate or deactivate. Wiki, Blogs, Newsletters, Articles etc.

Plugins can be added to enhance the package or core functionality.

Modules are what get positioned in the layout of your site.



What is an Article? How do you use them?


Here is an explanation.



What is a Stencil?


It's a way to make entering data into many same wiki pages uniform. A stencil is set up exactly how you want the data displayed (ie table or paragraph) and then a piece of code that is generated from your stencil is placed in your chosen wiki page, that prompts a person to input certain values during the edit process that when the page is saved renders these as per the manner that the stencil has been set up to do.

So for example you had several pages for family members to enter information about themselves, and you wanted to make them all look the same, you could generate a stencil with first name, surname, birthday, country and then put the code that this generates into individual family member pages for them to fill in when they edit it.

Note: at present it doesn't handle foreign language characters.



What is a Wiki Book?


It is a collection of content from your Bitweaver site - not limited to your Wiki pages, presented like a book. Think of it as a publishing tool for a thesis or report.

One of the Wiki pages that is already in your installation of Bitweaver is "How to create a Wiki Book" or you could just as simply click on Wiki and Create a Wiki book Its fairly straight forward. The page or content needs to be there first though.

If when you go to Add content on the Wiki book page you only see Wiki pages and you know that you have an image or a board to add - use the drop down menu at the top of the page to find the other content types.



What is caching?


Caching is the saving of images, files or information without having to go back to the database where it is stored, too often. to get them afresh. It is useful when there is a lot to load on a page or site.

Bitweaver has caching for the content (that which is entered into the site) in Kernel > System Cache. There is also caching for the modules in Themes > Configure:Layout Options - expand your assigned modules and enter a value there, or enter one when you assign a module.

Cache time is relative to how often one expects to need to see the information refreshed. A header - not so frequently as it is expected to stay the same, an rss feed perhaps 10 minutes - as how much more frequently would you check it than that?

The only modules that should *not* be cached are 'login' and the 'user' ones like 'user profile', 'user content' etc. A user would expect that if they made a change here it would show up automatically.

(Note: BW also has session times.)



What is the difference between tags, pigeonholes and categories?


What they have in common is that they can be used to group content together, regardless of the content's type: - images, galleries, wiki pages, comments, blog postings etc can all be grouped together to one theme ie "last year's wedding". (Much like a wiki book - see above.)

The 'Tags Package' is everything you read at Wikipedia about tags. Users input keywords, they are displayed as a cloud or as a list. They are non-hierarchical. (Grouping of tags like del.icio.us is not possible (yet).) To put it another way, they are random words that the user decides to describe the content. They evolve with the users and the site.

'Pigeonholes' and 'Categories', on the other hand, are both categorization packages. The basic concept is a hierarchical one. 'Pigeonholes' is fundamentally better than 'Categories'. To see at the features go to Admin > Pigeonholes > Settings.

Categorisation is pre-determined (usually by the site administrator or those with permissions to do so).

Pigeonholes has more features and modules. You can display content that belongs to each other in a side module, or you can apply a different site style depending on the category as a couple of examples.

A source of confusion might be, that Categories and Pigeonholes are both category-packages, but only one of them is named like that. The reason for that is the modularity of Bitweaver.

See also:



What package is what?


See this page: for explanations of the packages.



Why are there so many packages in Bitweaver?


There is not one package for each content type - there are many - "Packages are king!".

To handle images, you can use Fisheye, Gallery2 (?), or write your own package (and name it as you like). There isn't really one "Bitweaver image gallery package" or "Bitweaver categorization package".

If you write your own package you can name it for its function, subsequent packages normally adopt synonymous names. If you're writing a Tags package now or an Events package, there are two names that you probably wouldn't pick. (You can instead extend an existing package instead of writing one from scratch!)

Two other packages that overlap in function are 'Stars' and 'Recommends', as well as 'Search' and 'Ilike'



Where do I start? Where to from here?


Now you are ready to select the packages that you need for your site.

Read the description of each and consider if you REALLY need it - focus on the main component(s) of your site - you can enable packages again in the future.

There is so much potential with this CMS that it will blow your mind.

Wiki


Do my headings have to be red?


No. Red is the colour set as a default example if you are using wiki syntax for your site. You can choose any standard colour name or number such as: blue, purple, yellow, #2f89fa, #ff6600 and so on.

If instead, your wiki is set to html as the default and you have installed FCKeditor, your heading styles will be picked up from your css (cascading style sheet). To edit these you will need to know your way around your file system.



How can users upload images directly during edit?


Yes! This is automatically a default in many of the packages.

However you may wish to go to Admin > Liberty > Liberty settings and check Ajax attachments which allows the user to note the id immediately during the edit process so they can use it. While you are there check Enforce content status.



How do I add a document to a page or a posting?


First you need to upload the document to a Treasury gallery: go to Create Gallery in the drop down Treasury menu and the rest is fairly explanatory. Then to put a document into it go to: Admin > Liberty > Liberty settings

Treasury > Upload File

Enter a title (this effectively renames the file as this is what shows when you use the file on a page). Description is optional. Choose the gallery it is to go into. Click upload file.

Having done this Bitweaver will have assigned a numerical ID to it. To find out what this is, go to the gallery via the menu bar to List Galleries (or if your installation shows the path, click on the gallery name). Choose the gallery and it will list all the contents. Notice the ID number - this is what you will want to copy and paste to the page you want to use the file in.

This makes a link to the file number 67 appear in the page.


<?php
{file id=67}
?>




How do I add an image to a page or a posting?


There are two ways: either uploading directly to Fisheye, or if the site allows uploading during the edit of a page, article, blog post etc.

Fisheye

Go to Create Gallery in the drop down Fisheye menu and the rest is fairly explanatory. Then, to put an image into the gallery go to: Fisheye > Upload Images

You will see title and description boxes, but may also see that there are options for how to handle the upload - like rotation and resizing.
Choose the gallery it is to go into. Click upload file. Having done this, Bitweaver will have assigned a numerical ID to it. It is displayed underneath the image for you to copy and use in pages or postings.

You can also go to the Home Page drop down menu on the top menu bar to All available content and scroll through to find newly uploaded image, as it is ordered by date. In any case, the code you're looking for looks something similar to:


<?php
{attachment id=918}
?>


Pasting this into a page or posting means that the image number 918 will be displayed inline. Any attachment can be displayed like this. For images though there is an added feature - and that is the variable sizing. When you upload an image, Bitweaver processes it into five different sizes and saves the original too: icon, avatar, small, medium, large, original. Following this standard you can define the image size by:


<?php
{attachment id=918 size=icon}
?>

During Edit

If this setting is enabled then you will see a tab behind the package that you are editing. Click on the tab, find your image and upload.



How do I create a link to another wiki page?


On the page that you want to link from, put 2 open parentheses around each end of the word.


<?php
((yourword))
?>

When you save this page, this word will appear to want to create a link. Simply click on the word and it will take you to creating a new page.



How do I create a link to a board?


Create the board first.

Go to Boards tab and scroll down to Create new Board. Give it a title and a description as you wish and Save the page.

Then go back to the Boards tab and choose the Boards Home option.
This lists your boards. Hover your mouse over the name of the board you want to link to and note the number of the board down the bottom of your browser.

Then on the page that you want to link from, use square bracket to enclose the path to find the board.


<?php
[/sitename/boards/index.php?b=#|boardname]
?>

'sitename' will be the directory that your bitweaver was put into
'#' is the specific number of the board that you want to link directly to
'boardname' is the name that you want to appear on the page that you want to link from.



How do I create a table of contents for a wiki page?


First you need to make sure that you use the exclamation marks at the beginning of any line that you want to be made into a heading.

  • One '! for a big heading
  • Two '!' for a medium heading
  • Three '!' for a small heading

Then you click on the icon at the top of your wiki page for Page Table of Contents when you are where the table of contents is to go.

It automatically picks up the headings.

For further ways you can customise your table of contents refer to the Wiki Help tab.

The headings on this page for what it is worth are using '!!!', and colour.



How do I get Wiki pages to link when I am using a foreign language or special characters?


This is still under discussion in the forums.

One person got the Wikilinks to work in the German language by:

Going to the Admin tab, scrolling down to Wiki, across to Wiki settings, where you see several tabbed pages. Go to the Wiki settings tab. Find the Wiki Link Format and choose Complete

And another person, also for a Wiki in German, chose: Latin

So go figure!



How do I get code to show in a page instead of activating?


Normally, when you write plugin code (in curly brackets) into a wiki page, Bitweaver will run it. If you want to display the string of the plugin code instead (for instance, on a page like the one you are reading), you can use TikiWikiSyntax:
{code}


So if you wanted to show

<?php
{attachment id=918 size=icon}
?>
then it would look like

{code}{attachment id=918 size=icon}{code}




How do I use HTML in a Wiki page?


Wiki pages are usually written in Wiki Markup language. So to include HTML (another language) you need to have Allow HTML checked in Admin > Liberty > Plugins > Format. When using HTML in wiki pages, you should also activate HTMLPurifier for security reasons, in Admin > Liberty > Plugins > Format.

You will also need to go to the Group Permissions area and adjust which groups are allowed to use this feature. See How do I block people (registered users) from seeing menu's and assign permissions? in this guide.

Otherwise you may choose not to have the Wiki Markup language enabled and instead choose an html option in the Format Plugins area. All the commands in {}'s will still work in an html only site.




Unfortunately because most, if not all web servers, are controlled by Apache (mod_rewrite), it doesn't like the use of an '/' in combination with Pretty URLs.

So the only solution, if you want to use '/' is to turn off Pretty URLs:

Admin > Kernel > Settings - Make sure 'Use Pretty Urls' is unchecked and remember to click on 'Change preferences' down the bottom of the page.




This is because Bitweaver automagically (ie 'hey presto') thinks words that have an underscore or a hyphen in them, or that are written in caps, are going to be a new page.

An underscore is a common way for titles to be written instead of running all the words together.

So if this is annoying you, you will need to go to the Admin drop-down menu, choose Wiki and slide across to Wiki settings.

You will see a series of tabbed pages. Click on the In and Output tab

On this page is the checkbox for Wikiwords. (I understand these were called Hotwords in previous versions perhaps). If you uncheck it, then you won't have the 'problem' with words wanting to be links.

Remember to go to the bottom of the page and choose Change Preferences



What is 'Edit Page Sections' in Wiki features?


This is an option for the edit button to be placed more frequently on a wiki page so that a person may edit only part of the section. The default is 'disabled' (so the entire page is loaded for editing) or it can be set to appear alongside 'H1' or 'H2' so the sections following these headers are edited separately.



What if I want my site to be HTML only?


This decision is better made before you even start creating pages, but given that you probably have made this decision after experimenting a little with Bitweaver and TikiWiki is the default, here are the instructions for changing your site over including pages.

Go to Admin > Liberty > Plugins, Formats tab, and check Allow HTML.

Open each Wiki page and edit the content in the page to be html and edit the page type to be html. Do this to each page before you make the final changeover in the Administration area, otherwise you will not even be able to see anything on any page.

Once all pages are changed to html, then you can go to Admin > Liberty > Plugins, Formats tab, and check the Bithtml button and uncheck the Tikiwiki (default) button.



See also:




Comments

Well done!

by Kozuch, 18 Jul 2008 (09:50 UTC)
This is a great stuff. Looking forward to seeing it completed!

Watch all pages upon edit?

by Chris, 02 Jul 2010 (07:23 UTC)
I'm used to MediaWiki, and love having all pages watched by default when I edit them, or at least a non-default option for such. Like the subscription option on forums, I tend to assume this is the default everywhere and jump right in, then later I sometimes realize by the lack of messages in my inbox that it's not. I can't find anything on this page that even hints this has been considered for inclusion; I shall look through the official docs, though.