Create Base Skin

This is about a new base skin to build other skins upon. At the same time this is a project of refactoring current template practice.

Our goals:

• Provide base for new skins - to provide bare functionality with little markup
  • Have CSS and javascript as additional layers
• Let go of old clutter: clean up template structure and complex template macros (facilitated by recent additions like ADDTOZONE and RecursiveTMPLDefinitions
• Provide fully working working topic interaction with the js (AJAX) layer
• Create a template API

Basic functionality

Basic, or even bare functionality, how does that look like?

• No css, no js:
  • Clean and documented template structure with easy to understand template macros
• CSS layer:
  • Implementations for default foswikiXxx class names
  • Base styling for column grid (so columns can be used in topic texts)
  • Base styling for font grid
• JS layer:
  • jQuery to enable all basic scripts and possible jquery plugins
  • Topic interaction with AJAX

Implementation

CSS

We need to reduce the amount of css files (at least compared to pattern skin). And at the same time make style sheets easier to edit. PatternSkinColorSettings was a step into that direction, but nowadays we have tools like Sass to generate css: http://sass-lang.com/, http://search.cpan.org/~rpettett/Text-Sass-v0.9.1/lib/Text/Sass.pm

Base skin must provide fundaments for theming (a lot simpler than PatternSkin themes). For instance make it easy to add one or two sidebars, or to change the height of the top bar.

Minimal CSS is provided with skin path basecss, for instance for horizontal lists and sidebars. We could also provide fundaments for grids: (column grid like http://cssgrid.net/ and font grid).

Skin authors must be able to choose:

• use jquery theme
• override jquery theme

Javascript

Base skin must work without javascript. So with skin path base or base,basecss, foswiki still needs to be fully usable. This will pose requirements to the templates.

But with javascript on base skin is fully ajaxed (overriding skins should not have to implement topic interaction with AJAX).

Default functionality is provided by jQuery. We should move away from previously created javascript libraries.

jQuery might be enhanced with underscore.js, backbone.js and mustache.js, dependent how complex the js layer will become.

Templates

We need to separate templates that are required by core from skin sub templates.

There is a trade-off between readability and clarity versus extensibility. I think we all feel that patter skin is too extensible to the point of it being unreadable.

Templates must support single page interaction and AJAX interaction. For instance, each template must have its core functionality in a loadable container.

As functionality is layered, the most obvious thing would be to add this through 'sub skins' (although provided by BaseSkin) by adding css and js in their view templates.The skin path would then be: base,basecss,basejs. BaseSkin should provide these base sub skins with view.base.tmpl, view.basecss.tmpl and view.basejs.tmpl.

Creating a skin upon base skin

The skin would implement one or more templates, for instance a new view template. The skin path could look like this: base,basecss,basejs,myskin.

If the skin totally overrides basecss, it would become base,basejs,myskin.

-- ArthurClemens - 06 Apr 2010, 03 Jan 2011, 05 Jan 2011

Discussion

Ah, I was going to ask if this discussion had moved someplace else.

I think the first thing required will be a decent parser. The current parser is way too non-deterministic to support an extensible skin framework. Such a framework will require a parser that handles quoting, escaping, scoping, and end-of-lines correctly, predictably, and reliably. Writing such a parser is not difficult. The problem is all the years' worth of work-arounds for the current %EMOTE{"Grit Teeth"}%logic%END-EMOTE% that is embedded all throughout the core and plug-in code. That effort will probably require a major revision change to Foswiki 2.0 and break compatibility with earlier versions/code bases.

I also think the envisioned extreme skin path is a bit too extreme. I don't really see how having basecss and basejs skins helps very much at all. The CSS and JS for the base skin are just as easily supported via template files within the base skin itself. It's not like the CSS and JS are really going to be all that re-usable such that you would use templates from the basecss and/or basejs skins but not use the base skin. Anything in the basecss and basejs templates could only reference elements defined in the base skin templates anyway, so why try to make them appear to be stand-alone?

For that matter, I don't understand how printing is supposed to work under the skin/cover scheme in current use. A printed wiki topic isn't really just a handful of tweaks applied by a ?cover=print override. It's not like the tweaks can be shared and applied across any arbitrary skin hierarchy. The skin is intimately involved with both screen and print media definitions. That is, what is the value of ?skin=MySkin;cover=print versus just saying ?skin=MyPrintSkin or ?skin=MySkin;media=print or even /bin/print/MyWeb/MyTopic ?

-- BryanThale - 04 Jan 2011

Without knowing what your specific criticisms of the current parsers - not, parsers, not parser - are, it's hard to comment, but I'll make the observation that every attempt to rationalise the parsing has been blocked by the same fundamental problem viz. legacy.

Currently there are three key text processing steps in Foswiki:

1. On topic read, meta-data is parsed out of topic text
2. During topic expansion, macros are parsed and expanded
3. During topic expansion, TML is interpreted and expanded.

Of these, 1 and 2 are pretty well defined and robust. 3 is a significant problem; my next improvement step was going to be pulling static table parsing out, but even that is very difficult. So I look forward to specific proposals.

While I strongly support the idea of a base skin, I think it should not be javascript-dependent. There is still a large segment of the userbase that do not, prefer not to, or cannot use javascript, and if the base skin requires it, it makes fallback all the harder. I'd rather see a simple, mostly unconfigurable, base skin that has a JS extension built on top.

-- CrawfordCurrie - 04 Jan 2011

The idea of this skin is to provide a "good default" for skin developers, alike the Sandbox theme for Wordpress. This is about templates and about css markup.

The js functionality would be added by putting basejs in the skin path.

-- ArthurClemens - 04 Jan 2011

I agree that any base skin should be largely JS free. I just disagree that JS is something you can "layer on". I see it as an integral part of the skin, so a skin path like ?skin=myskin,base makes more sense to me since the JS will by definition be myskin skin specific. There is no value to requiring myskin, myskincss, and myskinjs skins in order to define MySkin as it just adds complexity without any benefit.

The base skin should be concerned with defining basic templates for each component of the Foswiki UI rather than doing very much in the way of formatting. For example, a template for the Edit link, a template for the Print link, a template for the View menu, etc. while allowing the derivative skin to define what those components look like or where they appear on the page or how they are presented to the user. For example, one skin may use a bar of links in the page footer, another a bar of icons in the header, and another may present the links as a slide-out menu in the sidebar. Although each is a very different presentation, each should be using the same basic component templates to generate the functional components involved.

The goal should be to have the base skin contain the "business logic" or application details of Foswiki while the derivative skins define the layout and eye candy. It shouldn't be necessary for a skin developer to know what the Foswiki URL structure is for example. They should be able to simply invoke a template that will resolve to the necessary HTML code for that particular UI component. The skin designer is then free to style the element to look like a button or an icon or whatever.

The problem with the current parser is partly that it is fragmented into multiple ad hoc parsing routines sprinkled around the code. I'd disagree that 2 is well defined and robust. The parsing and expansion of macros is totally non-deterministic. For example, you cannot know how %A%B%C% will be expanded for any particular topic. That makes developing an extensible skin problematic.

Also, the current routines do not handle quoted strings, escaping characters, processing scope, or end-of-lines correctly, so it is possible, even likely, to have a macro work correctly when invoked directly within a topic and break horribly when invoked from another macro or when included from another topic.

Since the parser was inherited and is quite elderly, an entire ecosystem of hacks and work-arounds has grown up and proliferated throughout the core and plug-ins to try and get things to work more or less. Fixing it will require a break in compatibility, no doubt about it. That's why I suggested it would probably be a 2.0 type of effort rather than a 1.x point release. I don't really see that as a show stopper. At some point you just have to say "Oops" and correct course.

I took a run at creating a new and improved parser which wasn't too tough. IIRC, it involved modifications to only 3 files but I immediately ran afoul of the previously mentioned hacks and special-purpose parsers used by folks to avoid using the broken primary parser. If I was to run all of that code to ground and fix it, I'd be maintaining my own fork of Foswiki which I'm not willing to do. I'd only want to do that as part of an official Foswiki 2.0 effort which will accept the code back into the project code base.

-- BryanThale - 04 Jan 2011

What has value to me is the content of my Foswikis and not the skin.

I do not know what kind of compatibility you suggest broken. But in general protection of the current users content is something we beed to treat as something holy. The millipns of dollars of value is in content. Not in the ability of some geeks like us to hack around.

Each and every compatibility break has to be taken case by case and the damage evaluated. If someone wants to start from scratch and target only new users they need to fork the project and start a new wiki for the young and naive.

On the base skin idea. I have for a long time asked for a stable skin API that I can trust so my edit and view templates can be made in a safe way without danger of spending 2 weeks on a Foswiki upgrade. Template tailoring means redefining specific elements in the existing templates. It takes ONE tiny change of some element name and you can spend hours fixing what is broken when upgrading. 10 major changes and you spend a week or two.

I would like to see a base skin created with the idea of a frozen API in mind with a list of documented API elements to be used for safe tailoring. If you stick to this API with its obvious limitations you are upgrade safe and your tailorings may even work in another skin. If you step outside you are asking for trouble. Just like we know from our Func API for plugins.

Getting to this would mean ONE upgrade effort from 1.x to 2.0 but then I should be able to sleep calmly.

Typical tailoring elements are removing buttons in the UI, adding them, moving the form to the top, adding stuff above or below the TEXT. These simple tailorings should be upgrade safe.

-- KennethLavrsen - 04 Jan 2011

Bryan, IMHO the macro parser is actually one of the few truly deterministic and context-free parsers in the Foswiki system. We should move this discussion to another topic if you have specific proposals that we can discuss; but remember, the basic requirement is that the current unit tests continue to pass (this was how I developed the current macro parser).

Regarding the base skin; I'm glad we all agree that JS-free should be the goal. I'm 100% behind the idea that we get back to a simple set of skin fundamentals that are well documented. There are a lot of hacks in the core that deal with skin specifics, and identifying, documenting and (if possible) abstracting them, should be an important goal of this work.

My personal view is that such a base skin should not attempt to define too many macros. One of the problems I have with Pattern skin at the moment is that there are so many different macros that look like they are asking to be redefined, but they never seem to do exactly what I expect. In some sense, it's too configurable for anyone to get their head around. Defining the base skin so that there are fewer configuration points would IMHO help a lot.

-- CrawfordCurrie - 05 Jan 2011

Foswiki provides more than one way to parse macros. To simplify: there is the good way i.e. using the parser that Crawford referred to, which processes preferences and the "registered tag handler" macros, and there are several bad ways e.g. using a regex in a commonTagsHandler. Unfortunately, many users get a bad impression of Foswiki's macro parsing because they use the CALC macro, which does not use the good way (and which has been given some attention, but I believe it is still a work-in-progress). Please don't paint all macro "parsing" with the same brush.

I have shied away from customising PatternSkin on the wikis I administer because, for the most part, it is a lot of work for little benefit. The work is in learning all about PatternSkin, and the learning is hard (to me) precisely because it has so many configuration points. One can do so many amazing things with PatternSkin that I struggled to find out how to get it do the few things that I wanted.

-- MichaelTempest - 05 Jan 2011

I have started a more detailed description at the top that should become a requirements list and technical plan at some point in the near future.

-- ArthurClemens - 05 Jan 2011

I agree that there shouldn't be any JS in the BaseSkin, but I think its OK to include some basic CSS. CSS can be easily overridden, and there are styles like foswikiAlert that no one will want to redefine.

-- AndrewJones - 05 Jan 2011

Commenting is disabled while not logged in