History of ThemeTutorial

Differences from version 40 to 45



@@ -1,295 +1,84 @@

-This page is supposed to provide some information on how to create a theme for bitweaver.
+{maketoc maxdepth=2}
 
-there are some detailed informations on how the CssSchema is set up and how to use it without getting frustrated, cos "__so many things change__ every time i change only one class".
+This page provides information on how to create a theme for Bitweaver. For details on classes and IDs, see ((CssSchema|Bitweaver's CSS Schema)). About themes and styles: a __theme__ is how Bitweaver looks and feels. A theme consists mainly of a style, located in -+/yourbitweaver/themes/styles/yourstyle/+-, and also of a layout, an icon set, modules, and other details. The __style__ consists of CSS files and template files (which override Bitweaver's default template files). Although a style is part of a theme, a __style__ tends to dominate the look of a Bitweaver install. That is why ''theme'' and ''style'' are often used synonymously.
 
-{maketoc}
-!tips, hints and tricks
-!!browser
-personally i use [http://www.opera.com|opera] as the browser of choice due to it's state-of-the-art css and XHTML compliancy and the possibility to customise everything yourself. if you want to use opera, please visit [http://www.literarymoose.info/opera/|Literary Moose's Opera Pages] for information on how to turn your opera into an incredible designers tool. (__i think the link might be dead. please update the link or replace it if you know of another good opera resource__)
+! Getting started
 
-for beginners, however, i recommend [http://www.mozilla.org|firefox] and the webdeveloper extension. both of these browsers are cross plattform.
+!! Picking a style
+To customize Bitweaver, you should pick a style that already exists and more or less looks like the one your wish to end up with - considering its layout, module positions, menu placements and so on. Bitweaver's themes use DIV-based layouts (40 presets called [http://blog.html.it/layoutgala/|Layout Gala]). Details, however, are controlled in your customized CSS files and templates.
 
-!!pick an appropriate starting theme
-if you want to customise a theme according to your needs, you should pick a theme that more or less has a layout you wish to use. if you are a complete beginner, it might be useful to start with a theme that uses a table based layout as these are much more forgiving and much easier to set up. such themes include: basic, bitweaver, july4.
+All styles that are available on your site are located in /themes/styles/. The style called __blank__ (its CSS file lists off all the most important classes and IDs), and the style __cascader__ (its CSS contains only the most important layout definitions) are good starting points for theme development.
 
-most other themes use a div based layout system, which is more sophisticated to set up. if your changes, however, are minor, such as modifying the colours or the font-size, you should be able to pick one of these themes as well.
+!! Browser
+Use a state-of-the-art CSS and XHTML compliant browser for development, and take care of backwards compatibility to old browsers later. Consider [http://www.opera.com|opera] which has the possibility to customise everything yourself and can be [http://nontroppo.org/wiki/MooseCSS|turned into an incredible designers tool], or [http://www.mozilla.com/|Mozilla Firefox], which can be extended with extremely useful plugins for development like [https://addons.mozilla.org/de/firefox/addon/60|Web Developer], https://addons.mozilla.org/de/firefox/addon/271|ColorZilla] and [https://addons.mozilla.org/de/firefox/addon/1843|Firebug], among others.
 
-!!source code
-we use the smarty templating engine and we apply the {strip} tag to most templates to remove any excess whitespace characters. this reduces the download size of the html pages but also results in an html code that is very difficult to read. to make the source code readable, i recommend you change the following in your bitweaver install:
+!! Applying Changes
+If your environment for theme development is set up correctly, ss soon as you've made changes in your style's CSS file, they will be visible in your browser after you have reloaded the page. If the changes don't appear
+* make sure you don't have any spelling mistakes (syntax highlighting helps)
+* make sure you are addressing the correct class or id (check the source of the page if the class or id exists)
+* make sure you are using the correct selectors (''a.external'' is not the same as ''.external a'')
+* use more specific selectors (a.external is better than .external for many reasons)
+* try using !important in your definition (e.g., border:1px solid #000 !important;) for testing
 
-/util/smarty/libs/Smarty_Compiler.class.php line 335
-from
-{code source='PHP' num=335}$text_blocks[$j] = preg_replace('![\t ]*[\r\n]+[\t ]*!', '', $text_blocks[$j]);{/code}
-to
-{code source='PHP' num=335}$text_blocks[$j] = preg_replace('![\t ]*[\r\n]+[\t ]*!', "\n", $text_blocks[$j]);{/code}
+!! Readable source code
+Bitweaver uses the [http://smarty.net/|Smarty] templating engine. The {strip} tag is applied to most templates to remove excess whitespace characters. This reduces the download size of the HTML pages and, more importantly, makes sure that browsers don't interprete white space as extra pixels to add to the layout. As a result, the source code of any Bitweaver page is very difficult to read without applying some kind of clean up. Use plugins like [https://addons.mozilla.org/de/firefox/addon/697|View formatted source] according to your browser.
 
-__Note__: Make sure to clear out your template cache after making the above change. if you don't you will not see any difference. (administration -> kernel -> system cache, and click "empty" on the line with /temp/templates_c)
+To make the source code readable without any extra plugin, you can change the following in your Bitweaver install (and clear the system cache):
+{code title="/util/smarty/libs/Smarty_Compiler.class.php" source='PHP' num=335}
+// from:
+$text_blocks[$j] = preg_replace('![\t ]*[\r\n]+[\t ]*!', '', $text_blocks[$j]);
+// to:
+$text_blocks[$j] = preg_replace('![\t ]*[\r\n]+[\t ]*!', "\n", $text_blocks[$j]);
+{/code}
 
----
-!the beginning
-!!getting started
-all themes that are available on your site are located in /themes/styles/
-^here you will find one theme called blank. this is a theme which contains all the most important classes and ids listed without any definitions.^
+!! Creating a new Style
+Make a copy of the folder called __blank__ (or any other) and rename the folder to the name of your new style. Within the newly named folder, find the original CSS file __blank.css__ (foldername.css) and rename it to name of your new style as well:
+{code title="copy and rename one style folder and one CSS file"}
+// from:
 
-!!to create a new theme follow these steps
-copy the theme 'blank' (or whichever theme you would like to modify) and rename the folder to your new stylename.
-within <stylename> rename the original css file to <stylename>.css
-hence we go from
+/themes/styles/blank/
 /themes/styles/blank/blank.css
-to
-/themes/styles/<stylename>/<stylename>.css
-
-i will assume that you have copied /blank/ as a starting point
-(if not, please copy all the contents of /blank/ (appart from blank.css and blank_commented.css) to your new theme folder to take full advantage of this tutorial
-
-!!taken from /themes/styles/blank/readme.css
-if you wish to create a theme from scratch here is a list of all css files present in /blank/ to aid you:
-* blank.css
-** main css file with all globally used classes and more
-* customisation.css
-** contains a list of classes that can be utilised to further customise the site
-* debugwithoutline.css
-** contains a set of classes and definitions that allow you to visualise all structures used on your site
-* showdiv.css
-** if included will visualise all divs used on the site including their classes and ids
-** (works well with debugwithoutline.css)
-* showstructure.css
-** like showdiv.css but it will show you all classes and structures appart from divs
-** (works well with showdiv.css and/or debugwithoutline.css
-* showsitelayout.css
-** visualises the layout of the main bit ids used by surrounding them with coloured lines
-* showpagelayout.css
-** draws coloured borders on one side of certain elements
-** to allow you to view the classes used without messing with your layout
-
-!!including css files in your main css file
-to include one of these files in your theme for debugging purposes, you can insert a line at the top of your css file
-@import url("include.css");
-
-do this for as many css files as you wish but note:
-*@import only works when it's __before any definitions__
-*showstructure.css | showdiv.css don't work with MSIE
-**use opera or mozilla to utilise these files
-**debugwithoutline.css only works with opera
-
-i have tested the above with the following browsers:
-*MSIE 6.02 (nothing works regarding structures)
-*Mozilla Firefox 0.8 (everything works appart from debugwithoutline.css)
-*Opera 7.5 (everything works)
-
-!!template file hierarchy
-this is the order in which locations are checked for, for any given template:
-{code source='HTML'}
-themes/force/<package>/
-themes/force/
-themes/styles/<stylename>/<package>/
-themes/styles/<stylename>/
-<package>/templates/
+// to:
+/themes/styles/yourstyle/
+/themes/styles/yourstyle/yourstyle.css
 {/code}
 
-this means that placing a file in themes/force will override any template found in any theme, makes it easy to create a common footer containing copyright information, without having to modify tonnes of files.
 
-we recommend that you make a copy of any template file you wish to edit in your own style directory that the upgrade process to later versions is quick and easy.
+! Templates
+!! Template hierarchy
+The general process of modifying a template is to __copy it from its location in bitweaver/package/templates/template.tpl to your style's directory: bitweaver/themes/styles/yourstyle/package/template.tpl__. Now the upgrade process to new versions of Bitweaver is quick and easy. The following is the order in which locations are checked for a given template. If Bitweaver doesn't find the template -+wiki/templates/editpage.tpl+- in the first location, -+themes/force/wiki/editpage.tpl+-, it moves on to look for it in the second location, and so on:
 
-^now we are ready to start with the css files.^
-
-!the css
-!!introduction
-if you are coming from TikiWiki, you will notice that the css is much smaller compared to that of TikiWiki and there are very much fewer classes used.
-
-This, however has absolutely nothing to do with the flexibility and power of the css file over the design of bitweaver. in fact, it's much easier and quicker to create a site that has an overall feel throughout. moreover, it's easy to customise particular sections exactly the way you need them if you so desire.
-
-a certain level of css knowlegde however is required to do this.
-
-^if you feel that you 'know' css you can use the 'blank' theme as a starting point for your new theme. please consult the readme in the 'blank' folder for further information.
-
-__please note__:
-there is a file called __base.css__ which is called by most themes using @import at the top of the css file. this css contains some definitions which make theming easier due to it's generic settings that set a base for difficult settings such as the css dropdown menus.^
-
-however, if you believe that there is something to be learnt from this brief tutorial, carry on reading... first of all it's important that you have a look at CssSchema, which has a basic layout of the site in terms of classes used on all output pages.
-
-
-!!a simple example
-1. <div class="box">text</div>
-2. <div class="module box">text</div>
-3. <div class="admin box">text</div>
-
-if you define the following:
-{code source='CSS'}
-.box { font-weight: bold; }
+{code source='HTML' title='order in which locations are checked for a given template'}
+1. themes/force/package/
+2. themes/force/
+3. themes/styles/style/package/
+4. themes/styles/style/
+5. package/templates/
 {/code}
 
-it will result in the following:
-1. __text__
-2. __text__
-3. __text__
+This means, placing a file in themes/force will override any template found in any style folder. For example, you can create a footer containing copyright information which will be applied to any style used on your site, without having to modify all the footer files of all available styles.
 
-the text in all three cases will be bold, however, if you define it like this:
-{code source='CSS'}
-.box { font-weight: bold; }
-.module { color: red; }
-.admin { color: blue; }
-{/code}
+Most of the templates have the same name as "their" PHP file, only with .tpl as the extension. Some specific .tpl files are only used as an inclusion and can't be used on their own. These are marked with an additional _inc at the end of the filename.
 
-it will result in the following:
-1. __text__
-2. ~~#FF0000:__text__~~
-3. ~~#0000FF:__text__~~
+!! Force templates
+If you would like to force the use of a given template for all styles but don't want to edit all source files, you can create a directory called __bitweaver/themes/force/__. Any template found here, will override any other template unconditionally. This is an excellent technique for creating a single top_bar for your site if you use multiple themes.
 
-this allows you to create a general style, look, feel using very few classes such as .box above (all the above are bold) but then go on and customise and finetune particular sections or groups of items simply.
 
+! The CSS
+Because Bitweaver's CSS tree of classes and ID is so efficient, its CSS files are quite small and not many classes are used. This makes your styles flexible and powerful. Moreover, it's easy to customise particular sections exactly the way you need them.
 
-!!slightly more interesting
-furthermore, it's easy to modify classes that are defined within other classes using the correct selectors.
+Please Note: There is a file called __base.css__ which is called by some styles using -+@import+-. This CSS contains some definitions which make theming easier due to it's generic settings for Javascript tabs, Suckerfush CSS dropdown menus, and others.
 
-consider the following 2 pages:
+For details on actually editing CSS files, cascading selectors, and hacking around browser bugs, please consult the appropriate online guides or books.
 
----
+! Slideshows
+Slideshows are a feature of Bitweaver's ((WikiPacakage|wiki package)) and allow you to display a wiki page in a particular way without any excess information such as columns or banners. The slides are set up in a similar way as the wiki page and use the same classes. You can pick a theme that will be used when displaying wiki pages as a slideshow.
 
-{code source='CSS'}
-<div class="wiki">
- <h1 class="title">pile of foo</h1>
- <div class="content">this is more foo</div>
-</div>
-{/code}
+To use your own theme as the style for slideshows but would like something like '__larger text__', you can create slideshow.css in your theme directory and add all your definitions in there. This file will be loaded in addition to your regular CSS and you can thus override any settings made above. Also, there is a folder called -+slideshows+-. It contains sample slideshow.css files, which you can copy (and rename) to your theme dir to use as blueprints.
 
----
+So, the easiest method to enlarge your slideshow text, is to create a file called 'slideshow.css' in your theme directory and then copy and paste the content of 'slideshows/enlargetext.css' to that file and save - voila!
 
-{code source='CSS'}
-<div class="articles">
- <h1 class="title">pile of foo</h1>
- <div class="content">this is more foo</div>
-</div>
-{/code}
-
----
-
-the above only differ in the first line - either __wiki__ or __articles__. as above it's easy to aply general definitions to title, and content. however it's also possible to influence, say, the __content__ section of __articles__ without changing settings in the __wiki__ by defining the following:
-
-{code source='CSS'}
-.articles .content { background: silver; }
-{/code}
-
-
-!!the nitty gritty
-consider the following page
-
----
-
-{code source='HTML'}
-<div class="box">zero plus two equals one</div>
-
-<div class="foo">
- <div class="box">i can sing</div>
- <div class="foo box">some chickens have lips</div>
-</div>
-{/code}
-
----
-
-if you wish to apply a definition to all boxes you use
-{code source='CSS'}
-.box { text-decoration: underline; }
-{/code}
-
-===zero plus two equals one===
-===i can sing===
-===some chickens have lips===
----
-
-if you wish to apply settings only to the boxes within the foo section
-{code source='CSS'}
-.box { text-decoration: underline; }
-.foo .box { font-weight: bold; }
-{/code}
-
-===zero plus two equals one===
-__===i can sing===__
-__===some chickens have lips===__
----
-
-if you wish to apply settings only to the box that has foo associated with it
-{code source='CSS'}
-.box { text-decoration: underline; }
-.foo .box { font-weight: bold; }
-.foo.box { color: red; }
-{/code}
-
-the result of all three definitions would be
-===zero plus two equals one===
-__===i can sing===__
-~~#FF0000:__===some chickens have lips===__~~
----
-
-^please note the lack of a space in the third case as compared to the second case.
-'~~#FF0000:.foo .box~~' vs '~~#FF0000:.foo.box~~'^
-
-^__note for MSIE__: MSIE only renders .foo.box {...} if this is the actual order in which they are mentioned. i.e. .foo.box {...}
-only renders if the class is called:
-class="~~#FF0000:foo box~~"
-and not:
-class="~~#FF0000:box foo~~"^
-
-obviously you can apply a setting to only the top box by setting definitions something like this
-{code source='CSS'}
-.box { color: blue; }
-.foo .box { color: black }
-{/code}
-
-~~#0000FF:zero plus two equals one~~
-i can sing
-some chickens have lips
-
-as you can see, you have an immense amount of power if you wish to use these features.
-
----
-!building the theme
-Well the first thing you'll probably want to start with is font style and background.
-{code source='CSS'}
-* {
- color: blue;
- font-family: sans-serif;
- font-size: normal;
- font-style: normal;
- font-weight: normal;
- text-decoration: none;
-}
-body {
- background-color: gray;
- background-image: url("images/background.jpg");
-}
-{/code}
-
-Take a look at CssSchema and see how you want to layout your site. Lets say you wanted __#bittop__ to always be 120px high with a silver background, you'd set accordingly.
-{code source='CSS'}
-#bittop {
- background-color: silver;
- height: 120px;
-}
-{/code}
-
-Next, you'd like to set a border around __#bitmain__.
-{code source='CSS'}
-#bitmain {
- border: thin solid black;
-}
-{/code}
-
-more to come...
-
----
-!slideshows
-slideshows are a feature of the wiki and allow you to display the wiki page in a particular way without any excess information such as columns or banner.
-
-the slideshow pages are set up in a similar way as the wiki page and use the same classes. you can pick a theme that will be used when displaying wiki pages as a slideshow.
-
-if you would like to use your own theme as the style for slideshows but would like something like '__larger text__', you can create slideshow.css in your theme directory and add all your definitions in there. this file will be loaded in addition to your regular css and you can thus override any settings made above.
-
-also, there is a folder called slideshows. this contains some sample slideshow.css files, which you can copy (and rename) to your theme dir, saving you some time.
-
-so, the easiest method to enlarge your slideshow text, is to create a file called 'slideshow.css' in your theme directory and then copy and paste the content of 'slideshows/enlargetext.css' to that file and save - voila!
-
-just to illustrate, here is the content of enlargetext.css:
+To illustrate, here is the content of enlargetext.css:
 {code source='CSS'}
 h1,.title {
  font-size: 2.4em;

@@ -301,53 +90,36 @@

 }
 {/code}
 
----
-!the icons
-in bitweaver it is possible to use your own set of icons to give the site the ultimate in customisation and theming flexibility.
+! Icons
+In Bitweaver it is possible to use your own set of icons to give your site the ultimate in customisation and theming flexibility. Associate any icon with a given theme by creating an icon in the folder -+/themes/styles/style/icons/package/+-
 
-currently it is possible to associate any icon with a given theme by creating an icon in the folder
-/themes/styles/<style>/icons/<package>/
+The extension of the icon has to be: __jpg, gif, png__. Icons in the above location will override the original Bitweaver icon. This allows you to integrate icons without having to touch the source code.
 
-the extension of the icon is irrelevant. if a file with the same name as the original icon is found in the above location, it will override the original icon. this allows you to fully customise the feel of your site, even integrating icons in the mix, wihout you ever having to touch the source code.
-
-^Note: only available from version ReleaseOne onwards.^
-
-more to come...
-
----
-!Style information
-i recently modified the theme selection page to display a theme specific image and a short description. to take advantage of this feature, you need to follow the following steps:
-
-create a folder called ''style_info'' in your theme directory. in there you can add a file called description.htm, which should contain a brief description of your theme in html format (XHTML 1.0 Strict).
-
-the image for the theme needs to be named preview.<ext> (the extension doesn't matter. this can be any image format). as a standard, it would be good, not to exceede 160px width for the image.
-
----
-!The Templates
-template files can be found in the directories <package>/templates. most of the templates have the same name as the php file, using .tpl as the extension. some specific .tpl files are only used as an inclusion and can't be used on their own. these are marked with an additional _inc at the end of the filename.
-
-If you wish to edit any one of these templates, we recommend that you create a copy of the file in your theme folder and modify the copy there. The structure in the theme folder should be
-/themes/styles/<style>/<package>/<template>.tpl
-lazy sods can copy the templates into
-/themes/styles/<style>/<template>.tpl
-allthough there may be a risk of file name collision if two package templates have the same name.
-
-!!Use the Force
-If you would like to force the use of a given template for all themes but don't want to edit the source files, you can create a directory called force. Any templates found here, will override any other templates unconditionally.
-/themes/~~red:force~~/<package>/<template>.tpl
-once again, spastics can use
-/themes/~~red:force~~/<template>.tpl
-
-This is an excellent technique for creating a single top_bar for your site if you use multiple themes.
-
-This will allow easy upgrading of your system if you should require this at some point.
-
-more to come...
-
----
-!the css drop down menus
-((Tutorial - Native Theme|Tutorial Native Theme CSS Dropdowns))
 
+! Style Information
+Create a folder called __style_info__ in your style directory. In there, add a file called __description.htm__, which should contain a brief description of your theme in HTML format. Then, add a small preview thumbnail for the style named __preview.ext__ (the extension doesn't matter).
 
+This info is displayed to the admin of a Bitweaver install when he picks a style in ''Admin » Themes » Themes Manager'''. It is also displayed then you upload your custom style to bitweaver.org so that others can download it.
 
+! Debugging help
+If you create a style from scratch, here is a list of all CSS files present in /blank/ to aid you, see /themes/styles/blank/readme.css:
+* blank.css
+** main css file with all globally used classes and more
+* customisation.css
+** contains a list of classes that can be utilised to further customise the site
+* debugwithoutline.css
+** contains a set of classes and definitions that allow you to visualise all structures used on your site
+* showdiv.css
+** if included will visualise all divs used on the site including their classes and ids
+** (works well with debugwithoutline.css)
+* showstructure.css
+** like showdiv.css but it will show you all classes and structures appart from divs
+** (works well with showdiv.css and/or debugwithoutline.css
+* showsitelayout.css
+** visualises the layout of the main bit ids used by surrounding them with coloured lines
+* showpagelayout.css
+** draws coloured borders on one side of certain elements
+** to allow you to view the classes used without messing with your layout
 
+To include one of these files in your own style for debugging purposes, insert
+-+@import url("include.css");+- at the top of your CSS file. Note that @import only works when it's ''before any definitions'' and that some more sophisticated debugging methods only work with advanced browsers.
Page History
Date/CommentUserIPVersion
30 Oct 2008 (17:12 UTC)
removed HTML before it's stripped out again, removed outdated CSS help, re-structured the whole page, less words
laetzer141.20.150.4345
Current • Source
charles75.160.109.23544
View • Compare • Difference • Source
laetzer85.178.10.6243
View • Compare • Difference • Source
xing194.152.164.4541
View • Compare • Difference • Source
Kozuch88.100.108.15940
View • Compare • Difference • Source
xing194.152.164.4535
View • Compare • Difference • Source
xing194.152.164.4534
View • Compare • Difference • Source
xing194.152.164.4533
View • Compare • Difference • Source
xing194.152.164.4532
View • Compare • Difference • Source
xing194.152.164.4531
View • Compare • Difference • Source
xing194.152.164.4530
View • Compare • Difference • Source
xing194.152.164.4529
View • Compare • Difference • Source
spiderr66.93.240.20428
View • Compare • Difference • Source
xing194.152.164.4527
View • Compare • Difference • Source
xing194.152.164.4526
View • Compare • Difference • Source
xing194.152.164.4525
View • Compare • Difference • Source
xing194.152.164.4524
View • Compare • Difference • Source
xing194.152.164.4523
View • Compare • Difference • Source
xing194.152.164.4522
View • Compare • Difference • Source
xing194.152.164.4521
View • Compare • Difference • Source
xing194.152.164.4520
View • Compare • Difference • Source
xing194.152.164.4519
View • Compare • Difference • Source
xing194.152.164.4518
View • Compare • Difference • Source
fire203.229.38.12417
View • Compare • Difference • Source
xing194.152.164.4516
View • Compare • Difference • Source
xing62.99.189.13015
View • Compare • Difference • Source