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.


Extending ComCode

Login / Search

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

Fan in action

Can ComCode be extended?

Hello all,

Currently I am evaluating ocPortal, initially by reading a lot of documents on the site to try to determine whether it will fit my needs.

Standards support (including Accessibility) is an important part in this. ocPortal claims WCAG and ATAG compliance - which sounds good.

But when I read through the documentation for ComCode ( http://ocportal.com/docs/tut_comcode.htm ), I note that the img tag does NOT have a parameter for alt text (which makes it automatically not ATAG-compliant *).

So I have two questions regarding ComCode:
1. Is it possible to extend a tag definition with a new parameter? (so I could add a parameter to specify the required alt tag)
2. Is it possible to define any tag parameter as required? (so I could enforce adding alt text for an image, or at least a conscious decision to specify an empty string)

Some semi-related (still ComCode) issues:
Headings: I had a hard time finding how to define headings - until I found a heading is confusingly called a "title"; there is already enough confusion between the title tag and the title attribute, so I find this choice rather unfortunate.

Other confusion was caused by lumping semantic tags like ins, del, lists, and more under "formatting" tags (they are not). But then ins and del apparently do not support parameters, so an extension would be useful here, too, to define cite and datetime for the tag to be generated.

And I was unable to find how to define paragraphs, or whether they are generated automatically (and if so, how): the word "paragraph" does not occur on the page.

_______
* Disclosure: I am an ex-member of the W3C ATAG 1.0 working group.
Supporting definition of alt text ComCode falls under priority 1 checkpoint:
1.1
Ensure that the author can produce accessible content in the markup language(s) supported by the tool ( http://www.w3.org/TR/2000/REC-ATAG10-20000203/atag10.html#check-support-access-features ).See also techniques for this checkpoint ( http://www.w3.org/TR/ATAG10-TECHS/imp1#check-support-access-features ), specifically: "Allow the addition of equivalent alternatives for all supported image formats that allow text content, including PNG, SVG, WebCGM, JPEG, and GIF."

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

Hi,

I'm very pleased and honoured to have a member of the working group here :)! It's great that you're here, it gives us the opportunity to work to get any glitches we might have resolved. We are committed to standards but of course it's very hard to make sure everything is perfectly met, so I just ask a couple of things up front:
  1. please be patient with us as we discuss things
  2. please take into account we need to keep a lot of different people happy that have different needs (i.e. we can't ask all our users to learn XHTML, semantics, and the WCAG checkpoints to write their content)

Comcode is intended as a simple language really, so isn't going to line up with the precise control and specification that XHTML can do. This is intentional by design, but also there's an "html" tag to ensure you can drop down to full control should you want to.

But when I read through the documentation for ComCode ( ocPortal Tutorial: Comcode and the attachment system - ocPortal.com ), I note that the img tag does NOT have a parameter for alt text (which makes it automatically not ATAG-compliant *).

The "param" attribute sets both alt and title. If you need more fine-grained control, you'll need to drop down to XHTML. I'll update the documentation to explain that "param" specifies alt, and be clear over what that means.

Is it possible to extend a tag definition with a new parameter? (so I could add a parameter to specify the required alt tag)

You'd need to change the PHP code to do this, but yes it is possible.
If you wanted to change it so "param" serves as just "alt" and not "title" too, you can edit the COMCODE_IMG template to do that.

Is it possible to define any tag parameter as required? (so I could enforce adding alt text for an image, or at least a conscious decision to specify an empty string)

No, but really you're trying to ensure that markup is correct, right? If you code in XHTML (using the Comcode 'html' tag), you can make use of the fact that ocPortal has a built in validator. You'll get the same precise control and strictness of XHTML (no defaulting parameters for example) and can ensure WCAG is met (including things like non-specified alt attributes). IIRC you need to enable this in the configuration but it's there and available.

Headings: I had a hard time finding how to define headings - until I found a heading is confusingly called a "title"; there is already enough confusion between the title tag and the title attribute, so I find this choice rather unfortunate.

The level 1 "title" as specified in Comcode contributes both to the "title" tag and to the h1 tag. As before, Comcode is all about making things very simple – generally we try and make things default sensibly. IMO people most relate to "title" more than "heading", but it probably varies to be honest.

Other confusion was caused by lumping semantic tags like ins, del, lists, and more under "formatting" tags (they are not). But then ins and del apparently do not support parameters, so an extension would be useful here, too, to define cite and datetime for the tag to be generated.

Primarily the documentation is for the average user who isn't going to want to learn about XHTML semantics, or write CSS to do their styling. Generally when people use the tags for formatting the semantics come along with it, but they're thinking of it as "formatting". I know that's not always the case, but we do have to design for the average user. The key thing is the semantic intent is easily achievable by those with a firm understanding.
I wasn't actually aware of the 'cite' and 'datetime' parameters, so we'll consider adding these for a future version :). I'll also put through the idea of a new "title" parameter to the "img" tag, to allow finer specification.

And I was unable to find how to define paragraphs, or whether they are generated automatically (and if so, how): the word "paragraph" does not occur on the page.

Comcode does not generate paragraphs, it uses line breaks. The reason is there's no solid/efficient way to convert human-readable text like Comcode to sometimes be split up with breaks and sometimes paragraphs. This is a case where you might want to drop down to XHTML. I'm not aware of any real accessibility problems that come through breaks, although I do appreciate the semantics are not equivalent. Please let me know if there are any serious problems with our approach.


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:
#49767
Avatar

Fan in action

Chris Graham said

Hi,

I'm very pleased and honoured to have a member of the working group here :)!
"Ex"! (Alas - I had to stop when I was laid off and thus no longer had a sponsor.)

Chris Graham said

It's great that you're here, it gives us the opportunity to work to get any glitches we might have resolved. We are committed to standards but of course it's very hard to make sure everything is perfectly met, so I just ask a couple of things up front:
  1. please be patient with us as we discuss things
  2. please take into account we need to keep a lot of different people happy that have different needs (i.e. we can't ask all our users to learn XHTML, semantics, and the WCAG checkpoints to write their content)
I'll be patient. :) And, it's never possible to accomplish 100% accessibility, one always has to take the audience into account. What attracted me to ocPortal was that you obviously care about standards and accessibility - that's one part of evangelism I won't need to exercise here. :)

Chris Graham said

Comcode is intended as a simple language really, so isn't going to line up with the precise control and specification that XHTML can do. This is intentional by design, but also there's an "html" tag to ensure you can drop down to full control should you want to.
Sure. Just be aware that if you want to comply with ATAG, it has to be possible to use Comcode in such a way that the code generated by it complies with WCAG. I was aware you can drop down to XHTML, so it's a borderline case; I'd say being able to drop down to XHTML is an "escape" for a knowledgeable author, but doesn't really support a less-knowledgeable one to produce accessible code. ATAG guidelines are not just for authors that know how to write (X)HTML, but also (and more so) for authoring tools that support authoring without ever exposing the author to (X)HTML itself.

Chris Graham said

But when I read through the documentation for ComCode ( ocPortal Tutorial: Comcode and the attachment system - ocPortal.com ), I note that the img tag does NOT have a parameter for alt text (which makes it automatically not ATAG-compliant *).

The "param" attribute sets both alt and title. If you need more fine-grained control, you'll need to drop down to XHTML. I'll update the documentation to explain that "param" specifies alt, and be clear over what that means.
Here's an important idea: the function of the alt attribute and the title attribute are very different. Alt text is intended to replace an image (or other element that requires an alt attribute) when it cannot be seen. The function of the title attribute is to provide extra information about an element. Think about it: in general, alt and title text should not be the same!

So, while it is excellent that the Comcode param attribute can provide the alt text, it should not at the same time generate title text. It would be better to have a separate attribute to be able to set a title, and only where needed.

The current description for the param attribute for the Comcode img tag reads: "the image mouse-over caption Supports Comcode." This suggests it sets the title attribute, and nothing else - never mind that Internet Explorer used to produce a tooltip for an alt attribute: that is a bug! and never mind that a tooltip isn't the only way to present a title text: there are other ways, such as displaying the text on a status bar, or making it available only on request.

Anyway, it would be nice to have a generic title attribute for all Comcode tags (rather, those that correspond to XHTML tags).

I also note that the url tag does have a title attribute (described as "tooltip" which I can live with even though not technically correct :)). But combine that with an image for an image link, and the automatic creation of alt=title on the image would lead to a potential conflict. Best practice is to use alt on the image as the link text you would write if it were a text link, and use a title attribute on the a tag to provide extra information about the target; in this scenario a title attribute on the link text (read: image al text) is superfluous.

I hope that makes it clear why param on img should not generate title text at the same time (and with the same text) as the alt text.

Chris Graham said

Is it possible to extend a tag definition with a new parameter? (so I could add a parameter to specify the required alt tag)

You'd need to change the PHP code to do this, but yes it is possible.
If you wanted to change it so "param" serves as just "alt" and not "title" too, you can edit the COMCODE_IMG template to do that.
Excellent. As long as I can find which PHP code to adapt I can handle that. But it would be great if you could take my suggestion on board!

Chris Graham said

Is it possible to define any tag parameter as required? (so I could enforce adding alt text for an image, or at least a conscious decision to specify an empty string)

No, but really you're trying to ensure that markup is correct, right? If you code in XHTML (using the Comcode 'html' tag), you can make use of the fact that ocPortal has a built in validator. You'll get the same precise control and strictness of XHTML (no defaulting parameters for example) and can ensure WCAG is met (including things like non-specified alt attributes). IIRC you need to enable this in the configuration but it's there and available.
OK. But see my remarks about ATAG: this is more about the spirit than the letter, but that's what all the accessibility guidelines are! My take is: If you have a means to generate XHTML, then that means (in this case Comcode) should be capable of generating accessible XHTML - Comcode is there, after all, because you're intending to support authors who do not know enough to fall back to XHTML. (I could, for my own site, but I could not expect commenters or forum members to do that.)

So… what happens if one does not specify a param attribute? If I do that deliberately, and ocPortal generates an alt attribute with an empty string, we're OK. If instead it doesn't generate an alt attribute at all, we get invalid code (and the HTML requirement is there for accessibility reasons in the first place). And what happens if one specifies an empty param attribute? If that results in an empty alt attribute, we have a valid mechanism (and it would not be necessary (for img) to make the param attribute required). (BTW, an empty alt attribute is valid and useful, an empty title attribute has no use at all - another reason to separate them.)

Chris Graham said

Headings: I had a hard time finding how to define headings - until I found a heading is confusingly called a "title"; there is already enough confusion between the title tag and the title attribute, so I find this choice rather unfortunate.

The level 1 "title" as specified in Comcode contributes both to the "title" tag and to the h1 tag. As before, Comcode is all about making things very simple - generally we try and make things default sensibly. IMO people most relate to "title" more than "heading", but it probably varies to be honest.
I've been a long-time member of the Desktop Publishing Forum (which deals not just with desktop publishing but also website development), and years before that the INETPUB forum on Compuserve (until it folded and most of its core members fled to and were welcomed in the DTP forum). In our experience, it doesn't hurt to use the "correct" terms - it prevents confusion down the line. Thus we use "alt attribute" and not "alt tag" and make a clear distinction between "title attribute" and "title tag". Gently educating people to use correct terminology empowers them to find relevant information elsewhere, and not confuse them at that point. And I've never met anyone who didn't understand "heading" or "header" when used in context.

(I do hope that the h1 "title" tag contributes to the document title rather than setting it, but I assume this will be configurable somewhere.)

Chris Graham said

Other confusion was caused by lumping semantic tags like ins, del, lists, and more under "formatting" tags (they are not). But then ins and del apparently do not support parameters, so an extension would be useful here, too, to define cite and datetime for the tag to be generated.

Primarily the documentation is for the average user who isn't going to want to learn about XHTML semantics, or write CSS to do their styling. Generally when people use the tags for formatting the semantics come along with it, but they're thinking of it as "formatting". I know that's not always the case, but we do have to design for the average user. The key thing is the semantic intent is easily achievable by those with a firm understanding.
Fair enough - but the "gentle education" would apply here, too. Put it in the right section, and you can at least suggest the idea that a list is not about appearance, but about document structure.

(So what about all the presentation-related tags and attributes in Comcode? Is CSS generated?)

Chris Graham said

I wasn't actually aware of the 'cite' and 'datetime' parameters, so we'll consider adding these for a future version :).
Maybe a little excursion to w3.org? ;)


Chris Graham said

I'll also put through the idea of a new "title" parameter to the "img" tag, to allow finer specification.
Great!

Chris Graham said

And I was unable to find how to define paragraphs, or whether they are generated automatically (and if so, how): the word "paragraph" does not occur on the page.

Comcode does not generate paragraphs, it uses line breaks. The reason is there's no solid/efficient way to convert human-readable text like Comcode to sometimes be split up with breaks and sometimes paragraphs. This is a case where you might want to drop down to XHTML. I'm not aware of any real accessibility problems that come through breaks, although I do appreciate the semantics are not equivalent. Please let me know if there are any serious problems with our approach.
This is indeed a problem.

Paragraphs are important for several reasons. Primarily, because a document structure is built from headings and paragraphs (and you cannot have "bare" text within a body tag: simplifying a bit, it essentially requires block content). by default, this has presentation consequences in browsers (even text browsers), too. Search engines also take document structure into account.

But paragraphs are also important for accessibility, as they provide "hooks" for in-page navigation in many screen readers: the screen reader user can quickly "scan" a document by jumping from one heading to another and from one paragraph to another to get to the section they want to read. Take away paragraphs and use only line breaks to (hopefully, but not necessarily) create "whitespace", and a document becomes much harder and slower to navigate for screen reader users. (Imagine having to read out aloud nine paragraphs completely just to be able to get at the tenth.)

I fully realize it's not easy to reliably generate paragraphs, but it is possible. Markdown does an admirable job in this respect (and you may be able to at least be inspired by the code: it is Open Source, after all. ;))

Maybe I should look into integrating Markdown - or did someone already do that? :)

Now, was I patient enough? If not, tell me! I don't want to work against you - I'd much rather work with you!

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

Thanks for the comments, we'll take them on board :).

So… what happens if one does not specify a param attribute? If I do that deliberately, and ocPortal generates an alt attribute with an empty string, we're OK. If instead it doesn't generate an alt attribute at all, we get invalid code

Right, it will put in an empty alt if no param is specified, which of course is not always accessible.

an empty title attribute has no use at all - another reason to separate them.)

I'm afraid practically it does, to squash IE from turning alt into a tooltip.

(I do hope that the h1 "title" tag contributes to the document title rather than setting it, but I assume this will be configurable somewhere.)

It contributes, and how it comes together can be changed in the HEADER template.

(So what about all the presentation-related tags and attributes in Comcode? Is CSS generated?)

Either inline CSS, or references to existing CSS classes.


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:
#49771
Avatar

Fan in action

Chris Graham said

Thanks for the comments, we'll take them on board :).
Great!


Chris Graham said

an empty title attribute has no use at all - another reason to separate them.)

I'm afraid practically it does, to squash IE from turning alt into a tooltip.
Oh, that. ;) I'm afraid it's a looooong time ago since I've done that! You just gave another good reason to specify title separately from alt attribute. :p But I was speaking semantically, of course.

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

Honoured member

Hello OpenSite, Welcome to the OCP forums.  I'm not a member of staff, but did want to comment on your post.

Accessibility is also what drew me to OCP, but probably not for the same reason it did you.  You see, I am totally blind, and finding an accessible web app has been a nightmare to me for years. I must say I have found a home at OCP. I've not been a member of any working group, or sat on the commission to decide what constitutes accessible and what doesn't, but I have been designing my own websites since 1996, and feel that I've pretty well learned over the years about accessibility.  I can tell you this.  The staff at OCP does indeed take accessibility serious, and on top of that they really care how their product performs, and about the people that use it.

  Chris, Alan and the Staff have been a GOD send to me personally, and I want to welcome you to our mist, and I personally look forward to reading your post with much interest.
Back to the top
 
Posted
Rating:
#49782
Avatar

Fan in action

chipster said

Hello OpenSite, Welcome to the OCP forums.  I'm not a member of staff, but did want to comment on your post.
Thank you for the welcome, chipster!

chipster said

Accessibility is also what drew me to OCP, but probably not for the same reason it did you.  You see, I am totally blind, and finding an accessible web app has been a nightmare to me for years. I must say I have found a home at OCP. I've not been a member of any working group, or sat on the commission to decide what constitutes accessible and what doesn't, but I have been designing my own websites since 1996, and feel that I've pretty well learned over the years about accessibility.
I can well imagine it's a nightmare! Far too many web apps don't even care about valid code, let alone accessibility. Though sometimes with a clean and simple (admin) user interface they can get at least close.

Yet so much could be gained with a CMS that conforms to ATAG so it's not only accessible to its user but what you produce with it can be easily accessible as well. After all, most web sites are produced with some sort of CMS!

Did you read this article on Juicy Studio? Choosing an Accessible CMS. Although it's exactly 2 years old now (and ocP was not in the list of CMSs reviewed), I found it a real eye opener. The CMSs were evaluated from a purely practical point of view, both by a screen reader user, and evaluated for general usability. (Part of the aim of the ATAG working group was to evaluate packages "formally", going through the whole checklist. But it's a big job doing that even for a single app - maybe there should be a separate group for this. It would be really interesting to see how well a formal evaluation would match the experience of the users in the Juicy Studio evaluations.)

chipster said

I can tell you this.  The staff at OCP does indeed take accessibility serious, and on top of that they really care how their product performs, and about the people that use it.

  Chris, Alan and the Staff have been a GOD send to me personally, and I want to welcome you to our mist, and I personally look forward to reading your post with much interest.
I really appreciate your jumping in here - this is great to hear. Thank you!

Marjolein Katsma
follow me on identi.ca
Back to the top
 
1 guests and 0 members have just viewed this: None
Control functions:

Quick reply   Contract

Your name:
Your message: