HTML Logo by World Wide Web Consortium (www.w3.org). Click to learn more about our commitment to accessibility and standards.

Moving forward with Composr

ocPortal has been relaunched as Composr CMS, which is now in beta. ocPortal 9 will be superseded by Composr 10.

Head over to compo.sr for our new site, and to our migration roadmap. Existing ocPortal member accounts have been mirrored.


I seem to be running into a wall...

Login / Search

 [ Join | More ]
 Add topic 
Posted
Rating:
#49816 (In Topic #10858)
Avatar

Fan in action

basic templating problems

OK, so I have gone through the installation, and the Setup Wizard (twice). As I am poking around the system I see a lot that I like. Each time I discover something new, my first reaction is "Oh, nice!". There don't seem to be any language files yet, and that is a problem - but going through the forums that seems solvable.

But I really need my own "theme", and looking at page source code, templates and templating system, I'm afraid I see a lot that I don't like. This would probably be solvable, too, but my first impression is I'm looking at a time investment of at least one month. :(

I'll describe below what process I went through, and try to sum up what problems I've encountered so far. I may be missing things, but I don't think I'm missing the essential things - please tell me if I am!:
  • Looking at the stylesheet generated by the Setup Wizard (or the style Wizard) I can sort of see the generated colors - but they're all over the place. These colors are only a starting point - but because the colors are not all in one place, setting up one or more different color schemes would be pretty hard.
  • Going through the Setup Wizards I was also confused by all the references to "left panel" and "right panel" (no way to choose to put some things at the bottom!), and even if I put everything in the "right panel" there was still a lot of stuff in the "left panel".
  • The generated layout seems to be fixed-width by default, which disappointed me, too. For a starter wizard to set up your basic theme, I'd have expected a choice between 1- 2- and 3-column layout, and a choice between fixed and fluid, at least.
  • I also haven't yet found out where the choices of what to use, and in which place to display it, are actually going, or how to edit the choices I made in the Setup Wizard - which is why I went through it a second time. But I still don't know how else to determine what should appear where.
  • Looking at the generated XHTML, I also noted that the main content area (visually between "left panel" and "right panel") actually comes after the two side panels: not good for SEO; and if there's a "jump to content" link, I haven't discovered it yet: not good for accessibility. (An alternative would be to have the main content area first in the text stream, and use CSS to put it in the middle, if you must have it appear there. Even then a "jump to content" link would be useful to get past the branding and main menu.) So, I'd obviously have quite a bit to do to change that, and I started to look into templating
  • First stop: Looking at generated XHTML source in more detail, I see tons of inline CSS, inline event handlers and even inline JavaScript code (i.e. other than just a simple function call). That is an absolute no-no for me, and not just because I don't like it that way:
    I'm in the Netherlands, setting up a consultancy for web development, with Open Source, Open Standards and Open Accessibility as the main starting points. We have a government accessibility standard (required for any government site, and recommended for other sites); it's pretty strict, largely based on what is now WCAG 2, with a lot of "current good practice" added and gluing it together. If I'm going to "sell" accessibility, obviously that standard will be part of it. And equally obviously, my own website will have to comply. But with the code as generated by ocPortal "out of the box" it definitely won't, because complete separation of markup, styling and scripting (XHTML, CSS, JavaScript) is one of the rules.
    So, I need squeaky-clean code. Looking at the templates, the inline CSS would be easiest to solve, by just replacing each inline CSS with an id or class and putting it all in a linked stylesheet (but not quite, see below). The JavaScript is a much bigger problem because essentially I'd have to code all the event handling to make it completely unobtrusive - big job.
  • So, I investigated what would need to be done to start from scratch (I have a basic generic template already that I would like to use). I looked at templates: I soon found the basic templates all come from the "default theme", and it seemed obvious that to override one you'd have to place your own variant in your theme's directory (that's a common enough mechanism). But exploring the templates, I could not find how they go together; for instance, I found HEADER.tpl, GLOBAL.tpl and FOOTER.tpl - together they seem to build the basic page structure; but I could not find any template that pulls them together. What if I want a different structure? Also, looking at the generated source, I can see no clue what bit of code is generated by which template - and if there is a switch somewhere to add comments to do that I haven't found it yet.
    Then I found the "template tree". The problem here is, it isn't really a tree. What pulls HEADER.tpl, GLOBAL.tpl and FOOTER.tpl together is something called "mixed", which seems to be editable somehow, but obviously is not an editable template. There is also a "container" (not even a link) that seems to contain the list of stylesheets - including inline styles which I would prefer as a linked stylesheet, and if it isn't should come after the linked stylesheets (its template only contains {CSS/} as content for the style tag). And what determines the order in which the stylesheets appear? "container" isn't editable at all, and if I look in HEADER.tpl, all I see is {$CSS_TEMPCODE}.
    I may have missed something, but it seems to me an awful lot of the code generation isn't actually driven by the templates at all, but by PHP source code. And that would make starting from scratch awfully hard, too, since it might involve hacking the source code as well.

So that describes more or less the process I went through yesterday (and a bit early this morning). And from what I'm seeing, it would be exceedingly hard to adapt templates to my criteria, and even harder to start from scratch with a clean slate, because it isn't all templating, there's PHP code involved as well. Maybe I'm still missing something essential, but I don't think I am.

Has anyone created a complete theme without any inline CSS and JavaScript? If so, maybe I could use that as a starting point, at least. If not, I will put ocPortal on the "would be nice" shelf to look at again later (I'm not giving up on it yet) and go looking for something else that allows more control over templating. Unless, I really did miss something essential.

ocPortal is great, if you can live with the default templates or what can be derived directly from that. It has a lot to offer right out of the box, works, it even validates - and that's a fantastic job! But it seems to me if you really need a structurally different template, you're pretty much stuck or at least have to invest a lot of time - not only on templates but on PHP code as well.

I'm afraid this all sounds very negative, and I don't intend that. It's just that I don't see how ocPortal currently would be a good solution for me, and with all the good things I'm seeing here, that's a disappointment.

Comments? Hints?

Marjolein Katsma
follow me on identi.ca
Back to the top
 
Posted
Rating:
#49818
Avatar

Hi,

It really sounds like you need to look at the documentation. A lot of problems you've found have solutions in the documentation, or to be frank are imagined and the documentation would show why.
I'll quickly go through and answer a few things directly.

There don't seem to be any language files yet

I'm not sure what you mean here, because there are definitely language files, and editable from the Admin Zone. If you do a search (top-right of Admin Zone) for "language" or "translate" I'm sure it'd come up – this is a good way to find features you don't immediately see. You'll also find it in the 'Style' section.

Looking at the stylesheet generated by the Setup Wizard (or the style Wizard) I can sort of see the generated colors - but they're all over the place. These colors are only a starting point - but because the colors are not all in one place, setting up one or more different color schemes would be pretty hard.

I'm not sure what you expected to be honest. What is it you were hoping for? ocPortal has generated a default scheme, which I don't think any other software can do – then it's regular CSS. Search and replace is a useful tool if you need to make mass changes. If you think CSS should have variables, I'm all for it – but it doesn't, and I don't think it would have been appropriate for us to implement a whole new layer of code on top of the CSS for that, as it would just non-standardise and confuse.

Going through the Setup Wizards I was also confused by all the references to "left panel" and "right panel" (no way to choose to put some things at the bottom!), and even if I put everything in the "right panel" there was still a lot of stuff in the "left panel".

I also haven't yet found out where the choices of what to use, and in which place to display it, are actually going, or how to edit the choices I made in the Setup Wizard - which is why I went through it a second time. But I still don't know how else to determine what should appear where.

There are clear "Edit" links underneath everything that you can use to edit the arrangements. This is definitely where you need to check the documentation, it's explained in quite some depth.

The generated layout seems to be fixed-width by default, which disappointed me, too.

It's definitely not fixed width, I'm not sure why you'd come to that conclusion.

For a starter wizard to set up your basic theme, I'd have expected a choice between 1- 2- and 3-column layout, and a choice between fixed and fluid, at least.

I'm not aware of any of our Open Source competitors even having a starter wizard to create a theme, but we'll take the feedback on board. A more powerful Setup/Theme Wizard is something that interests us.

Looking at the generated XHTML, I also noted that the main content area (visually between "left panel" and "right panel") actually comes after the two side panels: not good for SEO;

We'll consider changing this, but to be honest I question whether this SEO technique actually makes a real difference, and I'm not the only one (second hit on Google for "content order" seo). It would be nice to see some statistics on it.

if there's a "jump to content" link, I haven't discovered it yet

It's right there in GLOBAL.tpl:

Code

<a accesskey="s" class="accessibility_hidden">{!SKIP_NAVIGATION}</a>
and you can see we even gave it an accesskey as per the conventional keymap (the one based on UK government guidelines that became popular).

inline CSS

There's very little inline CSS. Either it's:
  • the CSS from 'nocache.css' that we need to include inline for browser compatibility (we don't use browser hacks, so we use a server-side detect and inject a small amount into the output stream based on that).
  • or it's something like "float: right" which we decided to keep out of the external sheets because it would have made the sheets extra long (harder to edit, more file size to transfer), but removing it would have not had a big impact anyway because element order also dictates floatability and thus you'd need to edit the templates to change such things anyway.

inline event handlers

I know some people like to keep event handlers separate and consider it a "best practice" but I think that's a load of rubbish quite frankly. Keeping them separate adds to the complexity of the system because you can't see what is going on in-situe. It's not an accessibility problem, it's not a code complexity problem, it's not a page weight problem (explained below), it's not an SEO problem – and we couldn't change it anyway really because a modular user-editable system like ocPortal really needs to be able to output a integrated code stream because it's non-predictable (from a static JS perspective) exactly what would be used on any arbitrary screen.

inline JavaScript code

There's very little of this, and when it happens it's for a clear reason to do with either modularity or page weight. It's not good generally to include inline JS for two reasons:
  • difficult to edit (as the code is quite strewn around)
  • adds to average page weight
However those reasons are not always the case. In some situations it would add to the average page weight if relatively obscure JS code was added to the global JS. It's also very arguable that it makes things easier to edit if things are inline because they are in-situe.

because complete separation of markup, styling and scripting (XHTML, CSS, JavaScript) is one of the rules.

Frankly we can't take responsibility for silly rules. Rules that are written by people with experience developing non-CMSs are not going to work well with CMSs. Because ocPortal is modular and user-editable, static assumptions that a coder might be able to make on a static or custom developed site are not going to be applicable.
I appreciate some CMS's might work differently, but those would be basic page/article systems, which have less modules and thus can make more static assumptions.

But exploring the templates, I could not find how they go together; for instance, I found HEADER.tpl, GLOBAL.tpl and FOOTER.tpl - together they seem to build the basic page structure; but I could not find any template that pulls them together. What if I want a different structure?

You would not need a different structure – any site will have a header and footer and even if it didn't (beyond the basic HTML requirements that wrap a page), you could put more into GLOBAL.tpl. Honestly, this is an imagined problem – no one has ever reported any issue like this.

Then I found the "template tree". The problem here is, it isn't really a tree.

It is really a tree, even if some of the nodes originate from PHP constructs.

and if there is a switch somewhere to add comments to do that I haven't found it yet.

Described in the documentation.

I may have missed something, but it seems to me an awful lot of the code generation isn't actually driven by the templates at all, but by PHP source code.

That's simply not the case, and frankly I don't like seeing this written on the forum as it spreads FUD to users.
Some orders come from the code, but it's really very minimal. The order of CSS includes, but you don't need to change that. If you read the Tempcode tutorial you would also see you can completely override any ordering assumptions we have made using our 'shift encoding' mechanism.


Become a fan of ocPortal on Facebook or add me as a friend. Add me on on Twitter.
Was I helpful?
  • If not, please let us know how we can do better (please try and propose any bigger ideas in such a way that they are fundable and scalable).
  • If so, please let others know about ocPortal whenever you see the opportunity.
  • If my reply is too Vulcan or expressed too much in business-strategy terms, and not particularly personal, I apologise. As a company & project maintainer, time is very limited to me, so usually when I write a reply I try and make it generic advice to all readers. I'm also naturally a joined-up thinker, so I always express my thoughts in combined business and technical terms. I recognise not everyone likes that, don't let my Vulcan-thinking stop you enjoying ocPortal on fun personal projects.
  • If my response can inspire a community tutorial, that's a great way of giving back to the project as a user.
Back to the top
 
Posted
Rating:
#49823
Avatar

Fan in action

Chris Graham said

I don't like seeing this written on the forum as it spreads FUD to users.
Let me address that first. I am not, in any way or form, trying to spread FUD - what I  am doing is reporting my process of analyzing ocPortal for my (possible) use, and some (major, to me) problems I encountered. And I am doing that to help you, spending quite some time to write it up (and writing this response). I could also just have dropped out but chose not to do that and share my experience instead.

I also made it clear that I still like ocPortal, and am not giving up on it - but it seems to me I'd need an awfully big investment in time to make it work for me.

Chris Graham said

It really sounds like you need to look at the documentation. A lot of problems you've found have solutions in the documentation, or to be frank are imagined and the documentation would show why.
Admittedly I haven't read all documentation (there's too much of it to read in one day, and that's good. But I have read more than you seem to believe.

Chris Graham said

There don't seem to be any language files yet

I'm not sure what you mean here, because there are definitely language files, and editable from the Admin Zone. If you do a search (top-right of Admin Zone) for "language" or "translate" I'm sure it'd come up – this is a good way to find features you don't immediately see. You'll also find it in the 'Style' section.
As I mentioned elsewhere, I started by exploring the site. Since a "community" around an Open Source package is important, I naturally also looked at the Community page, where I found the link for Language Packs: that page is empty: there aren't any. I found that odd, but thought maybe some common languages would be included in the install - there was only English. So, later I also read a number of forum threads about localization efforts. If this has led to anything tangible, it's not on the "language packs" page; in one thread there had been a download that was pulled (and it would be outdated now anyway).

I know it's possible to translate - I'm just disappointed there isn't anything available yet.

Looking at the stylesheet generated by the Setup Wizard (or the style Wizard) I can sort of see the generated colors - but they're all over the place. These colors are only a starting point - but because the colors are not all in one place, setting up one or more different color schemes would be pretty hard.

I'm not sure what you expected to be honest. What is it you were hoping for? ocPortal has generated a default scheme, which I don't think any other software can do – then it's regular CSS. Search and replace is a useful tool if you need to make mass changes. If you think CSS should have variables, I'm all for it – but it doesn't, and I don't think it would have been appropriate for us to implement a whole new layer of code on top of the CSS for that, as it would just non-standardise and confuse.
Variables would be nice but that's not what I'm referring to. A major step in any "theming" effort (and sometimes the only one) is to create or change the color scheme. The Wizard generates a color scheme, and I'd expect its output to be in one place: either a stylesheet, or a separate section in the basic stylesheet that puts all the colors together: that way you can also change them together to make a new color scheme.

Going through the Setup Wizards I was also confused by all the references to "left panel" and "right panel" (no way to choose to put some things at the bottom!), and even if I put everything in the "right panel" there was still a lot of stuff in the "left panel".

I also haven't yet found out where the choices of what to use, and in which place to display it, are actually going, or how to edit the choices I made in the Setup Wizard - which is why I went through it a second time. But I still don't know how else to determine what should appear where.

There are clear "Edit" links underneath everything that you can use to edit the arrangements. This is definitely where you need to check the documentation, it's explained in quite some depth.
I did read the documentation about the edit links, but that's not what I'm directly referring to.

But what I read there implies that what the edit links give access to is not in the templates. And there's the crux.

If the edit links thus give access to "arrangements", some of these arrangements obviously are not in the templates. There are bits in templates and there are bits elsewhere, and not easy way that I can see to edit it all as a whole.

None of which actually explains where the choices made in the Setup wizard are actually recorded - I found a very few in the database, but by no means all the output  of what I input in the forms.

The generated layout seems to be fixed-width by default, which disappointed me, too.

It's definitely not fixed width, I'm not sure why you'd come to that conclusion.
If it isn't I haven't noticed. I came to that conclusion because this site, as well the site that was generated for me, isn't usable at my normal browser width of 800px. In this forum, I get a horizontal scrollbar, and even if I scroll the "left panel" out of sight, the content of the posts is still not readable without using the scrollbar all the time to follow whole lines. On my generated site there is no horizontal scrollbar, but the top menu cannot cope: it "tries" to wrap but ends up hiding a lot of the links. If it isn't fixed-width, it is at least not completely "fluid" or "elastic" (yes I know the terms are used interchangeably though they don't mean exactly the same thing).

For a starter wizard to set up your basic theme, I'd have expected a choice between 1- 2- and 3-column layout, and a choice between fixed and fluid, at least.

I'm not aware of any of our Open Source competitors even having a starter wizard to create a theme, but we'll take the feedback on board. A more powerful Setup/Theme Wizard is something that interests us.
Maybe none have a "Starter Wizard" (and that is certainly one of the niceties of ocP); but there are certainly other CMSs that give you a choice between some basic layouts, either overall, or per content type. That way you're not immediately thrown into editing templates if you want a different layout. I'd be really glad if you would consider something like that, to make it easier for people to accomplish an alternative layout.

Looking at the generated XHTML, I also noted that the main content area (visually between "left panel" and "right panel") actually comes after the two side panels: not good for SEO;

We'll consider changing this, but to be honest I question whether this SEO technique actually makes a real difference, and I'm not the only one (second hit on Google for "content order" seo). It would be nice to see some statistics on it.
Search engines start reading at the top, and stop after a certain number of characters (different for different engines, of course); the more navigation and other non-content like scripts are in the text stream before the actual content, the less of the content will be indexed, unless it all happens to fall within a search engine's limit. (There was some research done about that and it was pretty convincing, but I can't find a bookmark right now.) And while no one ever knows the precise algorithms, it seems that at least some search engines give more weight to text higher up on the page. And I'm not aware of any search engine that starts reading at the end of a page ;) In this context, the conclusion is simple: it certainly can't hurt to have your content first, while it may hurt to not have it first.

if there's a "jump to content" link, I haven't discovered it yet

It's right there in GLOBAL.tpl:

Code

<a accesskey="s" class="accessibility_hidden">{!SKIP_NAVIGATION}</a>
and you can see we even gave it an accesskey as per the conventional keymap (the one based on UK government guidelines that became popular).
Well, accessskeys are controversial, at least, so let's not go into that. (And yes, I'm aware of the UK guidelines but that doesn't change that fact.) I didn't find it simply because I looked for it at the top of the generated document and could not find it.

Looking in GLOBAL.tpl now, I see it comes right at the end of the main content (which comes after the branding, the top menu, the  left panel, and the right panel). It's also hidden from view by means of the class accessibility_hidden. There are two problems with this, and the major one is that it doesn't come first in the text stream, before all other navigation (and where I looked for it), so users of text browsers like lynx (yes, it is still used) can benefit from it, as it will be the first link highlighted. Not every browser supports accesskeys. The other issue is hiding it visually: "jump to content" links benefit not only screen reader users but also those who use screen magnification software, and people with motor impairments who cannot use a mouse: even if they can use the accesskey, how would they become aware of the link, or its access key, upon entering a site for the first time if the link cannot be seen right away?

Even worse, the class accessibility_hidden is styled as display: none; making it not only hidden from view in a graphical browser (normally done by positioning it outside the view port), but also hiding it quite effectively for any user of any compliant screen reader. display: none; means it's not rendered, it's simply not there. That leaves effectively only users of browsers that do not implement stylesheets (like lynx, again, but see above) - or very old screen readers - to benefit from it.


inline CSS

There's very little inline CSS. Either it's:
  • the CSS from 'nocache.css' that we need to include inline for browser compatibility (we don't use browser hacks, so we use a server-side detect and inject a small amount into the output stream based on that).
  • or it's something like "float: right" which we decided to keep out of the external sheets because it would have made the sheets extra long (harder to edit, more file size to transfer), but removing it would have not had a big impact anyway because element order also dictates floatability and thus you'd need to edit the templates to change such things anyway.
Well, we can debate what is "quite a lot" and "very little" but that will get us nowhere. It's there, and what is there is too much for me (and too much for Dutch government accessibility rules). So yes, I'd need to edit the templates and the stylesheets - that's the easy part.

inline event handlers

I know some people like to keep event handlers separate and consider it a "best practice" but I think that's a load of rubbish quite frankly. Keeping them separate adds to the complexity of the system because you can't see what is going on in-situe. It's not an accessibility problem, it's not a code complexity problem, it's not a page weight problem (explained below), it's not an SEO problem – and we couldn't change it anyway really because a modular user-editable system like ocPortal really needs to be able to output a integrated code stream because it's non-predictable (from a static JS perspective) exactly what would be used on any arbitrary screen.

inline JavaScript code

There's very little of this, and when it happens it's for a clear reason to do with either modularity or page weight. It's not good generally to include inline JS for two reasons:
  • difficult to edit (as the code is quite strewn around)
  • adds to average page weight
However those reasons are not always the case. In some situations it would add to the average page weight if relatively obscure JS code was added to the global JS. It's also very arguable that it makes things easier to edit if things are inline because they are in-situe.

because complete separation of markup, styling and scripting (XHTML, CSS, JavaScript) is one of the rules.

Frankly we can't take responsibility for silly rules. Rules that are written by people with experience developing non-CMSs are not going to work well with CMSs. Because ocPortal is modular and user-editable, static assumptions that a coder might be able to make on a static or custom developed site are not going to be applicable.
I appreciate some CMS's might work differently, but those would be basic page/article systems, which have less modules and thus can make more static assumptions.
We're obviously not going to agree on a "a load of rubbish" or "silly rules". So let's agree to disagree here.

My conclusion stands: I want XHTML without any inline CSS and without any inline event handlers or JavaScript code. That is simply a requirement. Creating a set of templates, stylesheets and JavaScript files to meet my requirements to use with ocPortal would obviously be a lot of work. I may make that effort some time, but I'm not going to make it now.

But exploring the templates, I could not find how they go together; for instance, I found HEADER.tpl, GLOBAL.tpl and FOOTER.tpl - together they seem to build the basic page structure; but I could not find any template that pulls them together. What if I want a different structure?

You would not need a different structure – any site will have a header and footer and even if it didn't (beyond the basic HTML requirements that wrap a page), you could put more into GLOBAL.tpl. Honestly, this is an imagined problem – no one has ever reported any issue like this.
Am I imagining that there is no template pulling HEADER.tpl, GLOBAL.tpl and FOOTER.tpl together? If there is one, I haven't found it.

A site may have a "header" or a "footer" but that is by no means a requirement, just a convention. I've seen plenty that don't. And I never put the the <head> element and part of the <body> element together in a single template file. OK, that's just the way I work.

But what pulls those three files together, if not a single template? I may still be missing it.

Then I found the "template tree". The problem here is, it isn't really a tree.

It is really a tree, even if some of the nodes originate from PHP constructs.
Then it's not a template tree.

and if there is a switch somewhere to add comments to do that I haven't found it yet.

Described in the documentation.
Good. So I did miss that.

I may have missed something, but it seems to me an awful lot of the code generation isn't actually driven by the templates at all, but by PHP source code.

That's simply not the case
(…) Some orders come from the code, but it's really very minimal.
Well, if there are as you say "nodes [that] originate from PHP constructs", certainly not all code generation is template-driven. And it seems right at the top level it's also PHP that puts the three main templates together (unless, again, there is a top-level template that I haven't found yet). I've worked with various templating systems, but have never come across any that mixed templates and code at that level (code inside templates is another matter - and generally discouraged).

The order of CSS includes, but you don't need to change that. If you read the Tempcode tutorial you would also see you can completely override any ordering assumptions we have made using our 'shift encoding' mechanism.
OK, I'll read that.

The major problem remains that it will be a huge amount of work to accomplish complete separation of XHTML, CSS and JavaScript in ocPortal. I may attempt that some time, but I simply don't have the time to attempt that now.

There is still a lot that I like about ocPortal, and I may even recommend it to others for certain applications (but not others). It won't drop from my radar, and I'll keep an eye on the forum. I hope you will continue to grow ocPortal, and the friendly community here!

Marjolein Katsma
follow me on identi.ca
Back to the top
 
Posted
Rating:
#49831
Avatar

Hi,

Let me address that first. I am not, in any way or form, trying to spread FUD - what I  am doing is reporting my process of analyzing ocPortal for my (possible) use, and some (major, to me) problems I encountered. And I am doing that to help you, spending quite some time to write it up (and writing this response). I could also just have dropped out but chose not to do that and share my experience instead.

I do appreciate you doing the write up, thank you, and I don't mean to say you're trying to "spread FUD". However the way you are writing is you are stating problems (flaws, inadequacies, however you like to look of it) as a matter of fact – rather than  questioning them first. You've just picked up the system and gone straght to making a number of assessments in public that simply aren't correct. Given you have some authority from your past position, that's a real problem, and quite needless really.

I found that odd, but thought maybe some common languages would be included in the install - there was only English.

Oh I see, language packs are lacking. That's true but unfortunately there's not really much we can do beyond what we already have – we've made things possible, wrote an interface, documented it, pointed people in the right direction, supported efforts, written special tools. Hopefully people will make more in the future. I really wish people released more too.

A major step in any "theming" effort (and sometimes the only one) is to create or change the color scheme. The Wizard generates a color scheme, and I'd expect its output to be in one place: either a stylesheet, or a separate section in the basic stylesheet that puts all the colors together: that way you can also change them together to make a new color scheme.

That wouldn't be good for us to do for three important reasons:
  • breaks modularity (e.g. we can't put chat system styles along with others, for good engineering, and practical global CSS weight concerns);
  • it would split things up, making it actually harder to set overall styling;
  • it would increase CSS file weight by maybe 25%

I honestly can't see a problem. It's not hard to do a search for "color" and move through the styles, or to use something like Firebug to identify where things are set.
And, the Theme Wizard has given an enormous leg up.

and not easy way that I can see to edit it all as a whole

Well, it's true that it's not a whole. You do need to edit individual templates. It is however documented and supported by tools (like the Template Tree).

None of which actually explains where the choices made in the Setup wizard are actually recorded - I found a very few in the database, but by no means all the output  of what I input in the forms.

I don't really follow why you're trying to work back to the Setup Wizard like that.
What exactly do you want to change? The Setup Wizard is just a leg-up, and you should be looking through the configuration and looking at what's in the Zone Editor, and that kind of thing. Just move through the configuration. You can find a lot from the Admin Zone search if you need specifics, generally I think it is all quite easy to locate.

isn't usable at my normal browser width of 800px.

No, the minimum width is 1024. That's been the generally accepted minimum standard for a number of years.

If it isn't fixed-width, it is at least not completely "fluid" or "elastic" (yes I know the terms are used interchangeably though they don't mean exactly the same thing).

No site is completely fluid (as soon as you set a single CSS "width", or use a long word, you introduce a slight loss in that). It's true the zone menu styles don't contract too well, which we have resolved in 4.2 - but still, we say a minimum width of 1024.

Search engines start reading at the top, and stop after a certain number of characters (different for different engines, of course);

This is where we move into the horrible world of psuedo-science that comes along with SEO. There are real SEO techniques, and SEO techniques that are years out of date, are half-truths, or had about as much truth as snake-oil.
If search engines really do have a stop limit, honestly would you say as a rational person a few kb is going to be comparable to it? Let's avoid getting into supposition – where we lack hard facts, let's use common sense and think what a reasonable search engine manafacturer is going to do taking into account they're technology has been developing for year's under enormous investment and they have a real mission to generate the best results they can.

3-column designs are difficult to implement. People always talk about the perfect 3-column design, but there's virtually always something wrong with them. Usually they do something like assume there's no footer, or assume a minimum page height, or use CSS hacks. For ours we put a lot of thought into it and tried to get something that suited most people best. An unsupported SEO claim was considered less important than other factors but if someone can show us a better way to do it without introducing new caveats – or can show good evidence this SEO claim is real – we would definitely reconsider. Or, people can choose their own layouts by editing the CSS and templates.

In summary – given a real requirement to make an engineering tradeoff, we've gone through a conscious considered process of working out the best layout we can given the facts at hand and common sense.

Looking in GLOBAL.tpl now, I see it comes right at the end of the main content

It's not at the end – it's before. Or do you mean the "main content" as the navigation?

There are two problems with this, and the major one is that it doesn't come first in the text stream, before all other navigation (and where I looked for it), so users of text browsers like lynx (yes, it is still used) can benefit from it, as it will be the first link highlighted.

I'm very surprised to see you write that – unless I am missing something fundamental, the point is to jump past all the stuff repeated on each page – especially the navigation.

The other issue is hiding it visually: "jump to content" links benefit not only screen reader users but also those who use screen magnification software, and people with motor impairments who cannot use a mouse: even if they can use the accesskey, how would they become aware of the link, or its access key, upon entering a site for the first time if the link cannot be seen right away?

Very few sites have it visual, and I think most people would say it would be extraneous and thus would get in the way (which is also an accessibility problem). However I fully support that different sites have different audiences (or even that people might not agree with our default), so by all means people should change the templates and build it into their design if they think it appropriate.

display: none; means it's not rendered, it's simply not there

This is a surprise for me to hear and I'll have to look into this. It seems very strange, seeing that "display" is a visual styling property (due to values like 'inline-block', 'table', 'list-item' etc as display properties, not semantic ones').

I would not want to incorporate a nasty hack like a negative text-indent, as that's going to create problems of it's own. What would you suggest?

It's there, and what is there is too much for me (and too much for Dutch government accessibility rules)

There's a big difference from standards for interoperability and accessibility, and programming best practice. They are very different kinds of standards and programming best practice have to be subject to design trade-off, otherwise completely nutty things will get done as a result. A good engineer has to balance competing (contradictory) marks of quality to get the best overall result.
I'd advise you spend your energies educating the Dutch government, to give them some common-sense, and stop them inflexibly lumping very different things together under an emotionally/politically-charged moniker of 'accessiblity' – rather than "jumping when they say jump".

Am I imagining that there is no template pulling HEADER.tpl, GLOBAL.tpl and FOOTER.tpl together? If there is one, I haven't found it.

A site may have a "header" or a "footer" but that is by no means a requirement, just a convention. I've seen plenty that don't. And I never put the the <head> element and part of the <body> element together in a single template file. OK, that's just the way I work.

But what pulls those three files together, if not a single template? I may still be missing it.

Any page will have a header and footer from an XHTML code perspective, as it's a fundamental requirement of the XHTML specification (from the perspective of a character stream). Even then though, it's not required in ocPortal. Don't want a visual header? Wipe out the XHTML from the template. Want 20 panels in 20 places? Program the templates to load panels in the right spot. It's all possible in Tempcode. Yes the code assumes HEADER-GLOBAL-FOOTER but that means nothing as to what you can and can't do.

Then it's not a template tree.

It's a tree with templates in – a template tree ;). Tempcode tree might be a more accurate term I admit. "Template tree" makes more sense to people though so it's the term we use.

Well, if there are as you say "nodes [that] originate from PHP constructs", certainly not all code generation is template-driven. And it seems right at the top level it's also PHP that puts the three main templates together (unless, again, there is a top-level template that I haven't found yet). I've worked with various templating systems, but have never come across any that mixed templates and code at that level (code inside templates is another matter - and generally discouraged).

The code assembles the templates, meaning we avoid having to put glue code into the templates (ala how Velocity or Smarty are commonly-used). However as I mentioned 'shift encoding' can be used to undo any of this, and move stuff around at will. We have solved all flexibility issues years ago.


Become a fan of ocPortal on Facebook or add me as a friend. Add me on on Twitter.
Was I helpful?
  • If not, please let us know how we can do better (please try and propose any bigger ideas in such a way that they are fundable and scalable).
  • If so, please let others know about ocPortal whenever you see the opportunity.
  • If my reply is too Vulcan or expressed too much in business-strategy terms, and not particularly personal, I apologise. As a company & project maintainer, time is very limited to me, so usually when I write a reply I try and make it generic advice to all readers. I'm also naturally a joined-up thinker, so I always express my thoughts in combined business and technical terms. I recognise not everyone likes that, don't let my Vulcan-thinking stop you enjoying ocPortal on fun personal projects.
  • If my response can inspire a community tutorial, that's a great way of giving back to the project as a user.
Back to the top
 
Posted
Rating:
#49835
Avatar

Fan in action

Attachment
GLOBAL.tpl as installed
» Download: GLOBAL.tpl (5 Kb, 177 downloads so far)

Chris Graham said

Hi,

Let me address that first. I am not, in any way or form, trying to spread FUD - what I am doing is reporting my process of analyzing ocPortal for my (possible) use, and some (major, to me) problems I encountered. And I am doing that to help you, spending quite some time to write it up (and writing this response). I could also just have dropped out but chose not to do that and share my experience instead.

I do appreciate you doing the write up, thank you, and I don't mean to say you're trying to "spread FUD". However the way you are writing is you are stating problems (flaws, inadequacies, however you like to look of it) as a matter of fact - rather than questioning them first. You've just picked up the system and gone straght to making a number of assessments in public that simply aren't correct. Given you have some authority from your past position, that's a real problem, and quite needless really.
No, I just described my own experience, opening with:
I'll describe below what process I went through, and try to sum up what problems I've encountered so far. I may be missing things, but I don't think I'm missing the essential things - please tell me if I am!
If that isn't clear enough I don't know what is.

None of which actually explains where the choices made in the Setup wizard are actually recorded - I found a very few in the database, but by no means all the output of what I input in the forms.

I don't really follow why you're trying to work back to the Setup Wizard like that.
What exactly do you want to change? The Setup Wizard is just a leg-up, and you should be looking through the configuration and looking at what's in the Zone Editor, and that kind of thing. Just move through the configuration. You can find a lot from the Admin Zone search if you need specifics, generally I think it is all quite easy to locate.
For you. ;)

You seem to assume all one would ever use is the Admin Zone - but I don't. I used that, and the database, and the file system and still could not find where some of the things I specified ended up. So I went through the Wizard a second time because I could not find another way to undo some of the (as it turned out) wrong choices.

isn't usable at my normal browser width of 800px.

No, the minimum width is 1024. That's been the generally accepted minimum standard for a number of years.
Especially with designers with large screens. Who are forgetting that 1) quite a few people still use smaller screens, and with mobile internet smaller screens are on the increase, and 2) that people with large screens are more likely to use non-maximized windows. I use a browser window of 800x975 (portrait mode!), so I can place two full windows side-by-side on my monitor and still have some room to spare for overlapping windows to be accessible with a single click. I know several people who (quite independently) have made exactly the same choice (with minor variation in pixel size). Firefox, out of the box, detecting a screen like my 1680x1050 installs a portrait-sized default window much like that (just 40 pixels wider). With both larger monitors and smaller handheld devices on the increase, "minimum width is 1024" is quite simply a wrong assumption.

Looking in GLOBAL.tpl now, I see it comes right at the end of the main content

It's not at the end - it's before. Or do you mean the "main content" as the navigation?
No, I mean at the end of the content: the line <a accesskey="s" class="accessibility_hidden">{!SKIP_NAVIGATION}</a> comes at the end of <div id="global_middle_ph"> which comes after both <div id="panel_left"> and <div id="panel_right"> and the chunk of the body element that is in HEADER.tpl (where it should be if it's to come before all navigation in the text stream). I'm attaching GLOBAL.tpl as installed in the default theme, untouched. See for yourself where that line is!

I'm very surprised to see you write that - unless I am missing something fundamental, the point is to jump past all the stuff repeated on each page - especially the navigation.
In order to jump past all navigation it has to come before all navigation in the text stream - it doesn't.

The other issue is hiding it visually: "jump to content" links benefit not only screen reader users but also those who use screen magnification software, and people with motor impairments who cannot use a mouse: even if they can use the accesskey, how would they become aware of the link, or its access key, upon entering a site for the first time if the link cannot be seen right away?

Very few sites have it visual, and I think most people would say it would be extraneous and thus would get in the way (which is also an accessibility problem).
Mostly those are the designer types ;) or people who simply do not understand who would benefit from that link. Sites that prominently support accessibility generally do have a visible link (like WebAIM), or one that becomes visible on hover or focus (like the WATS site). With the latter method no fancy "design" is harmed, while it still benefits all it can benefit. (Two more examples futher down with other links.) Since accessibility is about accessibility for all, there is really no reason to make this tool inaccessible to some who could benefit when it doesn't even need to have an impact on visual design for those who do not need it.

Here's a nice line-up of articles about 'skip links'.

display: none; means it's not rendered, it's simply not there

This is a surprise for me to hear and I'll have to look into this. It seems very strange, seeing that "display" is a visual styling property (due to values like 'inline-block', 'table', 'list-item' etc as display properties, not semantic ones').
I'm afraid that is still a common misunderstanding which was found in older screen readers, too, but corrected in the more recent ones.

To quote the W3C CSS2 Standard - 9.2.5 The 'display' property:
none
This value causes an element to generate no boxes in the formatting structure (i.e., the element has no effect on layout). Descendant elements do not generate any boxes either; this behavior cannot be overridden by setting the 'display' property on the descendants.

Please note that a display of 'none' does not create an invisible box; it creates no box at all. CSS includes mechanisms that enable an element to generate boxes in the formatting structure that affect formatting but are not visible themselves. Please consult the section on visibility for details.
(CSS3 is even less ambiguous but not a standard yet.)

Note this has nothing to do with "visual styling": in compliant user agents, no box is created, meaning it just will not be part of the DOM at all. (And what isn't there, should not be spoken either: compliant screen readers don't.)

I would not want to incorporate a nasty hack like a negative text-indent, as that's going to create problems of it's own. What would you suggest?
If an element really must not be visible but still accessible to screen reader and keyboard-only users, positioning outside the browser viewport is, in fact, the recommended technique; there are several ways technically to accomplish that (off the top is probably the easiest since the link would have to be at the top anyway). And it is still possible to put it into view on focus - which is something you cannot do with an element that isn't part of the DOM in the first place, as it isn't there to receive focus. An alternative would be to just change color so the link is "invisible" by using the same foreground and background color, until the element receives focus or on hover.

Here is a good article about Screen Readers and Cascading Style Sheets based on quite a bit of research how screen readers actually deal with various CSS methods to hide an element.

It's there, and what is there is too much for me (and too much for Dutch government accessibility rules)

There's a big difference from standards for interoperability and accessibility, and programming best practice. They are very different kinds of standards and programming best practice have to be subject to design trade-off, otherwise completely nutty things will get done as a result. A good engineer has to balance competing (contradictory) marks of quality to get the best overall result.
I'd advise you spend your energies educating the Dutch government, to give them some common-sense, and stop them inflexibly lumping very different things together under an emotionally/politically-charged moniker of 'accessiblity' - rather than "jumping when they say jump".
I don't know how you imagine standards are developed, but for accessibility standards "best practice" is an important element in the process. Please refrain from ridiculing our government's accessibility standards; the fact that they took not just WAI guidelines but also current best practice on board actually shows they made an honest effort to come up with the best guidelines that can be formulated now. (Current best practice is something that always evolves, and that is of course also one of the reasons we now have WCAG2: WCAG1 had been outdated for quite some time.) Quite a lot of effort and expertise went into creating the Dutch guidelines and they were widely (internationally, too) well received. See for instance The Dutch accessibility law is awesome (always visible "skip to main content" here) or The Dutch Embrace Web Standards (also with a nice "skip to content" on hover).

There is now an English version of the Dutch guidelines (of course the Dutch version is the normative one).

Any page will have a header and footer from an XHTML code perspective, as it's a fundamental requirement of the XHTML specification (from the perspective of a character stream).
Actually, "header" is a typographical concept, and has nothing to do with the <head> element in HTML which contains purely meta data. There is nothing at all in HTML that is related to "header" or "footer". In XHTML - because it's XML - all elements need to be closed, and that of course also applies to the html element, but that is something else entirely.

Even then though, it's not required in ocPortal. Don't want a visual header? Wipe out the XHTML from the template. Want 20 panels in 20 places? Program the templates to load panels in the right spot. It's all possible in Tempcode. Yes the code assumes HEADER-GLOBAL-FOOTER but that means nothing as to what you can and can't do.
I'd probably just empty out HEADER and FOOTER and use GLOBAL as the single top-level wrapper. To start with. :) But not now.

Marjolein Katsma
follow me on identi.ca
Back to the top
 
Posted
Rating:
#49837
Avatar

If that isn't clear enough I don't know what is.

Sorry if my reply is over-the-top, but I need to defend my software. Sorry for missing your qualifier, your post was quite long so I must have forgotten it by the time I got to the end.

You seem to assume all one would ever use is the Admin Zone - but I don't. I used that, and the database, and the file system and still could not find where some of the things I specified ended up. So I went through the Wizard a second time because I could not find another way to undo some of the (as it turned out) wrong choices.

I have added to our documentation TODO list to add a tutorial (or something) explaining exactly what the Setup Wizard changes. However, if there are things you can't find please let us know, as I consider this a very separate issue to the Setup Wizard (which was never intended to be a part of the ocPortal configuration mindset once it was run once). We can address such problems individually.

quite a few people still use smaller screens

We have to place our defaults in line with conventions and expectations, and where things are headed into the future.
I have no problem accepting people might want to change our defaults, but I don't think it's a fair criticism of the software. To confirm my experience about 1024x768 being the standard I did a test of 3 sites…
  • eBay
  • Amazon
  • BBC news
And all of them didn't work at much less than 1024x768 without scrollbars (I honestly only tried these 3 sites, I didn't try more that did work).

mobile internet smaller screens are on the increase

We made a team decision that the mobile direction is likely to go down the iphone zoom/pan model, rather than in the pure CSS fluid layout model. I fully accept this isn't a decision you'll like, and likely would not sit well with your site – but it's just our default, and what we thought best for general users (due to the high amount of design restriction a wide fluidity range creates). Please respect we have to base our defaults on a very wide set of considerations that do have to take in visual design norms just as much as access device considerations.
There's a lot of logic behind visual design, and it isn't just about things looking pretty. This said of course prettyness is important to many people as it provides a brand factor and is a competitive factor – so we need to take this fully into account.

Your point about Firefox's default size is interesting – I didn't know this. Nevertheless, I think I did demonstrate my point about 1024 being the de-facto standard on the big popular sites now, so all I can say is people must be coping with the scrollbars of such sites, or changing the browser window size.
I'm on a 24" monitor myself, and I tend to leave my windows as 1024x1000 or so unmaximized. I think I had 1024x768 native resolution as far back in about 1997.

I respect you like two windows side-by-side and that you won't like our defaults for this reason.

In order to jump past all navigation it has to come before all navigation in the text stream - it doesn't.

I understand now, thank you for explaining. I considered the tag to be a standard anchor mapped by keypress whilst in fact it is a pair: a link, and an anchor (anchor possibly being an ID of an existing tag). My mistake.

meaning it just will not be part of the DOM at all

I've carefully read the CSS excerpt and I do think it is ambiguous but I can see a reading of that where the formatting model described also encompasses aural properties and thus would be interpreted by a screen reader. If the screenreaders themselves got it wrong, I don't think it's a mark on a small software company who's primary market isn't accessibility to get it wrong!

I don't agree with your comment about the DOM. The DOM in JS, or any DOM browser, can certainly look under a "display: none" element – crucially, due to separation of concerns – the DOM is derived from the XML and not in any way tied to CSS. So I don't think this is to do with the DOM at all – just an interpreted synergy between visual and aural styes.

If an element really must not be visible but still accessible to screen reader and keyboard-only users, positioning outside the browser viewport is, in fact, the recommended technique; there are several ways technically to accomplish that (off the top is probably the easiest since the link would have to be at the top anyway). And it is still possible to put it into view on focus

Clearly shifting stuff out of view is a hack, and unfortunately those always tend to have negative unforeseen consequences so I would normally avoid them. However in this case as it's considered the right way to do it, and because I can only think of some very minor situations where it'd cause potential problems – we'll incorporate it as a bug fix. Thank you for explaining.

In XHTML - because it's XML - all elements need to be closed, and that of course also applies to the html element, but that is something else entirely.

Our template system is not just a mechanism to output XHTML, so our terminology isn't derived from it. It's based on text streams, and from the templating languages point of view XHTML is just a text stream (some templates arrange Comcode too).

I've had a look at those government guidelines and they are actually quite good. For example, it's not "no inline styles", it's:
Web developers should separate structure from presentation whenever possible, so using CSS for the site presentation whenever possible is strongly recommended. CSS should be placed in linked external files as much as possible.
"Strongly recommended" and "as much as possible" is very different from "must" and "never", so it provides scope for sensible engineering – like we have done. The "no inline event handlers" is not something I saw from glancing through – but if it's in there I strongly disagree with it because I could explain in great detail how essential it is for any CMS like ocPortal to have them.

I would suggest we am the perfect company to criticise guidelines like this and it's better that our thoughts are written than for me to just say "not for us" and not properly reply. As you have seen, two users came to you right away to say how much we care about accessibility, and how much better we are than other companies, so if we are finding problems in an approach or have done something a certain way, it's going to be for a reason. Frankly we should be benefiting from our hard work to meet standards, not put in a position having to publicly argue over all the individual design and engineering decisions we've made.


Become a fan of ocPortal on Facebook or add me as a friend. Add me on on Twitter.
Was I helpful?
  • If not, please let us know how we can do better (please try and propose any bigger ideas in such a way that they are fundable and scalable).
  • If so, please let others know about ocPortal whenever you see the opportunity.
  • If my reply is too Vulcan or expressed too much in business-strategy terms, and not particularly personal, I apologise. As a company & project maintainer, time is very limited to me, so usually when I write a reply I try and make it generic advice to all readers. I'm also naturally a joined-up thinker, so I always express my thoughts in combined business and technical terms. I recognise not everyone likes that, don't let my Vulcan-thinking stop you enjoying ocPortal on fun personal projects.
  • If my response can inspire a community tutorial, that's a great way of giving back to the project as a user.
Back to the top
 
Posted
Rating:
#49844
Avatar

Community saint

I have not read every thing in this thread but I will admit making themes is or can be a pain in the butt.
I get stuck a lot and the bad part about that is some people consider me an expert at making themes for ocportal. Although I may make themes for it I am no expert infact I think succerdad might be better at making themes them me.

In my opinion it could be made much easier and maybe in the css slimmed down to a half or even a forth of the entries. I know in making themes I have deleted css entries with out breaking any thing. At one time I even started making a theme where I blanked out the whole global css although that was before 4.0 came out and I did it do to having css issues with the drop down menu. I have not tested the drop down menu in 4.

Even though I love ocportal I would love to see the theming aspect of it made simpler, maybe as simple as smf, or ipb, now that would be cool.

I run http://otakuplayground.com and am hopping to make themes and other things for ocportal even though I no longer use it for otakuplayground.com I still love it and feel it could go far with the right help. It needs themes and needs people to advertise for it.
Back to the top
 
There are too many online users to list.
Control functions:

Quick reply   Contract

Your name:
Your message: