“Writing a proposal. Oh boy do I hate word processors. There must be a better way.”

It turns out there is, though I ended up forging my own path to suit my skills and working methods. A little background…

I need to produce decent looking proposals for web development projects. Normally I bite the bullet and suffer the awkwardness of Word or OpenOffice or LibreOffice or something, and then export to PDF. It’s all very clever: it took some great minds to produce this software. But it really goes against the grain. It feels so wrong.

I like plain old text, and as a web developer I’m used to defining the style of documents by hand, in CSS, rather than using another program to do it for me, as I write. I would go further and claim that this is not just a matter of personal taste: word processors are bad for the world. Sure, people are used to them, and they cannot imagine a better way, and – most importantly – there is probably no equally mature, friendly, well-supported and funded software in place to allow for a move away from them as things stand. But it does not follow from this that they are good.

What’s Wrong With Word Processing?

The name, to start with. But most of all WYSIWYG. One thing I’ve learned from web development is the importance of respecting the logical separation of style and content. WYSIWYG is not so respectful. Everything happens in the same place and at the same time. Effectively, documents are typeset as you go, character by character. This is silly.

Formatting your document’s style has nothing to do with its content. What you are trying to say is a different concern from how it should look. And I do not mean that the two human operations are more conveniently handled by separate software operations. I mean that they are different human, conceptual, natural concerns. Of course it has to look good (although a. it doesn’t always have to, and b. even plain text looks way better than a clipartified Word document). Yes, of course your document has to conform to a company standard, or your own standard, and how it looks might be partly what you intend to convey. But all this precisely means that these standards and styles ought to be defined separately, beforehand, leaving you to get on with the writing: to concentrate on what it is you have to say. It is the difference between talking to somebody at a party and deciding what you are going to wear to that party.

Using WYSIWYG software such as the horribly feature-rich Word is like going to a party with several changes of clothes and proceeding to change them every time you think that what you’re saying doesn’t go with stripes. Sure, do the best you can to look good, but prepare for that, by going shopping, trimming your beard, and putting on your best Y-fronts. After all that’s done you can get on with talking to people and getting drunk, safe in the knowledge that you’re looking great. Underdressed? Well, if you didn’t care enough to prepare, to research, and to tune your attire accordingly, then you shouldn’t care about being underdressed.

Now, moving on from that straining analogy, the biggest benefit of separating style and content is that content becomes independent of how it is presented. If standards of presentation change, or a piece of writing needs to be reproduced in different formats, or you’ve finally got tired of Comic Sans, then you shouldn’t be going anywhere near your content to achieve the desired formatting changes. But word processors force you to do this. You actually have to open and edit your document, just to re-style it. This wrongheadedness has been spectacular in its worldwide detrimental impact.

(Note that I’m quite ignorant of Word and the no-doubt very sophisticated setups that can be achieved in organizations where stanadardized presentation is important. For all I know maybe you don’t always have to go back and edit your document or re-assign a template of whatever. However, achieving this is just a workaround, and likely would not have a perfect success rate; it seems clear that the default expectation of the software is that you do mix up content and presentation.)

And faced with the option, the expectation, to fiddle about with fonts and bullets, it takes discipline, imposed from above or by yourself, to beat down that natural inclination. This is not a matter of freedom. In my case, I have to struggle with formatting issues almost every time I write – or rather, process – one of these documents, because I might be using different word processors on different platforms with different fonts or whatever. This should not even be an issue, because we already know, deep down, that style and content are logically separate categories (note that this does not mean that they do not sometimes overlap). And in a company environment, standard templates for Word and detailed strictures and guidelines from management on formatting, fonts and colours, are awkward and only partly successful workarounds for a problem that would not exist without WYSIWYG.

The writer of a document has expertise in the subject addressed by that document. They may not have expertise in typography and layout, and usually they do not. The latter, then, becomes nothing but a distraction and a huge waste of time. And … I didn’t ask you to send me a bloody Word attachment in the first place!

The natural paradigm for me, which I get from web development, is to write stuff in a text file, and to define how it looks in another text file, and only then to view how it will look to the document’s recipient. I believe this should go for print documents as well as HTML web pages.

It is already the way of things in printing, publishing and professional writing. I don’t believe Proust was worrying about typefaces when he painstakingly described the memory of a hawthorn bloom, and the prevalence of Word has not made this any less true of professional writers today. Why should any writer, or anyone who becomes a writer for brief periods – whether of poems or proposal documents or annual reports – have to worry about such things? Why has the division of labour, both human and machine, which is so thoroughly advanced in the modern world, been bypassed in this case?

Lightweight Markup

A few years ago I discovered Textile, which is a lightweight markup language. What a Godsend. I can get on with writing:

All in a text editor. You know, like Notepad only with nice colours and productivity tools. There’s nothing and nobody messing around processing what I write. Processing comes later, based on separate settings that I have set up for the scenario.

My Great Solution Which, Though Great, Could Most Probably Be Vastly Improved Upon

Up till now I’ve only really used Textile to generate HTML for display on web sites, usually blog posts, but now that I’ve (mostly) moved away from Windows and on to Linux, manipulating text becomes all the more easy. I’ve created a nice wee setup to generate PDF documents styled with CSS straight from a Textile file. I should stress that this involves the terminal and bash scripts, so it’s probably for geeks only.

The upshot is that when I want to write a proposal, I just run a couple of commands to set up a proposal project based on a template, and then get down to writing my document in Textile, and when I want to see what it’ll look like I just run ~/gopdf.sh, which generates a PDF.

The gopdf.sh bash script does three things in order:

A. Generates an HTML file from the textile file using pandoc
B. Generates a PDF from the HTML file using xhtml2pdf
C. Opens the PDF

(If I had actually got to the stage where I’ve built up a nice PDF stylesheet I would have shown you something more fancy, but there you go. And the sharp-eyed among you will notice that the line of text immediately following the list is squashed up to it. This might be a problem with pandoc’s understanding of textile, which is not perfect, favouring the alternative Markdown as it does. You can include HTML in among the Textile markup, so a line break here is easy to achieve, or else a CSS bottom margin would probably do it, and would probably be the better choice.)

What it Allows Me to Do

Before I describe how I make all this possible, here in more detail is what I now do every time I get a new client who wants a proposal.

One

So I meet with Bob of Bob’s Cake Company fame, and he tells me he wants a cake web app. I say sure, no problem, then I go home, start up Linux and create a folder called bobs_cake_company, and cd into it. Then…

The first command copies over my standard proposal template folder to bobs_cake_company as a sub-folder called “proposal”. The second one just opens the current folder, bobs_cake_company, in Sublime Text 2 (I seem to remember doing some things to get that “subl” command working, but I’m not sure what. Probably just a symlink.)

Two

I write the document in the file that is there waiting for me, proposal.textile. Remember, by writing I just mean writing. Not fiddling with margins or choosing bullets or struggling with alignment issues or fixing pasted text or making sure that the screenshot isn’t blurry or anything else like that.

Three

In the terminal…

This generates a stylesheet from the SASS files in which I define the CSS stylings. Full disclosure: currently my method is in its early stages so I don’t yet have a good standard CSS stylesheet for PDFs. I’ll be building this as I go along for a project or two before I can just leave it alone. So right now I’m actually running this Compass watcher when I begin writing, because I’m styling as I go, like a human word processor. Not for long.

Four

Then in the terminal (in a new tab):

This creates a PDF (or overwrites the one that already exists), and then opens it in the default PDF viewer. Thereafter I just run “~/gopdf.sh proposal” whenever I want to see my changes in the PDF.

Five

Send proposal to client and have a cigarette.

Making it All Possible

The process I’ve just described depends on a few pre-existing elements:

• pandoc
• xhtmlpdf
• startdoc.sh bash script
• gopdf.sh bash script
• a proposal_template folder with goodies in it
• Compass (optional)
• Sublime Text 2 (optional)
• A dangerous, expensive and anti-social nicotine addiction (optional)

You do the following stuff once only.

Get pandoc: Pandoc is a Haskell library that converts between lots of different kinds of documents. I would have used it alone had it been able to convert Textile and CSS to PDF directly. (I couldn’t make it work and concluded that pandoc couldn’t do it, but I could be wrong.)

Installation instructions are here

Get xhtml2pdf: xhtml2pdf is a python package that generates PDF files from HTML and CSS. It can be installed with easy_install or pip and also available to download here

If you are so inclined, get Compass: Compass is a CSS authoring framework built on Ruby and SASS. You write in SASS and Compass generates CSS files for you. The latter are what you actually run on the server. I’ve been using it for a year or so and I love it. One of the reasons I like it is just because I can avoid the curly braces and semi-colons of CSS itself. I’m addicted to significant whitespace. (Though it’s worth noting that they’ve been going after designers and have opted to make their SCSS syntax the default because SASS looks too much like programming).

More details on installing Compass here

If you need a great text editor, get Sublime Text 2:It’s all the rage, and for good reason. Get it here

Create startdoc.sh:

This copies the proposal template folder, renames it depending on your argument, and also renames the .textile file.

Create gopdf.sh:

This is where the action happens. It runs pandoc to convert from Textile to HTML – along with print.css – and then runs makepdf.py (which in turn runs xhtml2pdf, as we shall see) to take proposal.html and generate proposal.pdf.

Create the proposal_template folder

We need to create a standard proposal template that will thereafter be copied over to a new project any time you run ~/startdoc.sh. It consists of a folder structure which looks like this:

The folder sass contains the Compass SASS file; stylesheets contains the CSS that is produces from the SASS, namely print.css; config.rb is the Compass config file; and makepdf.py runs xhtml2pdf, but is itself executed by the gopdf.sh bash script. The folder fonts contains font-files that can be included in the PDF by using @font-face in the stylesheet.

Once all this is copied over by startdoc.sh, proposal.textile is where all the writing happens.

The Python script, makepdf.py, looks like this:

This is called in gopdf.sh, specifically this line:

So running ~/gopdf.sh proposal will get pisa to take proposal.html and generate proposal.pdf. Pisa, by the way, is the original name – or central core – of xhtml2pdf.

In the near future I hope to fill the standard print.css with lots of proposal-specific stylings, and proposal.textile will probably contain my standard section headings and table of contents.

By the way, when creating the standard template, the Compass stuff can be set up automatically by running the following command.

(If you like the SASS syntax, that is)

WordPress

I’m writing this in Textile right now, but it struck me that I only had a WordPress blog to post it to. I can use Textile for my philosophy blog, because I built the engine myself in Django, but I hadn’t got far in the past trying to get Textile working in WordPress. Thankfully, Veeti Paananen has provided a plugin, Simple-Textile which seems to work nicely.

It’s really time to move this blog, and a redesign is probably overdue.

Afterthoughts

If you’re not a coder, but you’re an author or just do a lot of writing, and you don’t have to worry too much about making your words look good enough for Bob of Bob’s Cake Company to print out — but you do want a nice, pleasing, peaceful, distraction-free writing environment, then there are some nice minimalist editors out there at the moment, such as OmmWriter and WriteRoom.

I get basically the same thing in Sublime Text when I put it in “distraction-free mode”, so my programming and web design editor also functions as a nice place to write about Wittgenstein, Heidegger, Karl Marx and the evils of traffic control.

But when it comes to writing something big or complex like a book or a thesis, folks sometimes opt for specialist software, such as editors that revolve around the LaTex typsetting markup system. These are usually built on the same paradigm that I’ve been describing, namely the separation of style and content, which is especially important with documents primarily intended for professional print publishing. Word processors are strictly for home and office use, and I imagine those in the world of printing never touch them with a bargepole. It must be galling that word processors are these days thought to be the last word in setting and styling type, because while they have cast that noble profession into obscurity – though certainly not into obsolescence – their own ability to do it well is tragically lacking. Next time you’re in a print shop ask them what they think of Microsoft Word, so long as you don’t find anti-Microsoft rants boring.

Thanks to all of the wonderful and generous programmers out there without whom I would likely still be shouting at Word like a madman.

Further Reading

I’m not the only one, you know.

Why Do I Hate Word Processors?
Word Processors: Stupid and Inefficient
What has WYSIWYG done to us?

After working primarily in Django for the last while I had to do some WordPress work yesterday, implementing SEO improvements to one of our e-commerce client’s web site. I added a function to functions.php and got everything working nicely, but then I went to /wp-admin only to find a blank screen, with no error messages. Neither could I find anything in the server error logs. I could get to /wp-login.php and seemingly log in succesfilly, but then the same thing would happen – I couldn’t get in to the back end, even though the public site was working just fine.

Most of the proposed and unsurprisingly successful fixes I found in blogs and on the WordPress support forums involved re-installing WordPress, but one suggestion stood out: delete any blank lines at the end of your functions.php file. I’m in the habit of adding extra lines at the bottom of a file to give me more space to work in my text editor, so this looked promising. And it worked.

I don’t know why.

Pony-Powered Enlightenment Bullshit

This sounds like bullshit, of course, and I confess I’m spinning this out more than is warranted, but there is an immense calm, neatness and harmony about developing with Django. Everything’s at just the right level; everything fits together in just the right way. Everything’s in the right place, everything’s in nice little pieces that fit together like a jigsaw.

You know when you read a textbook and you get the feeling that the author knows exactly what you’ll have trouble with? Or a teacher who always seems to be able to anticipate your difficulties. Well that’s what it’s like to work in Django. There have been countless occasions where I have exclaimed, after a bit of struggling, “oh, you mean I can just do this!” Just where you need it to be, it’s all done for you. You know the bits I mean: the tedious shit. The painful repeated Ctrl-C Ctrl-V crap that you go through every time you do a form.

Django is high-level, but in a low-level way. There’s no fucking about with shitty interfaces, arcane meta-languages and strange customs, just to put a website up that has editable content; there’s none of the horrible mess of PHP; there’s no need to download three thousand PHP files and work with a horribly complex interface just to set up a wee blog for God’s sake. With Django, you build things up yourself, in just the way you want. If you think this sounds like a lot of work, it’s not – it’s way less work, because Django knows roughly the kind of things you’ll be doing.

I confess that I never got around to trying a PHP MVC framework. No doubt all this great stuff I’m talking about is largely owing to the general MVC pattern, rather than to Django itself – but I’m not so sure. Django’s helper classes, such as forms, make the whole web development experience fun. Anyway, it’s so much nicer to write in Python.

Demon-Driven Enlightenment Bullshit

(This section doesn’t have much bullshit in it actually, but I couldn’t stand to leave the first two titles unbalanced.)

I’ve been blogging over at my philosophy blog, critique-of-pure-reason.com, which is why this is the first post here for a long – shit, it’s October already! That blog and the studies from whence its content sprouts have been taking up a lot of my time. Right now I’m studying scepticism, in particular Descartes, who suggested that for all I know I might be dreaming at this moment, or I might be the victim of a malicious deceiver demon who is creating all of my perceptions for me; so I cannot take my perceptions for what they seem to be, and so I have no ground for the belief that I am sitting at my computer writing; even though I bloody well know I’m not dreaming.

Now, you would think that “I bloody well know I’m not dreaming” would be absolutely inadmissable in philosophy, but most answers to Descartes seem to be saying something similar, especially those from Moore and Wittgenstein. Anyway, that’s enough of that. This is neither the time nor the place. This is the place if you’re interested. I did the blog engine from scratch in Django, by the way. Have I mentioned how much I like Django? Come to think of it though, the site’s sadly lacking in navigation, categories, tags and all that. Well, I did it over a single weekend so what do you expect?

So I’ve been staying up till all hours poring over philosophical papers from the journal Mind, just trying to prove that I’m not dreaming. It’s not as fruitless as it sounds though: mountains and valleys of thought are appearing from over the horizon. I’m moving ever nearer, exploring the foothills on my way to the dizzy precipices of [insert more bullshit here].

Not Enough Hours

And that’s not to mention all the music: saxophone, piano, theory and composition. And the maths. I’m working through a book of undergraduate mathematics, and Euclid’s Elements – oh and I’m half-way through a textbook on logic. Am I insane? Is this whole paragraph a cliché? I think it is you know. Fuck.

But wait. There are CSS compilers, and then there are the libraries and frameworks and plugins that are built around them. Well, I guess that’s where the term “meta-framework” comes in.

One such meta-framework is Compass, which is built around the core language and compiler Sass. I mentioned Compass briefly in my other post. At the time, I had dismissed it as being more than I required, or more than I wanted to get into, but in the end I realized if I was going down this route at all I might as well do it right – and Compass does it right. It seems by far the most thorough, mature solution I’ve found, with a good heritage and a lot of success.

So that’s what I’ve settled on using now. There might be some kind of tighter integration achievable if you’re using Rails, but what I’m doing is using it to generate CSS as I locally develop a site in WordPress, and the same for a site built on the GetSimple CMS, and a Django project as well. You can use it with anything, and when you come to deploy it you can exclude all the Compass stuff, leaving no trace of it on the live site, except perhaps in the tell-tale auto-generated layout of the CSS code.

Your best bet is probably to go read the excellent documentation, but here’s some basic stuff from my own experiences…

Initial steps:

1. Install Ruby
2. Install Ruby Gems
(if you’re on a Mac you may have these already. I guess you could find out by carrying out the next step)

3. Install Compass from the command line:

With these installed, whenever I begin a project I set up Compass in the theme or template directory by running the following command inside that directory:

There are loads more options for the create command (See the documentation). Note also I’m using the SASS syntax, because I prefer it. There are two choices, and projects default to SCSS. See here for more information on the differences.

Incidentally, it’s interesting that SCSS is now the default syntax for Sass (confusingly, the name of the language/compiler is also the name of one of its two syntaxes). The SCSS syntax looks just like CSS itself, and the idea is to lessen the unfamiliarity for designers who are already very skilled in CSS. After all, there’s no reason in principle why they should have to learn a new syntax in order to take advantage of the power of Sass and Compass, which is independent of the syntax, and independently valuable.

However, I’m sticking with the SASS syntax, because I find it neater and easier to write, and I don’t mind admitting that it’s simply a welcome novelty.

That create command creates a configuration file, config.rb, and three directories, most important of which are src and stylesheets. src is the where you write the code, and stylesheets contains the generated CSS.

The last essential piece of the puzzle is how the CSS is generated when you’re developing. All you need to do is run the following command in the directory in which you set up Compass:

This runs in the background and watches for changes, then re-generates the CSS when it finds them.

Getting ready to code

I’m currently working with a config.rb that looks like this:

It’s good when starting out to use a _base.sass “partial” to set up your variables and imports. Mine looks like this:

See here for more on Compass best practices.

Mixins

Notice at the top of the base partial I’m importing another partial file, _my_mixins.sass. Mixins are wonderful: they let you collect together styles and mix them into your stylesheet wherever you like. Compass comes with many of them, but you can also define your own, which is what _my_mixins.sass is for:

These are used in the actual stylesheet source code (eg. in screen.sass) like this:

Grids

I’m also using the 960 grid system (Compass also comes with Blueprint). With Compass, using a grid system is very nice indeed.

One thing that’s good about this set-up is that you can code using a grid system without using any unsemantic class names like “prefix_2 grid_8.” Compass takes care of that when it generates the CSS. Effectively you’re using the grid as it really should be used, only in design and development. Compass calculates the relevant widths for your semantically-named elements, based on the 960 mixins, and there’s no underlying skeleton of unsemantic classes left behind in your HTML and CSS.

NOTE: Using +grid-container instead of +grid-system(12) means you don’t end up with all the 960 grid classes in your style sheet, which won’t be required because of your use of the mixins.

This is just the basics. There’s lots of stuff online, but you can’t do better than the Compass documentation, and it’s worth taking a look at the site of Chris Eppstein, the man we have to thank for it all.

I think I’ve unearthed a conspiracy. In the wonderful world of the world-wide web (that’s WWWWW for short), with so much information available, and so many companies selling online, surely there must be a collection of standard procedures for implementing an online shop, and reliable sources of information covering them? Apparently not. How else to explain this except an evil conspiracy? In particular, an evil conspiracy against web designers and developers.

This post is drawn from an e-mail that I sent to a tech savvy client, a small business owner. The email summarized their options for e-commerce, in the specific context of the UK, and it was the result of some hours of research. Reading it over later I realized it could be useful to web developers, given the aforementioned global conspiracy. It is therefore my duty as a good web citizen to reveal this sacred, jealously guarded information – despite the dangers.

NOTE: I’ve called it a starting point, but really this post is just a record of my own starting point, and there’s a bias here towards WordPress.

Introduction

There is one way of selling online that I won’t really go into here, which is selling through your regular PayPal account or with Google Checkout. These are pretty good options, because they’re so easy, but most businesses don’t want customers being directed away to PayPal or Google when they check out. A more integrated solution is preferable because it gives customers confidence in the professionalism of the business; the business can have direct access to its product, order and customer data within a single system; and you – the developer – get more control all round. That’s what this post is really about, but the shopping cart software mentioned here can work nicely with the simpler PayPal set-up as well.

An online shop that accepts credit cards usually needs these four things:

• An Internet Merchant Account (IMA)
• A Payment Gateway
• Some shopping cart software (including product listings, product pages, a cart and a checkout page)
• (in some cases optional) Shop CMS (admin for shipping rates, product management, inventory, order management, etc.)

The shopping cart and CMS can normally be treated as separate and independent. For the payment gateway and IMA, I would normally recommend PayPal’s Website Payments Pro, which bundles these together. But if a substantial portion of your market is in the UK, there’s a problem:

Maestro and 3D Secure

This is where it gets complicated. In fact, it looks to me like the whole thing’s a bit of a mess.

Mastercard enforces the use of 3D secure to process Maestro payments (and this is becoming very common for payments with the other cards too). All Maestro transactions will be declined if this isn’t implemented. 3D Secure is an extra step in the checkout process, which allows real-time authentication with the customer’s bank. It commonly comes in the guise of “Verified by Visa” and “Mastercard SecureCode”. In some implementations it’s optional – the customer can skip it – because not all cards are required to be authenticated like this, but a Maestro payment just won’t complete successfully without a 3D secure authentication.

Before you go down this route it might be worth weighing up the pros and cons of 3D secure:

Pros

• Lets you take Maestro payments
• Can give customers more confidence in buying stuff online (in theory)
• Reduces chargebacks
• It could be that, as people in the UK have become more used to it, they have come to expect it

Cons

• Yet another step in the process of checking out – this is known to lead to a reduction of sales
• Restricts your options for e-commerce software and payment gateways
• From a development point of view, implementing 3D secure can be tricky, depending on the kind of solution you choose

With Website Payments Pro, it’s up to you to set up 3D Secure. Seemingly as an afterthought they recommend using some kind of product from a company called Cardinal, but I’ve no idea what Cardinal actually provide, and their web site is no help. I sent them an enquiry but received nothing in response. This didn’t give me much confidence, so I looked for some other solution, i.e., a payment gateway that had embraced 3D Secure and knew how to implement it.

Turns out there is one that’s popular in the UK: RBS Worldpay. They offer three account options, including one that – like Payments Pro – bundles together the IMA and the gateway. The crucial thing is that WorldPay implements 3D Secure.

RBS WorldPay

At the time of writing I haven’t implemented the gateway, so I can’t say too much about it now. I also won’t say anything about WorldPay’s interesting (in the loosest sense) recent history, but you should check it out because it puts things in perspective.

What I’ve discovered so far is that there are essentially two ways of implementing WorldPay: HTML redirect (or Hosted Payment Pages, which appears to be the newer name) and XML Direct.

HTML Redirect is the easier option. When the user checks out they’re redirected away to the WorldPay site, where all the hard stuff is taken care of. You may be familiar with HTML Redirect from seeing this beautiful interface:

Yes, I know: there’s no way you’re having this ugliness anywhere near your lovely design. But according to the WorldPay site, you can customize this page, in line with your own design. I don’t yet know just how customizable it is: looking at what documentation there is (not an easy task in itself), I’m sceptical how far you can go with it.

I must warn you that browsing the WorldPay site for good information is a painful experience. It has the feel of a collection of documents assembled from disparate sources by a robot with little sympathy for, or understanding of, the requirements of human beings. I suppose this is fairly common with such massive corporate organizations, but it’s a real shock when you’ve been used to dealing with small, focused companies with a dedication to openness on the web.

It took a couple of messages to WorldPay technical support to find out that there was another way: XML Direct. This allows a more complete integration with your site, because all the processing is done in the background, rather than with a redirection. The implications are that you’ll need to make damn sure you’ve got a secure system. RBS have a process for assessing your set-up, and further procedures for testing and activation.

For an alternative to RBS WorldPay that also supports 3D secure, check out SagePay

PCI Compliance

Aside from any particular requirements of your gateway, generally a secure setup is one that is PCI compliant.

With HTML Redirect and the hosted solutions (option 1 below), you don’t need to be PCI Compliant at all, because you’re not actually storing credit card numbers on file or in a database. It’s your payment gateway (eg. WorldPay or Website Payments Pro) or shopping cart service that has to be PCI compliant. However, your gateway may still require you to pass some level of security-checking.

With XML Direct, you do need to pass some PCI Compliance tests, and that’s a whole other can of worms I’m not going to open right now, because I’m still not sure exactly what’s inside. Worms, yes, but what kind? And do they bite?

SSL/HTTPS/Encryption

You might not be storing credit card numbers, but you may need to transmit them securely, in which case you will need to buy an SSL certificate and have it installed on your web server. Basically, if your checkout page resides on your web server, as part of the site, you will need SSL. But if it’s hosted, as it is with WorldPay HTML Redirect or one of the complete hosted shopping cart solutions (option 1 below), you’re not transmitting anything sensitive so SSL is not required.

Software Option 1: Hosted

Examples: Ecwid, Foxycart, Shopify

With hosted e-commerce, you sign up to a service that provides a cart and checkout process, all hosted on their servers. General shop settings – shipping, taxes, coupons and product types – are all administered on their site.

The big advantage is that they they’re the ones who need to have the SSL encryption and security, and they wrap up the whole checkout process very nicely, so there’s not much in that area you have to worry about.

I’ve set up a shop with FoxyCart and MODx, and while there’s a lot of work to be done if you need product management built into your CMS, setting up the customized cart and checkout pages is a breeze.

• They handle SSL and PCI compliance
• No 3D secure/Maestro (because they’re responsible for implementing it and Ecwid, Foxycart and Shopify haven’t done so yet, although they’re working on it)
• Your data is on their servers
• Separate place to manage shop (ie. separate from the rest of the website)

Ecwid (Free)

• Very fast, very easy, and very tempting
• But no API and not very configurable
• Depends on JavaScript

Foxycart ($19/month)

• Very configurable
• Total control over the design of the hosted pages
• API and XML feed to get data from their servers to yours (allowing you to integrate this data with your database and CMS)
• Cart depends on JavaScript

Shopify (From $29 to $699/month)
Look at that price-range. That indicates a pretty mature kind of product, and I get the feeling this might be one of the best hosted solutions out there, but I don’t know much about it. But it’s built with Ruby on Rails so it must be super cool, right?

Software Option 2. Self-hosted / Integrated

Examples: WordPress plugins WP e-commerce and Shopp

I recently split off a WordPress site into two development branches, one with Wp e-commerce and the other with Shopp. I’m very impressed with this type of software solution. I don’t see any reason why you couldn’t implement any size of shop, and there’s loads of CMS features covering just about everything. I went with Shopp in the end, but they’re pretty similar in functionality.

• You have their software installed on your server (ie. the server I’m hosting the site on)
• You keep all the data on your server
• You don’t have to log in to another site to manage your shop
• Shop CMS for product, order and customer management etc., integrated into your site CMS
• Configurable
• Often requires an SSL certificate
• Could require PCI Compliance, depending on how you implement it
• Maestro support is possible (if using RBS WorldPay or something similar like SagePay)
• But no WorldPay gateway option out-of-the-box

WP e-commerce (free, or $195 for the business gold cart)

• Open source
• Configurable, customizable
• Ability to create a custom gateway integration
• The free version withholds some functionality that in most cases is a necessity, such as multiple images per product. You could probably code this in yourself if you wanted to avoid the cost.

Shopp (One-off $55)

• Open source
• Configurable, customizable
• Ability to create a custom gateway integration

Software Option 3: Self-hosted Standalone CMS

Example: Magento

• You have their software installed on your server, alongside your web site CMS
• All-in-one shopping cart, product and order management package
• You keep the data on your server
• Open source
• Separate dedicated CMS for your shop (not integrated into your site CMS)
• Tonnes of features
• Potentially difficult to configure and integrate
• Requires an SSL certificate
• Could require PCI Compliance, depending on how you implement it
• Maestro support possible (if using RBS WorldPay or SagePay)
• But no WorldPay gateway option out-of-the-box

Something like Magento should be seriously considered. It’s very featureful, and I hear they recently implemented 3D secure. However, setting up and configuration could be time-consuming, and systems like these can be pretty bloated, slow and clunky.

Conclusion

If you need to take Maestro payments – and there are still a lot of those cards around – you can’t really go with option 1. The other options all have built-in support for several gateways, but unfortunately not WorldPay. This means some unavoidable work on your part to hook things up. Whether you go with option 2 or 3 depends solely on the needs of the client and your own development decisions.

In the forthcoming weeks I’ll be implementing the gateway – perhaps developing a WorldPay module for Shopp in the process – so I’ll be posting about that. If the Guardians of the Sacred Secrets of E-commerce haven’t tracked me down, that is.

The answer to this, of course, is variables (or constants), so that you can define your colours in one place. Trouble is, CSS don’t got none. In fact, CSS is lacking in several important ways. What it boils down to is that we struggle to get around the fact that CSS doesn’t work like a programming language. In other words, it’s not logical, intuitive or consistent.

Cognitive Dissonance

I’ve been saying for a while that the affection many people say they have for CSS must be born of their triumph in finally getting the bloody thing to work. I know this feeling. There’s power in there to do what you need, and it can be fun. We must get some kind of neuro-chemical reward when we creatively delve into the details of CSS and finally emerge with something approaching what we were going for.

In fact, this is a classic example of the psychology of rationalization, prompted by cognitive dissonance. The time and energy we spend on CSS compels us to believe that it is good, because if we doubted that, there would be an unacceptable inconsistency in our lives.

It’s how web developers remain sane: by lying to themselves.

There is a joy in arranging your stylesheets logically, breaking them down into sections, successfully and efficiently tackling the issues of specificity and inheritance. But this is only because there’s so much room for improvement in CSS. It’s so easy to write it badly, with repetition and redundancy everywhere. And even if you write it well, maintenance is still a hassle. Why should we have to deal with these difficulties when there already exist models and paradigms, in the world of programming, that could make things much simpler if applied to CSS?

Often you hear the objection that the abstraction of CSS is only for those who haven’t done the hard work in learning it properly. That kind of attitude stinks, in my opinion. Specifically, it stinks of self-justification, conservatism and protectionism. It is the bitter form of the rationalization that aims at avoiding conginitive dissonance.

CSS won’t be around for ever. It was expedient, and learning it has been a necessary evil. A heroic endeavour, it’s true: the prominent designers, developers and standards advocates who have cracked it and shared their knowledge with the rest of us are web heroes, no doubt about it. But that doesn’t mean we should continue to celebrate the endeavour if it’s no longer necessary.

First Steps

So in my last site I put things into practice in a very basic way. Here’s config.css.php:

And here’s the fake stylesheet main.css.php:

In the HTML you link to the stylesheet in the normal way, but specifying the PHP file instead of a CSS file.

True, you could use regular CSS classes for this, but do you really want to pollute your HTML with classes with names like “dark” and “box-shadow-colour” ? Just think how horrible that could get.

That’s all very well, but it’s still really just CSS. It’s also going to be slightly slower (not that I’ve noticed), and it’s a bit of a hack anyway. It’s akin to the way that PHP is peppered through HTML, and that’s not a great model.

That’s where CSS compilers or frameworks come in. One example is CSScaffold. With Scaffold you can use mixins to group together properties into reusable chunks. They work a bit like functions or classes in programming, and Scaffold comes with lots of them ready to use. Also, the big advantage of Scaffold over the way I described above is that it will serve the generated CSS files directly if they’ve already been cached.

Enter Python

But Scaffold still stubbornly clings to the CSS syntax, and it wants you to integrate it into your code. What I really wanted, as well as relief from semi-colons and curly braces, was a way of generating CSS, not on the fly in production, but only during development, so that the live site would only ever serve plain old CSS files with no server processing. So I became much more enthusuastic when I found CleverCSS, which is a way of doing this kind of thing with Python.

This…

…on the execution of clevercss.convert produces this…

A few things to notice in the CleverCSS code: no semi-colons or curly braces; the indentation defines the hierarchy; the use of the ampersand to refer to the parent element for the hover; the arithmetical expression $grey – 76; and the method call $light.darken(50%).

I’m beginning to use this now to generate and update CSS files as I develop a WordPress site. If I find that it’s not right I can easily switch over to something else, or just go back to doing CSS directly – with no harm done and no time wasted.

But CleverCSS is in Python, not PHP, so I can’t very easily weave it into the fabric of the operational code, even if I want to. Instead, here’s the technique I’ve come up with:

1. Let’s say in my CSS folder I’ve got main.clvr and forms.clvr, which never get uploaded to the web server*
2. I do the styling code in these files
3. When I want to see the changes to the web page, I run a Python script from the command line in the CSS folder:

4. Now I’ve got main.css and forms.css

*Note that you can use any extension you want

Here’s make_css.py:

This finds all the CleverCSS files and runs clevercss.convert on their contents, writing the output of each to a CSS file.

I’m really enjoying this technique, but it isn’t perfect. Running the script is an extra step, and that in itself might be enough to put some people off. And CleverCSS, at least the version I have, has no support for custom functions, mixins or macros, as far as I can tell. And debugging in Firebug is on the generated CSS, so you have to relate it back to the CleverCSS yourself.

As it happens, these problems are solved in CSS compilers such as Compass, which uses the SASS language. SASS is comparable to CleverCSS but seems to offer a bit more, including mixins. Compass takes things further: it has a bunch of standard mixins and plugins, support for grid frameworks like 960.gs and Blueprint, and it can integrate into several web app frameworks. Also, it listens for changes to your files so that you don’t have to repeatedly run a script to produce the actual CSS.

But I’m not ready for that kind of commitment. In any case it would be unsuitable for a WordPress site.

I’m very new to this methodology so I’m not necessarily recommending it. The debates continue about whether CSS itself should eventually provide these things, and whether CSS abstraction is just for programmers and not designers – but in principle I believe it’s a step in the right direction.

I’ve only mentioned a few of these languages and frameworks, but there’s a tonne of others out there, all with different syntax. An argument could easily be made that they’re just adding another layer of clutter, when we’ve no idea what’s going to happen with web standards and browsers. These solutions are transient and half-baked, and far less established than CSS itself.

However, used as a convenience in the way I’ve described, it doesn’t introduce any difficulty into development or obscurity into the finished application, which remains just PHP, MySQL, HTML, JavaScript and CSS.

Over the last couple of years there’s been a lot of activity around this. Here are some great articles, with good debates in the comments:
What’s Wrong With CSS
The Demise of Plain CSS
Why Stylesheet Abstraction Matters

CSScaffold
CleverCSS
SASS
Compass

“Refining his architecture? What does he mean?” For me, learning to use MODx well has been about working out how to combine templates, template variables, chunks and snippets in a logical and efficient structure. A good application – a small one, at least – should have a shape that you can envision (if you’re the kind of person who envisions shapes, that is). The shape should be pleasing, natural and economical. In my first two MODx sites I fashioned a few butt-ugly shapes that would certainly have sullied the pages of Euclid’s Elements.

They worked, and they were clever in their ways, but I feel I’ve moved past all that now, that I’m approaching the gleaming heavenly realm of the Platonic solids, of perfect dodecahedrons and icosahedrons.

Maybe I make it difficult for myself. Two components that are mentioned so often in the MODx forum and documentation that you could be forgiven for assuming were part of the core itself, are the snippets Ditto and Jot – but I’ve never used them. And then there’s Wayfinder. I used it once, and it was great, but I didn’t really know what I was doing and I wasn’t comfortable with it, and it was a hassle to learn how to use it. In the project I’m on now I’ve just done it myself, with a “menu” snippet and a couple of chunks. I know the boundaries of the project so I can decide to avoid complication by battening things down; and there’s so little code that changing it will be easy in the event that the structure of the navigation needs to change in the future.

Incidentally, Jot and Ditto are often mentioned in connection with blogs, for which they appear to be indispensable in MODx. Well, say what you like about WordPress but it does blogging pretty damn well and is equally customizable. I fear if I try putting a blog together with MODx, things might get pretty sticky. Even if I was successful I’d still end up with something far inferior to WordPress. This is a tricky situation, because I really do want to be able to use MODx for blogs – the templating system is close to perfection, and WordPress’s is horrible. But this is all by the way.

I really appreciate the work that people put in to writing freely available, open-source code. Wonders abound. But I have to confess: I don’t have much patience when it comes to using plugins, widgets, modules or whatever. If I’m looking for one it’s to save time, so 1. I want it to behave roughly as I’m expecting, and 2. I want good documentation, i.e. documentation I don’t have to spend much time with. Otherwise, I’d rather just do it myself, gaining into the bargain the extra advantage of avoiding the overhead of features I don’t need.

In this last project I’ve been working on, the most common type of page required an image gallery to go underneath the main content, and a main image in the body of the content text. Any page of this type could have photos added to it, and they should appear in the gallery in the same format. For the solution I needed: an easy way for editors to add photos without any resizing woes; auto-generated thumbnails; a way of outputting the gallery HTML; some good HTML and CSS; and a nice Lightbox on the client-side.

I had a look around for a plugin or module but it really wasn’t worth the hassle and nothing I found seemed like a good fit, so here’s what I did. If anyone spots a problem in the code or in the concept itself, let me know.

UPDATES & THINGS TO NOTE:

• This is about MODx Evolution, not the newer Revolution
• I’m not aiming here to provide full site-wide image management. For that, something like MaxiGallery might be a good choice, and certainly provides loads more features.
• The plugin might not work in the 0.9.x versions of MODx. I’m using 1.0.2. Thanks to Dimmy for pointing this out in the comments
• The plugin doesn’t seem to work correctly when using the front-end editor
• It’s not included here but I’d recommend checking the size of the uploaded photos in the first place, and you might want to actually resize all uploaded images so as to standardize the “full-size” photos that are displayed in the lightbox.
• The code here doesn’t check for the existence of files, or handle exceptions

What we’re aiming for

Above is an example of the page type in question, with the portion of the page we’re interested in highlighted. By the way, the photos are not at all relevant to the website – this is just for illustration.

This is not particularly relevant to the MODx side of things, but for the sake of completion the image above shows the lightbox that pops up when you click on a thumbnail.

To achieve all this we need:

• A template for this kind of page
• Template variables for the photos, to apply to this template
• A chunk for the outer HTML of the gallery: gallery
• A chunk for the inner HTML: gallery_item, to be repeated for each photo
• A snippet for the body photo: body_photo
• A snippet for the gallery: gallery
• A plugin: thumbnailer, which generates thumbnails, and runs when a document is saved
• Some CSS to style the gallery HTML
• Some javascript to display the full-size images in a lightbox – I’ll use jQuery

Although it might make sense to explain the thumbnail generation first, I’m going to start with the template, template variables, snippets and chunks to demonstrate the output we’re aiming to produce, and from there move backwards to the plugin. Finally, with the MODx side dealt with I’ll say a bit about the client-side, specifically the lightbox for viewing the full-size photos.

The Template

The template itself can be whatever you like, just so long as there is one that you can target the template variables to and which you can use for all pages of this type. The relevant portion looks like this:

It’s not important that I’m using HTML5 (see the <section> tag). But if you haven’t coded in HTML5 before I heartily recommend it – you can even get it to work in IE with the inclusion of a wee javascript file. This is the first line of an HTML5 document:

Beautiful.

The Template Variables

We need some template variables, one for the main body image and one for each photo in the gallery, and the latter variables need to go in a new category, which I’ve called “Gallery.”

In the editor, this gives you something like this:

You may pick up on a crucial implication of this, namely that the number of photos an editor can add to a page is limited, almost hard-coded. I think this is probably fairly standard practice in the world of CMSs, but it went against my instincts: it’s natural to want to provide the flexibility of being able to add limitless photos. But ultimate flexibility is mostly a complete waste of time, and often holds its own problems. So editors will only be able to add eight photos to a gallery. So what? Looking at the requirements, eight was plenty. To paraphrase 37 Signals in Getting Real, it just didn’t matter. It’s amazing the time you can save by making decisions like this.

Anyway, providing for more photos per page at some point in the future would be a simple matter of the developer/administrator adding more template variables.

The Chunks

We need an outer and an inner chunk.

gallery

gallery_item

The Snippets

First of all, some configuration values to be used both by the snippets and by the plugin.

config.php

It’s not very important where this config file lives. Somewhere in “assets” is good. (And if you’re a big fan of config files you could put other things in here, such as the chunk names. Or, now that I think of it, you could pass in the chunk names in the snippet calls.)

The body_photo snippet is pretty basic, and it’s not crucial to do it this way. As usual with snippets I just include a separate file:

body_photo

body_photo.php

All this does is echo out an image tag to the page if there’s a value for the body_photo template variable, and nothing if there isn’t. Crucially, though, the image is not the one uploaded but a resized version held in a folder for the medium-sized images. More on the resizing later.

By the way, get_tv_value is just a helper function which I’ve got in utility.php:

Now for the gallery. Again, in the MODx manager we need to just include our snippet code:

gallery

gallery.php

In gallery.php, line 12 shows why we put the template variables for the gallery in a new category: we can get a MySQL result for the eight variables. Immediately afterwards we loop through that result to build a bunch of list items, each time injecting values into the gallery_item chunk, which is the inner, repeated chunk of the gallery HTML. Each iteration will replace the various placeholders, [+big+], [+title+] and so on, producing something like this:

Notice that the actual image for the image tag is the thumbnail version, and the surrounding anchor links to the original. Also notice the rel=”lightbox” value, which will be used by the JavaScript.

When we’ve got all the list items it’s time (line 41) to inject them into the outer chunk, gallery, by replacing the placeholder [+gallery_items+]. The end result is something like this:

And then it’s echoed out to the page. With all the template parsing done, the HTML that’s sent to the browser will look something like this:

That’s it for the output side of things. But how do we get those thumbnails, and the medium image, where they’re meant to be?

The Plugin

I’ve called the plugin thumbnailer, but it actually does one other thing, which is generate a medium-sized version of the body photo, which is exactly the size required for the page.

As with the snippets I include an external file:

thumbnailer

Notice the lack of PHP opening and closing tags. In plugins, unlike snippets, you always exclude them (and you always forget to.)

The one other thing to do to set up the plugin in the manager is check the OnDocFormSave System Event, as shown below.

thumbnailer.php

My first instinct when writing this was to use the MODx API to get the template variable values, but when the plugin runs it’s too early to do that, so we have to use $_REQUEST to get the form values directly from the editor. The naming scheme for template variable input elements is “tv[template variable id],” e.g. in my case it was tv9 to tv17 for the gallery variables.

For the thumbnails, we can get the same MySQL result that we used for the snippet (line 21), and then in the loop, concatenate the input name using the template variable IDs (line 28). For the body photo, we can get the name for the input by first getting the ID of the body_photo template variable based on its name (line 37).

For the resizing itself, I’ve used a small class called ImageHelper, which is kindly provided here at Tips for Twits. I’ll include the code here for completeness:

ImageHelper.php

It takes care of cropping and resizing very nicely, and is the simplest and most effective code for this kind of circumstance that I’ve found.

So let’s say an editor has their document looking like this:

In the file system, the result of saving this document will be the following (with all other files excluded).

Client-Side

It’s a simple job to style the HTML output with CSS, so I won’t cover that. So, let’s briefly cover the lightbox. First it needs some CSS like this:

Recall that in the gallery each list item’s image link has rel=”lightbox”. We can use this in following code, which, aside from its dependence on jquery, is the entirety of the lightbox script (it doesn’t work in IE6 though, last time I checked – some tweaking required for that).

Click on the photo below for a demo.

So there you have it. I hope you find it shapely, pleasingly simple, and easy to maintain.

This post is mainly an introduction to the ManagerManager plugin written by Nick Crossland. In my opinion it is absolutely indispensable, unless you’ve come up with your own way of doing the same thing. But it took me a while to get it. It’s possible I was just having a stupid day, but on my first encounter with it I was puzzled and frustrated for a while about how and when to use it, so maybe I can plug some gaps here. Let me just say again that this plugin is absolutely indispensable. Well, I guess you could get by without it, but at the very least it’s very excellent.

Essentially, it allows you to control how resources (also referred to as “documents,” mostly corresponding to web pages) are edited, depending on the role of the user and/or the template used by the resource. Using it you can customize and control the user-experience for content editors by changing, in several ways, the document fields and template variables that are available to users editing a resource. And you do all this by defining “rules” in a single rules file or chunk.

Install

Before I go into what exactly you can do with it, here’s how to set it up. ManagerManager came bundled with my MODx 1.0.2 installation, but you can also get the package from the MODx website. The two things to look out for in the download are plugin.txt and the managermanager folder. Put that folder in yoursite.com/assets/plugins and go to yoursite.com/assets/plugins/managermanager/docs in a browser to read the documentation (you can also see it here on my site if you haven’t downloaded it yet).

In the documentation you get details on installing and setting up, but I’ll briefly go over the steps here. Basically all that’s left to do at this point is to create the plugin in MODx with the contents of plugin.txt. Go to Elements > Manage Elements > Plugins > New Plugin and paste in the code, then check the System Events described in the docs, and then paste in the configuration string in the Configuration tab. The string looks like this:

By the way, if you’re not aware, configuration parameters are defined like this:

So in the configuration string for ManagerManager given above, it sets up a text-field parameter called config_chunk but leaves it blank. If you want to use a chunk to manage your rules, put the name of it in here. My MODx installation already had the chunk mm_demo_rules.

When the plugin runs, it looks for rules in the chunk that you’ve defined in the configuration tab, but if that chunk is empty or nonexistent or not defined in the configuration tab (as in my case), then it looks in the file managermanager/mm_rules.inc.php. I use this file for my rules rather than a chunk, but it’s a matter of taste. Note that if there’s something in the chunk (and the chunk is defined in the configuration), none of the rules in the file will be applied, because the file won’t even be included.

The Rules

So what do the rules actually look like? Basically they’re function calls. All of them are described in the documentation, in the Fields, Tabs, Widgets and Sections pages, and the names to use to refer to the fields are described in Field names. Note that the although these field names mostly correspond to the MODx database field names, not all of them do.

Here’s an example rule:

Your rules file or chunk is just a bunch of these calls, and every time somebody edits a resource, they will be applied. Easy.

Hiding Fields

You may want to hide fields from users who are editing certain resources, because you don’t want those values to be changed. Say you want to fix the value of the parent resource, or you want to ensure that Show in menu is always set to true and can’t be changed. Or maybe you just don’t want to confuse users with too many fields (if there’s no need for them to see the URL alias or Link Attributes fields, why not hide them?).

One of my uses for this is hiding the resource content editor for templates that contain only dynamic data such as tables, feeds, blog post excerpts, and so on. For these pages, all the content is generated by snippets, in combination with chunks, and anything entered as content by the user will not show up (because in the templates and chunks I’m not using the [*content*] field at all) – so it makes sense to remove that functionality.

Setting Default Values

You may want to ensure that certain resources always have the same default value for particular fields. I used this recently when I wanted to set the value of content-type to application/pdf by default. I saw this as a must-have feature, rather than a nice-to-have, because one of the main ongoing actions of editors of this site was to add new PDF documents, the links to which would then be displayed by a snippet in various parts of the site.

Incidentally, this only made sense if I could make sure that the resources in question had a specific default template, so I also used my own plugin to automatically set the template for these resources. I didn’t realize at the time, but I probably could have used an MM rule for that too, namely mm_hideTemplates (see below).

Renaming Fields

Renaming fields changes their labels. One way that I used this was to change “Long title” to “Page heading,” because that’s how I was using [*longtitle*], i.e. as the <h1> heading (in other words, in the relevant chunk I had <h1>[*longtitle*]</h1>). Changing the label just made it clearer for users. The flexibility of MODx means that, by default, fields are named in a fairly abstract way, because you can use them however you want, so more meaningful labels are often better, once you’ve settled on how you’re going to use them.

Changing the Help Text

This way you can help to tailor the user’s experience to the specific functionality of your implementation. If you’ve customized things to a great extent, some of the help text will begin to be useless or even misleading, so it’s good to keep things tight by paying attention to stuff like this.

Synching Fields

Use this to ensure that fields always have the same value. I haven’t used this myself, but I’m sure I will.

Inheriting Values From the Parent Resource

Does what it says on the tin.

Hiding Templates

The above example removes the (blank) template from the Uses Template drop-down. As I noted above, it looks like I could have used this when I needed to set a default template by hiding all the other templates from the drop-down list, instead of using my own plugin. I haven’t tried it though.

Tabs, Widgets and Sections

There are also a number of functions for changing the tabs and sections. For example, if you want to restrict users to editing the content field and nothing else, hide the Settings tab as well as hiding fields in the General tab. Sections, by the way, are a MODx way of grouping fields together in the edit screen. Common ones you’ll see are “Resource content” and “Template variables.” As for widgets, ManagerManager provides a few functions for changing the widget that is rendered for a field, eg. colour-picker or image preview.

With careful combinations of rules, and any logic you fancy putting in the rules file, you can get as clever as you like.

For more information on ManagerManager have a look at the dedicated board on the MODx forum.

For the next MODx-related post…I’m not sure. One thing I’ve found interesting: I struggled for a while to find a satisfying way of combining two requirements regarding javascript. 1) How to manage and maintain my javascript files easily and avoid any duplicated code; and 2) also ensure that the resulting page is optimized for speed (sometimes I find it quite hard to settle for a YSlow grade of B). I’d love to see how other developers manage this in MODx.

This javascript/jQuery code gets the contents of your cart (which is in the variable fc_json, made available by foxycart_includes.js), removes any item whose name matches a certain string, and then adds your new item. It looks so obvious now, but it took a while for me to get it.

I’m working on a shopping cart at the moment, and it’s my first day with FoxyCart, which is a really nice solution for a common but pretty badly-catered-for requirement (ie. online shopping carts and checkouts). I wanted to just plug and play: just set up a few templates for the cart, checkout and email receipt, and go with that, because FoxyCart is pretty nice without too much customization. But things are rarely so simple. The website will be selling not only products in a shop, but registrations to an event. Yep, that’s still easy, but a registration can be for multiple attendees, and the registrant needs to fill in the same information about each of them as he did for himself, and some of that information determines the price.

So the registrant’s gone through the whole process of filling in the forms for each attendee, and they get to their registration summary page, and there’s a list of the names of the attendees with the cost for each one (which depends on what information was supplied, what boxes were ticked), and a grand total at the bottom. This is all before they get to the shopping cart. It’s true that when adding to the FoxyCart cart you can supply it with options and corresponding prices, and this would have been good for allowing for the selection of multiple attendees; but it wouldn’t have allowed for the entry of all the attendee-specific details and their corresponding prices.

A Problem

So they hit “Add to cart” and then “Checkout” and everything’s great – if that’s the only thing they do. But what if, after adding the registration to the cart, they go back and change the details for an attendee, thereby changing the price? First of all I set the quantity_max parameter to 1 to prevent them adding it twice. But if what you’re adding has a different price, it’s treated as a different item. If they click to update the cart with a registration that comes to a different price from the one they previously added, the amended registration is added as a new product, so that they now have two in the cart.

It seems odd that FoxyCart gets stuck on this, and I thought there must be some parameter I could use, but I couldn’t find it. The solution had to be to either somehow update the price of the item in the cart, or remove any registration in the cart before adding the amended one. I ended up using the latter. To do it requires JSON AJAX requests, which you can do in jQuery with $.getJSON or $.ajax. Anyway, I quickly arrived at the essential logic on which the above code is based. But I couldn’t get it to work.

I was led first of all to use the fc_PreProcess() function. From reading the documentation it seemed that I should define a function called fc_PreProcess, put all the code inside that, and then the included FoxyCart javascript file would find my function definition and execute it prior to adding anything to the cart. Sounds perfect, I thought.

Here’s how it didn’t work. You add a registration to the cart, close the cart, amend your registration so that it now has a new price, and then add to the cart again (although as far as the user is concerned they are updating the cart), at which point the new one should be substituted for the old. And at first it seemed to work: only one registration item in the cart, and with the new price too! I cheered at the time, until I clicked “checkout” to find that the item had just fallen out. And doing it all again I saw that in the cart itself the item would disappear if you refreshed it.

What seemed to be happening was that even though the item was displayed in the cart, it had since disappeared. The item was being removed after it was added; more precisely: a new one was added, making a total of two items; the cart was displayed; and then my code found and removed both items. I’m still not quite sure how this happened, but blame may lie in the asynchronous nature of the JSON calls, mixed use of http and https, sessions, or in my lack of sleep.

A Solution

So what you see above is the hand-made solution. The “add to cart” or “update cart” button on my registration summary page doesn’t submit the form, it just executes the function add_pre_process(), which looks for an existing registration and removes any it finds; and then adds the new one. There is a separate “View cart” button.

Ideally I would have liked to use the success callback of the ajax request in add_item(), but it doesn’t fire.

So, the problem seems to be solved, but not properly solved. The question now is do I spend time investigating what the problem was and delve deep into the workings of FoxyCart, or move on to the next stage, which is the shop. Well, I’ve got two websites going live in the first week of January, so it’s no contest. Onwards!

Anyway, my first intention was to stick with PHP, so I was led to have a look at the CodeIgniter framework after I watched a couple of excellent tutorial screencasts by Jeffrey Way on nettuts. But then I discovered Kohana, originally a fork of CodeIgniter but apparently better in several ways. Last time I checked, CodeIgniter was very PHP4-centric, whereas Kohana is most definitely a PHP5 beast, with all the OO stuff that entails.

I haven’t been able to use it in anger yet, but I’ve set a few things up with it, and it gives me a nice warm feeling. It seems really lean and simple and built in the right spirit, and it didn’t take me as long to get my head around the MVC pattern as I’d expected.

The thing is, now I find my thoughts drifting into alien territory…

This goes back to my previous post about web development choices. The more I look, the more confused I become. I wouldn’t consider anything Java or .NET, so in the area I’m looking at the big [puts on suit and pulls a sombre, earnest expression] SERIOUS frameworks seem to be Ruby on Rails and Django. I’ve been trying out Python with the Google App Engine, and I forgot how great it was to learn a new programming language, so Django – a Python framework – looks like a good way to go. But something in me cries out NO – do I really need all that stuff? Look, there’s this guy over here says Django’s too big and bloated; but wait, there’s that guy over there says with Django he can spit out ten amazing websites every day.

But coalescing out of my confusion is the perception of a contrast in the community, and for those who build websites and web apps it’s good to be aware of this. On the one hand there are those whose overriding concerns arise from their work in creating and maintaining the frameworks themselves; and on the other hand there are those who just want to make websites. This became obvious to me after watching two video talks from DjangoCon 2008 (yes, I’m still catching up with all this), one by Mark Ramm, one of the guys behind TurboGears (another Python framework), and the other by James Bennett, one of the Django guys.

Now, I’m aware that the subjects of these talks were quite different, and pitched at different levels, but nevertheless I do think it’s fruitful to compare them.

Mark Ramm seemed most interested in guiding the philosophy of the Python community, about the future of Python frameworks and how they should be taken forward. In particular he criticized the “monolithic,” all-things-to-all-people approach of Django, opposing it to the Turbogears/Pylons approach, which is to open things up, to make it easy (even necessary) for developers to grab this bit here and that bit there and carefully craft an optimal whole. His standpoint reflected his immersion in developing for – or the development of – web app frameworks.

James Bennett’s focus was on developing with frameworks – that is, building web applications – rather than on how best to build the frameworks themselves. He talked about the most efficient ways to approach the development of an application using Django, for maximum code re-use and maintainability.

Of course, these are not implacably opposed positions: it’s just a difference of focus. Both may be right in their own ways, but as a freelance developer of – currently – small to medium websites, I naturally find James Bennett’s focus on the day-to-day business of making a web app much more appealing.

It might be true, as Mark Ramm says, that you don’t get perfection by installing everything in one bundle and just running with it, but to me that’s rather academic. Everyone is agreed that the purpose of frameworks is to free us from the boring repetitive tasks of this line of work. We shouldn’t have to even think about admin interfaces, form-handling, nice URLs, templating, or ORM data-mapping. But further, I just want some one thing that does all that pretty well. If I have to pick and choose between different combinations, and try to get all the bits working nicely together, then I’m thinking about it: I’m wasting my time. I don’t want to think about the optimal key set-up of a saxophone – I just want to make music (is that a cheesy analogy?)

Before I realized this I struggled to stay a course through the choices facing me, taken first in one direction and then another, each with its own passionate and persuasive adherents. But now, even if the two approaches I’ve perceived are just sides of the same coin, I can use this idea of a dichotomy to sort and prioritize the opinions I find.

However, I now find myself considering having a go at building a web app with Haskell, a functional programming language beloved of geniuses, hippies, mad scientists and my good friend Paul Keir (who might fall in all three of those categories). The introductory message at haskell.org has the words ADVANCED, PURE, CUTTING EDGE, RESEARCH, CORRECT, and PARALLELISM (eh?). That’s all a bit scary to me.