corzblog (about)

corzblog.. I trust it with my blog™

welcome to corzblog!

This document attempts to provide all the information you need to get corzblog up and running on your website or personal server. Usually it's trivially easy.

what is corzblog?

It's a blogging package, a specialized form of content-management software, enabling you to easily maintain a "Web Log", or "blog", which is an online journal, a.k.a. diary. But it can be whatever you want it to be. Essentially, it allows mere mortals to produce beautiful HTML documents. corzblog III (in progress) produces lovely xhtml.

You can create and edit your blogs from anywhere online using a standard web browser; on the road, in an internet café, wherever. All styling is achieved with easy-to-use bbcode. No HTML knowledge required! The "bbcode parser" that does all magic can be had separately, too.

The page you are reading right now was created with corzblog. The "blogs" menu in the sidebar allows readers to jump directly to the various entries. With a wide range of useful features, it's perfectly at home creating technical manuals, version histories, all-sorts. I spotted a site using it for a glossary system. A large amount of the copy on corz.org was created with corzblog. It makes xhtml easy™.

corzblog uses similar controls and concepts to my favourite bulletin board software, phpbb. In many ways, a blog is just like a bulletin board thread, except only you can reply.

The style of corzblog is completely customizable, I just have a thing about orange.

to run, you will need:

• space on a web server running PHP (= v4.2)
• a web browser
• something to say

While not essential, to make full use of corzblog, it is useful to have javascript enabled in your web browser. most rational people do. standards-compliant, command-line browsers like lynx work just fine. you will also need the text editor, only once.

quick install

1: unzip

preferably right where it will be used. or just unzip it anywhere and drop/upload the whole "blog" folder into the root of your web server, or wherever you like. you can access is right away..

   http://mysite.com/blog/

2: open "config.php" in a text editor

enter your own details. it's self-explanatory. notes within.

3: blog!

file permission should be good from when I archived it (will work on all the major platforms when unzipped in place). The only way to find out, is to blog! If not, see the installation section (next) for details on how to make the blog file writable.

;o)
(or

Installation

three steps..

1: unzip

preferably unzip in place, where it will be used. alternatively, unzip it locally, and drop/upload the "blog" folder into the root of your web server. You can put it anywhere inside your web space, but in the root is cooler.

corzblog tries to figure out where in the server it is operating, but possibly this mechanism isn't foolproof, so a preference is provided for this in the config.php file. You can access your blog right away if you like, an example..

http://example.com/blog/

cooler still, you could create a virtual host or sub-domain specifically for your blog, something like..

http://blog.example.com/

or ..

http://localblog/

2: edit your preferences.

open "config.php" in a text editor and edit in your own details. pick a good password.

important: if you create or edit a blog at an internet café or other public place, ensure that your password hasn't been saved in the machine's memory. check this by clicking the "add blog" link one more time and begin typing the blog title in that field, if a menu pops up, choose your title from that menu and watch to see if the password is entered automatically. If it is, complain to the management and have them remove the password and the password autocomplete functionality immediately.

or just leave it and let everyone edit your blogs.

3: ensure the "blogz" file is writable

you should be good to go; permissions being stored in the zip; but it's possible that something happened to them in transit, getting moved around or uploaded, or whatever. simply; if the blog file isn't "writable", nothing you write can be saved! this is easy to fix..

In a unix/linux/mac os x shell, that would be:

cd /path.to.webserver/blog/
chmod 777 blogz.blog

(yeah, standard code tags work in a blog too)

You can use your FTP client for this too, it's sometimes under "attributes" (set them to "ALL" for "EVERYONE", or equivilent). In aqua (Mac OS X) you can use the "get info" dialog. On Windoze servers, pop up a properties dialog for the file and go to the security tab, or you may prefer DOS "attrib".

You'll want to open "blogz.blog" (the name is configurable in the prefs) in a text editor and DELETE the contents. Then you can start blogging afresh.

alternatively, use the archiving function (click "edit blogs" in the sidebar). If all goes to plan, the intro file should be archived to whatever.blog in the /arc folder, leaving you a nice clean blog to start afresh. you can delete the test archive afterwards.

note: the archive folder also needs to be set to chmod 777 or equivilent. If I remember, there's an informative errror message if it isn't.

;o)
(or

notes

There's some stuff in the "inc" folder you might want to look at.

The only ABSOLUTELY necessary files here are the bbcode parser (obviously), and the "sidebar.php" file, which is the navigation on the left. You could replace these, duplicating their functionality, but not remove entirely. removing the javascript functions file ("js/func.js") would stop the cool quick-code buttons from working)

Most everything else is related to the style of the blog site. Please do mess about with it.

.htaccess

actually, there isn't one of these in the inc/ folder at all, but there is in the main folder, and the arc/ folder too. The main one sets up the character encoding for the whole blog/ folder and directs the server to parse .blog files as html, and the other can (optionally) prevent direct web access to your arc/ folder

if you want to know more about .htaccess files, go here.
note: many operating systems will hide files beginning with a dot

blog_l.css / blue_l.css
blog_r.css / blue_r.css

the styles. edit to your delight. things would look very plain and strange without one of these. But then, ie5 users might like that ;o) there are left and right versions of both the orange and blue schemes.

buttons.php

the buttons for the editor
note the unbuttons

cbparser.php

the bbcode to html to bbcode parser
you can use this on its own for other projects

cbguide.php

the bbcode guide
this gets re-used so much I separated it

corzblog.png

image for the footer.php. see next item.

footer.php

you can leave that as it is, incorporate my logo into something else, or trash it. so long as you leave a link somewhere, it's your call.

js/func.js

javascript functions for the quick-code buttons. If you add something real groovy, let me know.

I sometimes experiment with the <h6> button, it might blow up your browser one day.

metadata.php

this is inserted at the top of every page in corzblog, stuff that browsers like to know. I also chucked the starter for the page generation timer in here, handy.

note: character encoding metadata is hard coded into the pages themselves, reason being, when the webserver finds that data, it reloads the page from scratch with the specified encoding.

It makes sense then, not to go including pages before this process happens. Although utf-8 is specified in the master .htaccess file for corzblog, some webservers ignore this. As they say, your mileage may vary…

sidebar.php

the left/right hand column with the links, edit in your own links

I'd prefer you to leave the "get source" link around somewhere, if possible, ta. I'll update that as I go along for sure.

deleting blog entries

---

Note, there's no mechanism to delete blogs once you publish them. This is by design. If you really must, just edit the text to "deleted!" or something.

If you really really must delete a blog entry, it's easy enough to do in a text editor, so long as (AND THIS IS VERY VERY IMPORTANT) you take care to edit out the correct parts. Each blog entry is terminated with an fictitious <end> tag. There are a few in this "about.blog" file. Select the entry you want to remove, like this..





and just remove that part. It's okay to leave linebreaks between blogs.

Archiving your blogz

---

At the end of each month, you'll probably want to archive your blog. Not only will this save you bandwidth and quicken downloads of your blog (say 100k per month, per page, per page view .. think about it), but keeps everything nice and organised. This is ridiculously easy to achieve:

• click the edit blogs link in the sidebar.
• You'll figure out the rest.

note: you must to ensure that the "arc" directory is world-writable!
(see above for how to set permissions.. probably chmod 777 arc )

Remember that the name you choose for your archive will appear in the sidebar, so don't make it too long. I may add a check for this. As a guide; the blogs menu truncates the individual blog names to 18 characters. I'm using "2003-nov" type names, see left.



bugs:

---

no known bugs


to do:

---

erm.. I'll likely find something.

That's it! Get blogging!

;o)
(or


ps.. this software is free for personal, non-profit use, so long as you leave a link to my site, especially the "powered by" logo in the footer, and perhaps a link to the corzblog source. thanks very much. see the enclosed license (probably called "free-sex.txt" or something like that). Please do read that, there's effort in it, you may be surprised.

upgrading

If you are upgrading from a previous version of corzblog, what do is..

• remove the "arc" folder and "blogz.blog" file from the new distribution (basically, you don't want to replace all the .blog files you have created yourself). you might also want to delete the "about.blog" file, if you have customised that for your own site.
• copy you setting from the old config.php into your new config.php. name, etc.
• upload the new files (minus the blog files) into your webspace, replacing all the previous versions of the files.
• that's it! (really I could of just said "replace everything except your blog files")

• note: if you edit older blog entries, occasionally, in areas where the bbcode parser has been improved, you will get the old-style plain html version of a tag. in these rare instances, if you want the functionality of the new tag, pop-up titles, whatever, simply replace the raw html with the new bbcode tag and all will be well. most folk don't edit old blogs, though.

OS X Webserver

If you run OS X, you can switch on personal web server in your sharing preferences and run corzblog as your personal web log! Simply drop the blog folder into the root of your web server, here..

/Library/WebServer/Documents/

You can then access your blog here..

http://localhost/blog/

And probably by a few other addresses too, on my OS X box it is http://imac/blog/ See the Full Instructions (above) for how to make the blog "live".

If you want to run a few people's blogs on one computer, or just enjoy doing this sort of thing, I recommend you look into setting up some virtual hosts then you could use jimsblog in your browser, or whatever.

;o)
(or

version history

3.0 alpha

* I didn't keep notes. I was working in a style that made that too difficult. Result is very pleasing.

v2.5 final

* The end of the road for regular corzblog. keep an eye out for corzblog pro, coming soon!

v2.4 beta 3

* More improvements to cbparser bbcode parsing engine, added a couple of new URL tags, namely [turl]pop-up title only[/url] and a(t last) [murl]let me know![/url], for inserting your (mashed) email address into the page.

* Happily discovered that you can now get off with using mashed email addresses in RSS/RDF feeds and they will still validate. Consider it done. Because those spambots will discover newsfeeds soon enough! I recommend you upgrade for this reason alone!

* och, a few other things, minor stuff.

v2.4 beta 2

* fixed a potential issue editing old blogs, on some servers, the post wouldn't work, and user is continually redirected back to the choose page.

v2.4 beta 1

* took advantage of cbparser's new balance tags functionality. now if a blogger leaves unalanced bbcode or html tags in their post, corzblog will tell them so at the preview and post stages, offer them a chance to fix it.

* altered the rss 1.0 validation link back to un-htmlencoded. hopefully they've made up their mind now

* moved the sidebar links and titles into the preferences, easier to edit.

* after a seccessful edit of the about page, the link and auto-jump go directly to that page, instead of the main blog. it will, in fact, take you directly to whatever article you were editing. editing standard blogs now does the same thing. neat.

* added a preference for the font size in the edit area

* made all the documentation 100% cbparser compliant! I did most of it when cbparser was in its infancy, and just dropped raw html in where I needed it. cbparser does it all now, even the tables, so this entire page (the one you are reading right now) is created entirely with bbcode! if you edit any of these atricles (or rather, attempt to), you can see the bbcode for yourself.
cbparser changes (also apply to corzblog)

* added extra cell types for the table tags. namely [c5]: 50% wide cell; [c5l]: same, aligned left [c5r]: and right [c2]: colspan="2" (takes up two columns); [c3]: or three colums; [c4]: or four columns. close them all with a standard [/c] tag.

* three new flavours of horizontal rule..
[hr] standard, 70% wide, centered spacer

[hr2] 50 pixels wide, left
[hr3] 100 pixels wide, left
[hr4] 150 pixels wide, left

I use this under the titles in the version history you are reading right now, amongst other things. I use these ones a fair bit.

* a [mid]middle tag[/mid] for putting things in the middle, i.e. centred. if you need any more tags, let me know!

* added DemiCode™. what this means is, you can use pretty much any html tag by simply replacing the "<" symbol with a "[", and the ">" with a "]", and you will get valid html. you can do [h3]type three heeader[/h3] tags like that now.

For instance, even though there is no [center] tag in cbparser, as such, this.. [center][b]this will be centered[b][/center] .. works just fine.

It feels like I'm opening a can of worms with this feature. we'll see. if it all works out, I can dump nice wee chunk of code from cbparser.

v2.3.9.3

* you can now edit the about page from within corzblog. multiple "entries" come up in a drop-down menu, just like the regular blog.

* fixed a few formatting foibles on some of the error pages (well, I never see 'em!)

v2.3.9.2

* improved error reporting on the edit page.

* fixed a bug where if you installed corzblog in a ~user (virtual) folder, although everything worked fine, archiving worked fine; strangely, no archives appeared in the menu. they do now.

* made some of the preferences clearer, and more flexible for folks with unusual server setups.

v2.3.9.1

* improved the css. no really, it's all fixed now.

* added an option for the length of truncation in the "blogs" menu

v2.3.9

* added a routine to determine where corzblog has been installed. you don't need to enter that manually anymore, though the option remains, just-in-case.

* removed the "real" links from the javascript buttons. since upgrading the bbcode parser to accept titles in the tag, there's really no need for this, and as much as I love raw html, it is messy looking inside your bbcode.

* some minor improvements to the bbcode parser, and it's built-in demo. I think all the tags are covered now.

* fixed a bug where if you used a different extension to .blog your archives wouldn't appear in the archive menu unless they were called "something.blog"

* fixed the slashes thing reading archives with single comments (apostrophe's) in them. works both ways now!

* finally figured out why the blue.css vriation's drop-down menu was waaay slower than the orange one; it was the float: left; that did it. we don't need this for the left-hand menu styles. incredible that a wee float could make so much difference, but there ya go. Sadly, you'll still do need the float if you use the right-hand menu schemes. If anyone knows a workaround, let me know.

v2.3.8

* cleaned up and compressed some internal code, killed a few duplications

* it looks like the javascript buttons got broken somewhere, but that could just be me. I use that less and less these days, as the bbcode parser expands. At any rate, I've added an option to disable it. javascript jobs = procrastinate now! but I fixed it anyway. You can still turn off the javascript buttons, though, see config.php

* a few more additions to the bbcode parser, of course. drop caps among them, these come in five widths, from [dc1]I[/dc] up to [dc5]W[/dc] to cater for all your letter's individual needs.

* removed a confusing "legacy" comment from the css files. less trivial than you might think.

* moved the css files to their own sub-folder, which is inc/css/

v2.3.7

* improved the documentation

* fixed a bug where if you were using a different extension for your blog files, the blog archives were still being given a .blog extension. I DO recommend you use a .blog extension, however, not least because it enables corzoogle to easily search your blogs, it's also specified in the .htaccess, I mean, WHY NOT? *ahem*

v2.3.6

* Fixed a limitation in cbparser's handling of the "pre-formatted" tags. you can now have any number of [pre] blocks and they will *all* be honoured. You can put bbcode inside [pre]tags[/pre] tags too, and it will pass unmolested. (I'm adding spaces here because pre-tags have top priority and would be interpreted before anythign else.)

v2.3.5

* made a preference for the stylesheet, you won't have to rename them any more, just enter the name in config.php

* some gui enhancements, I noticed (on yet another blog stripped of all my links (one for the planned rogue's gallery!) they're probably sending a payment right now, huh?) that giving your blog a really long name (the $mysite preference) can mess with the sidebar, at least make it appear rather incongruous; so the top menu has been renamed to simply "blog".

* made some more fixed text into configurable (config.php) text.

* improved the corzblog logo slightly, it now has a "powered by" on it, in the vain effort to get someone to LEAVE IT ALONE!

* Fixed a bug when using apostrophe's (single quotes) in archive titles (thank's joe!)

v2.3.4

* fixed an unclosed /p tag in the parser's reference tag (specifically, replaced the <br> tag with a </p> tag - editing old blogs will give you some lovely plain html to make into a reference again!), it's a minor html error that is "assumed" closed, but I'm trying to track down why google translation services messes around so much with my blog styling, and every wee thing must be eliminated!

* cleaned up a fair bit of internal code. it was my first project, after all. some real noob stuff in there, still is! but then, I do remember a TV programme years back, a housing estate, Canada I think it was, where the houses where real basic, but crucially, had these big old spaces you could do stuff with, extend as needed, and folks stamped their identity and their history on them. stuck in my head. my code's kinda like that.

* couple of under-the-hood security enhancements.

v2.3.3

* okay, error_reporting(E_ALL). I'm on it! first under the knife was the parser. as well as cleaning that, I added the capability to do square brackets that aren't bbcode commands. I suddenly had need of this! to get a "real" square bracket, just do it double, [like this]

* added the page generation timer starter (it's in inc/metadata.php) after seeing someone else's blog with a kaput timer. my own is started in my site's page header, not corzblog itself, well, now it is.

v2.3.1

* made the date in the footer dynamic it was stuck at 2003 (oops).

* added an extra linebreak ("\n") into the reference tag, right after the paragraph tag. add that into any old blogs (or other parser users, now). previously, when you clicked on a reference, it appeared at the very top of your browser pane (usual browser default), but I like a wee space up there, space is important.

v2.3

* improved the cbcode (bbcode) parser and moved it to a separate function. couple of folk asked me if I'd put out the parser on its own. while I was at it, I fixed a couple of things that were bugging me. if you find yourself editing old blogs and experiencing bbcode weirdness, try this..

replace any single-quote tag values in the news blocks with double-quotes versions. I can't handle single quotes in html anymore. specifically align='right' in the [news] tag is now, align="right" and instead of span="h6", it now uses span="news", and I removed an annoying space.

your old blogs are unaffected! but if you ever need to edit them, you will probably just want to replace old news tags with the new ones; you'll get the raw html in your edit-field.


* quashed the references bug. editing them shows the proper [ref] tag now.

v2.2.1

* corzblog is now fully corzoogle compliant! this means it can work with not only the blog archives, but the current blog too. It was annoying me. It also means the funky robot links machine can chew on them too.

* Added ability for non-javascript enabled browsers to get an "Archives" menu. It looks exactly the same as the regular one, except it's always visible, rather than dropping down on a mouseover. Also added a few other bits and bobs for non-javascript browsers, reluctantly, I might add.

v2.2

* blog archives now have a .blog extension. If you are upgrading from an earlier version, add a .blog extension to any archives you have, then they will appear in the archive menu as normal.

note: you DO NOT need to add this extension when archiving; corzblog will add this for you. it's effectively invisible, doesn't even show up in the menu's or URL's. The renaming is only if you are upgrading.

Primarily, this was so that blog archives are searchable with my corzoogle search engine, which requires specific file extensions as a security measure.

* other stuff; the sub-header archive pages now displays the name of the current archive, or whatever you are looking at, few other wee user interface things like that.

* Altered the edit.php file so that if you access it directly, it will redirect you to the choose page.

* Added another couple of variations of the css files, so now we have standard orange, left or right-hand sided, and the same for blue. I'll do more of these as time goes on.

* Fixed a bug with back-slashes entering the title area, oops.

* Updated the javascript functions to match my domain (at last!).

v2.1.3

* cleaned up some of the internal code, stuff that had started out as illustration, but was getting kinda messy *cough*

* tweaked the css for the blue theme, now the sidebar is on the right. total time, 3 seconds editing the CSS file. I suspect I'm not finished with the CSS.

v2.1.2

* fixed a small bug where if you hovered over the archives menu and there were no archives in the /arc folder, it produced a php error (which vanished again on mouseout, pretty cool) now it echoes "no archives yet"

* updated and renamed the metadata file in the distribution

* simplified the .htaccess files

v2.1.1

* slight alterations to the two css files, now we use px values for all margins and padding. Apparently some non-standard browsers get upset when you mix the values.

* Updated and improved the about file which you are reading

v2.1

* made the archiving automatic. there's a form in the "edit blogs" page; you name it, it get's archived, your current blog gets wiped. TADA! total no-brainer.

* blogs are now backed-up to the /arc/ folder at every add/edit operation. In the event of any human mistakes, your last blogs file is in /arc/blogz.bak

note: any file you put in the arc folder with a .bak extension will *not* show up in the archive menu. same goes for "index.php" files, though the hidden .htaccess file would prevent surfers from loading any index.php file, anyhow.


* knocked together an alternative CSS file (blue) you're looking at it.

2.0

corzblog II .. "now it's personal"


* This has got to be the best blogging system I've ever written!

* Spurned on by the success of the new RDF feed, and its greed for user custom user variables, I set about restructuring the internals of corzblog. I think you'll like it.

* "User" variables are now all in one central place. Like lots of other php packages, what you need is in "config.php". I might even get around to doing a form for this.

* archiving your blogs is now a trivial matter. Call the old blog what you like, drop it into the "arc" folder and bingo! It's in the archive menu. When you select an archive, its blogs are listed in the blog menu too, for easy navigation.

* there's loads more, I'll probably write up the changes after I've had a sleep

v1.6.2

* Added rss 1.0 rdf feed to the blog. I realise now that there are so many variables that a user might want to edit, I'm gonna have to move these over to a single file, one of those "config.php" things.

v1.6.1

* I switched all the linebreaks to unix linefeeds. Previously we were using a combination of both unix and mac linebreaks, unix for dynamic pages; javascript, html, etc; unix for the source files, and mac for the blogz themselves. Hopefully this should make everything clearer. It doesn't matter if you can see them or not, it's all handled internally, so long as your text editor can translate and save them - and all decent text editors can - you'll have no troubles.

After setting their password, most folk will never need to look at the sourcecode anyhow, certainly not the raw blogs, but if they did, they would find them now quite readable, similar to the style of html I produce by hand. The blogz file being jumbly gave me sleep problems.

I use unix linebreaks for all my text these days (specifically, UTF-8 (no BOM) - unix linefeeds), mainly because OS X is "unix-based", but linux servers prefer this too. Really it doesn't matter too much, so long as your browser produces both (i.e. DOS linebreaks) inside forms, and they all do, as far as I know.

v1.6

* importantly, I changed the "end of blog" marker from a unix linebreak "n" to an <end> tag. This is to prevent problems with unicode linefeeds, not that anyone uses them yet. You'll need to do a quick search/replace for all "n" characters (unix linefeeds), and replace with "<end>". took about 1.2 seconds or something like that, for five months of my blogs. This will also help those who had trouble seeing unix linefeeds in their text editor. *sigh*

* improved all-over linefeed handling. Now I can make the raw blogs much easier to read and editing manually. plain carriage returns are used throughout (default on mac, but every decent text editor on every platform can handle them).

* added a few common transformations, allowing you to use bullets, degrees, plusminus and trademark symbols in the blog, they get encoded properly now.

* added a pop-up of special symbols, this is growing all the time.

* because we're all unicode now, you can theoretically input any symbol you like and it "should" be saved just fine (most browsers have been UTF-8 compliant for years), the pop-up just makes it easier to find those symbols, and also encodes them as 'proper' &html-entities;

* widened the text edit area to 66 columns, should still be good for an 800x600 screen.

* improved the auto-scroll when you add special stuff to the blog.

* altered sidebar so that list of blogs is accessible wherever you are in the blog site.

* improved the references function. Now you can create easy-refs! Each reference section being unique to the blog (previously you could only have only one per page), and you can have up to three neat, numbered references per blog. This number could easily be increased if needed, I'm just getting itchy about the number of string transformations being performed on the blog text. och well.

v1.5

* added rss feed capabilities. very nice!

* some internal changes, wee code clean up

* added cute pop-up descriptive labels for buttons (some browsers -safari- won't show them)

* added a "quicklinks" section to the sidebar, for individual blog entries

* spruced up the quicklinks with cuteness

* fixed a few wee bugs that had cropped up

v1.4b

* added a couple of new bbtags

[block]a blockquote[/block]


* at last the < > button has a function. "[ ]" blockquote!

* also the [hr] tag, which will draw a nice thin horizontal rule.

v1.4

* got rid of add2.php moved it all to one file.

* moved all editing functions to a single file too

* rearranged the editing window a bit < > still does nothing! hah!

* previewing and editing now in one page. much better!
(I knew something was bugging me)

* previewing of edits is now possible (previously only new posts)

* minor stylistic changes

* code is pretty messy, but 100% functional! I'm happy!

v1.3

* Made the edit menu meaningful. (name of blog)

* minor stylistic changes to code box

v1.2

* couple of minor bugs in the preview worked out

* will now take you directly to the blog is add/edit was successful

* if not, you have the option to go back and fix it!

* added a few more quick-code function buttons, big, bold, italic

* made the whole thing self-contained and removed my header, for distribution.

v1.1

* Added preview function for new entries. nice.

* Added new functions, code, url, image, etc

* blog content will now appear *inside* the edit window automatically

* I'm happy now!

v1.0

* working swell! (well, so so!)

* editing possible now-ish (adds extra bits)

* added javascript functions and css in /inc folder (extensible)

* the script will now grab your "posted by" footer.php and insert it back

v0.5

* basic blogging possible

* worked into my nice pages and css

* worked out the break bugs, and a few other bugs

v0.1

My first "real" php project!
got basic entry code running.
borrowed some ideas and a couple of snippets from my unwitting guiding hand in this self-help tutorial.. Jaryd Whitem AKA: JRiderofShade, ta m8!

That online php manual is excellent too!