Last month I read about Headless CMS for the first time, and I just felt in loved with that approach.
But just right after, I wondered how could I format and/or add style to the content if some day I worked with this technology.
By styling the content, I mean words within a title, paragraph and so on; not a whole paragraph, which is quite obvious it can be done.
It seems to me that it is impossible, since you only get a JSON with no HTML whatsoever; just raw texts. So it looks like this is the major downside of consuming content through a Headless CMS from a Front End perspective.
Formatting text is just fundamental, specially when dealing with large content. And I am sure I cannot be the first one concerned about not being able to add some bold and/or italics to a text to emphasize the important parts of it.
But I can't find any website discussing this topic, just "how to model the content" and whatnot.
Does really no one care about it?
I would appreciate if anyone could shed some light about this question.
Diving into the Headless CMS #RicoHancock has pointed out, I've learnt that it is completely feasible to store rich text and strucuted content within a JSON that can be converted to HTML following some specifications I wasn't aware of.
In the particular case of DatoCMS, they use a specification called dast.
To learn more about it, visit their docs (the following link contains very illustrative code examples):
https://www.datocms.com/docs/structured-text/dast
Paraphrasing their own words:
Structured Text format adheres to the Unified collective, which offers a big ecosystem of utilities to parse, transform, manipulate, convert and serialize content of any kind.
The "Unified collective" is a collective of free and open source packages to work with content as structured data with plugins. In order to create the syntax trees, Unified uses UNIST nodes.
UNIST is a specification, and stands for "UNiversal Syntax Tree".
More info about the UNIST spec and the Unified ecosystem:
https://github.com/syntax-tree/unist
https://unifiedjs.com/learn/guide/introduction-to-unified/
https://unifiedjs.com/learn/guide/using-unified/
TLDR: Markdown.
The company I work for uses DatoCMS. We have a blog, and each blog post is created in our CMS by our copywriting team. DatoCMS allows us (the developers) to create "blocks" that make up the blog post. We have image blocks and content blocks that are rendered by a template file on our frontend. The content blocks support Markdown, so italics, bold, and links work. When our copywriting/marketing team want to make a new blog post, they go to the CMS, create a new post, add a title, slug, and blocks, and then save.
I don't have much experience with other Headless CMS', so not sure if Markdown will work there, but I don't know why it wouldn't, Markdown is all over the internet. (In fact, this answer is Markdown XD)
Related
Got a site with powerpoint presentations that the client wants embedded, the embedding is being done via google docs embed. I have been doing some accessibility testing, albeit not particularly in-depth but even with OS X screen reader it is not having any luck reading the slides. (I am aware slides are probably terrible for accessibility anyway). I can get the text content of the slides stripped out via the Google API, but I don't know if thats the best thing, to include it on the page below/above the iframe embed with one of the CSS tricks for hiding it from normal view?
I am aware of iframe title and aria-label but those seem to imply they are only to describe the contents of the iframe, which I am doing, but I need somewhere that can contain more text.
Has anyone got any good tips for the best way to deal with such things? Thanks!!
Embedding rich 3rd-party content in web pages poses many challenges.
When we put something like this in a web page, we typically think we're adding a bit of "content", but it often amounts to embedding a complex application; and the user interface, semantics, and presentation are outside of our control. In your case it's a presentation slide deck, but it could also be a Flash/Silverlight/Java applet, a slippy map, interactive SVG infographic, a 3D-panorama, virtual tour, zoomable image, chemical molecule viewer, or who-knows-what. (Note: I'm not familiar with the Google docs embed/API specifically, so most parts of my answer will address these rich content cases in general.)
Even if the embedded rich 3rd-party content/application is accessible today, there's no guarantee it will remain so after the 3rd-party system gets an update.
So what can you do? The safest thing might be to assume it's inaccessible, and consider the best way to provide an accessible alternative. The Web Content Accessibility Guidelines (WCAG) calls this a "conforming alternate version", and it sounds like you're already thinking along these lines.
An important caveat to all of this, is that the use of "conforming alternate versions" isn't considered ideal by many accessibility specialists. It's greatly preferred to make your main content accessible as you can.
Some relevant parts of WCAG:
Understanding conformance, especially the section about "Understanding Conforming Alternate Versions".
Technique G190: Providing a link adjacent to or associated with a non-conforming object that links to a conforming alternate version.
F19: Failure of Conformance Requirement 1 due to not providing a method for the user to find the alternative conforming version of a non-conforming Web page.
It's worth mentioning the 3rd-party content in your website's accessibility statement. Statement of Partial Conformance - Third Party Content offers guidance about that.
The crucial thing about conforming alternate versions, is that it's no use at all if the user isn't made aware of it, or isn't able to reach it.
Implementation-wise, there are a variety of approaches you might take. In many ways, providing an alternative for embedded rich content is similar to providing a long description of a complex image, or a transcript of a video. Have a look at these WAI tutorials for some ideas.
Web Accessibility Tutorials: Complex Images
Making Audio and Video Media Accessible: Where to Put Transcripts
I can get the text content of the slides stripped out via the Google API
It sounds like you're trying to automate the process. That's fine, but it might not give satisfactory results. Some things you should consider:
Is the text content alone going to be enough? Presentations often have images too. Did the author provide text alternatives for these images, and are they present in the text extracted via the API? If the author hasn't provided text alternatives for images in the slide deck, the text you get from the API won't be telling the whole story.
Not all text in slides carries the same weight. Some slides serve to introduce sections, some slides have headings. Does the text obtained from the API convey these relationships?
Lists are very commonly found in presentation. Does the text obtained from the API preserve this structure?
Slides sometimes contain links. Are these included in the text obtained from the API, so the links are available to everybody using the alternative version?
Slides sometimes contain tables and charts. How will the information in these be conveyed in your alterative version? Is the information included in the text obtained from the API?
Sometimes, presentation decks also contain rich 3rd-party embedded content themselves! A slide containing a video, or an animated GIF are examples of this. If so, you can find yourself with a much more complex challenge.
... and many other meaningful info and relationships. Quotations, code samples, etc.
If any of the above points give cause for concern, you will need to consider managing your alternative version manually.
The "conforming alternative version" has to conform to WCAG; if you just offer a choice of two non-conforming version, that doesn't satisfy WCAG.
include it on the page below/above the iframe embed with one of the CSS tricks for hiding it from normal view?
No, I wouldn't recommend that. I assume you're refering to visually-hidden text, using CSS utility classes such as .visually-hidden or .sr-only. It sounds like you're only thinking about screen reader users.
You need to offer the alternative version available to everybody, not just one group of users who you think will need it.
Many groups of users may experience difficulty using the rich 3rd-party embedded content. This includes people using the keyboard only, screen readers, magnifiers, speech control, switch access, or other tools. The conforming alternative version can be navigated like a normal web page though.
The 3rd-party content likely has a different visual style, and it may not be adaptable in the same way as the page it is embedded in. That can frustrate people who make use of browser zooming, text resizing, font preferences, reader mode, Windows high-contrast themes, viewport resizing, and other user-applied presentation changes. The conforming alternate version should be as adaptable as the rest of your site.
Rather than hiding the alternative version in a visually-hidden container, here are some other ways to present it. The first two are the simplest and most reliable.
Put it on the same page, just after the original content, visible to everybody.
Put it in a collapsible disclosure element just after the embedded content. A <details> element is an easy way to achieve this. This is useful if the alternative version is quite long.
Put it elsewhere on the same page, and tell users where to find it. An internal link can help here.
Put it on a separate page, with a link next to the embedded content. I'm less keen on this approach. Only use it if you can commit to maintaining both pages.
Provide a way for users to switch between the two versions. For example some buttons, or a tabbed UI. However, you must also ensure that the switching mechanism is accessible. That might mean a full-blown ARIA tabs implementation.
I am aware of iframe title and aria-label but those seem to imply they are only to describe the contents of the iframe
Giving the iFrame a useful name is important. It's also a useful mechanism to inform screen reader users that an alternative version is available. The WAI Complex Images tutorial linked above has some similar approaches. Example: <iframe title="Google Slides Presentation of FOO BAR BAZ. Link to text version follows this frame.">. This only helps screen reader users though; you still need to make the availability of the alternative version clear to everyone.
How committed are you to using Google Docs for displaying these slides?
Any accessibility enhancements that you'll be able to implement on Google Slides won't be very good.
One way around this whole thing is to offer PDF versions of the slides that have been fully-remediated for accessibility instead of using Google Slides. That would potentially be a single solution that could be accessible to all visitors. Going this route means that you wouldn't have multiple copies of the same slides to update, which could lead to a split in content if one gets updated and the other is forgotten.
If you're really set on having the slides embedded in the page, then you could offer both formats by applying aria-hidden to the embedded iframe and then hiding the PDF links from sighted users using CSS clip, or by positioning content off-screen.
I am a user, not a programmer, whose forthcoming new website on Plone 4 requires adding hyperlinks inside the Description field of pages and folders. This is needed to point specific words to our website Dictionary as we had been doing on EZ Publish for the last 10 years.
Our developer says this can't be done in Plone. I'm looking to help them find how to do this (they don't seem to use English-language forums).
Is there an existing add-on or existing code for this? If not, is it possible to code this in? How? If not, will it become standard in Plone 5?
<a href="http://python.org>Python</a> will not work, as the description-field is ment and used as a meta-information of an item, holding plain-text only, and doesn't allow the usage of html-elements, nor embedded Javascript. That's probably why T. K. Nguyen recommends to provide an additional rich-text-field.
But you can use reStrucuredText instead. Tell your developer to exchange the description-snippet in concerned templates to:
<div tal:define="Std modules/Products.PythonScripts/standard;
restructured_text nocall: Std/restructured_text;"
tal:content="structure python: restructured_text(context.Description())">
</div>
It will transform any word starting with 'http:' or 'https:' to a link, furthermore will also recognize mail-addresses like 'someone#plone.org' and transform them to mail-links (on click opens the user's default mail-client, if available, with the address pre-populated in the 'To'-field).
If you want to have named links, use the reStrucutredText-syntax for the input, like this:
`Check out Python`_, you'll love it.
`Write a mail`_ to someone.
.. _Python: http://www.python.org
.. _Write a mail: someone#example.org
The tricky part is to figure out, which templates are affected, but it's doable of my experience (did it with preserving line-breaks in listing-views, not reStructuredText).
Alternatively use a JS-workaround, as proposed by T. K. Nguyen. Be aware though, that it may break accessibility to some users.
It is possible to customize the description fields to be rich text (HTML) instead of plain text, but it requires a developer.
You can also use JavaScript to look at a description field and replace (for example) any string that starts with "http" with a hyperlink pointing to that URL. Your developer would have to look for examples of such JavaScript code and then would have to know how to register it on your site and then invoke it.
This describes how to do something similar, for PloneFormGen field help text (which is also plain text):
https://designinterventionsystems.com/blog/how-to-make-urls-clickable-in-ploneformgen-field-help-text
It might be easier to have your developer create a new rich-text description field and have all your content types include that new field. That, however, would require that you update the view templates for those modified content types. This is much easier with Dexterity, which ships with Plone 5 and is available for use with Plone 4.x.
imho it's a really bad idea to convert the description field to any richttext (html, rst, md) field. You need to change a hole bunch of templates to avoid html code rendered everywhere.
Example:
search
collections
content
portlets
Addons
The description is also often used as title attribute on links, in those cases you need to convert it to plain/text. And there are several more issues, where you could ran into.
As #T. Kim Nguyen wrote: Consider add a new textfield and show it, where necessary, probably implemented as a Viewlet in the below title slot.
Looking at your current site, it seems like you want this to provide a teaser for each article, which may contain links. If that is the case, then you can find other ways to do this without making the description html.
For instance, if you used collective.cover for your portal/collection pages then a Rich Text Tile would allow you to cut down the the object text to an appropriate size, but still edit it with a Rich Text editor, and keep/insert hyperlinks.
I have posted this question to the plone user mailing list as well, so I hope nobody minds that, especially since it is nothing I have hidden.
Since my question is hard to put into a generic question, I'll try to explain it with a (hopefully) illustrative example. Please bear with me on this one.
Content Type: Product
Each product shall have several explanatory sections with a title and a rich text as the section contents. Said title should be either taken from a listen of predefined titles (by the editor) or entered freely once (the exception).
Since the site will use Dexterity and requires a multilingual approach (plone.app.multilingual), centralizing the titles saves the translators some headaches and avoids unnecessary duplicates. Also in general, the styling is done through Diazo, so the sections will be mapped on a nice widget.
My problem is, how to map this onto Plone with usability for the editors and translators as well as efficiency for the software stack in mind.
Approach 1
Put the titles in a hidden folder and use a vocabulary in the Product content type. Also make the Product a folderish content type and require the editors to enter each section as a separate item into said folder (e.g. ProductSection non-folderish content type). Repeating that process for each product. But this seems not very user friendly and imho would not scale very well with the number of products and sections.
Approach 2
I could naturally also reduce the Product content type in general to just one single rich text field and have the user enter each section as a div block with a headline and a paragraph. Even though this is the easier way to implement this, it puts the burden on the translators (many duplicate translations) and on the editors (e.g. changing a title for marketing or whatever, requires changing it manually through all products etc.).
Again, please remember this is an illustrative example of my problem and here Product is really that, a product from a company's portfolio and not a Plone add-on. ;)
So my question basically boils down to this: Which approach sounds more reasonable? Or is there a more standard and/or creative way to solve this problem?
Thanks a lot for any suggestions and help in advance. It is very much appreciated...
UPDATE
After I received a very enlightening answer on the plone users list, my current thinking (untested, brainstorming) is as follows:
Product will be a custom form (due to MultiWidget, see below)
the section blocks will be saved in a list on the Product object (titles will be a choice field only)
the section titles will be saved elsewhere and manageable through different means (needs to be accessible by a Site Administrator, so anything ZMI is out of the question)
easy editing through z3c.form's MultiWidget (that's the key ingredient, actually)
If this works out and plays nicely with Dexterity and multilingual, I guess that's quite the optimal solution for everyone involved.
Naturally I'd appreciate any and all kinds of comments or suggestions. Maybe I am totally on the wrong track now but based on what I read up, this should actually work fine.
I need to collect data from a visitor in an HTML form and then have them print a document with the appropriate fields pre-populated. They'll need to have a couple of signatures on the document, so it has to be printed.
The paper form already exists, so one idea was to scan it in, with nothing filled out, as an image. I would then have the HTML form data print out using CSS for positioning and using the blank scanned form as a background image.
A better option, I would think, would be to automatically generate the PDF with this data, but I'm not sure how to accomplish either.
Suggestions and ideas would be greatly appreciated! =)
I would have to respectfully disagree with Osvaldo. Using CSS to align on a printed document would take ages to do efficiently in the aspect of cross-browser integration. Plus, if Microsoft comes out with a new browser, you're going to have to constantly update for the new use in browsers.
If you know any PHP (Which, if you know JavaScript and HTML, basic PHP is very simple), here's a good library you can use, FDPF:
Thankfully, PHP doesn't deprecate a whole lot of methods and the total code is less than 10 lines if you have to go in and change things around.
You can control printed documents acceptably well with CSS, so I would suggest you to try that option first. Because it's easier.
This is actually a great php library for converting HTML to PDF documents http://code.google.com/p/dompdf/ there are many demo's available on the site
XSL-FO is what I would recommend. XSL-FO (along with XSLT and XPath) is a sub-standard of XSL that was designed to be an abstract representation of a formatted document (that contains, text, graphic elements, fonts, styles, etc).
XSL-FO documents are valid xml documents, and there exist tools and apis that allow you to convert an XSL-FO documet to MS Word, PDF, RTF, etc. Depending on the technology you use, a quick google search will tell you what is available.
Here are a few links to help you get started with XSL-FO:
http://en.wikipedia.org/wiki/XSL_Formatting_Objects
http://www.w3schools.com/xslfo/xslfo_intro.asp
http://www.w3.org/TR/xsl11/
Suppose you're developing a web site and blind users will be a significant chunk of your target market. If the web site includes document editing functionality, what would be appropriate WYSIWYM tools? Are languages like Markdown, Textile and Wiki Formatting really accessible or are they inconvenient to blind users?
I'm a blind programmer and while I haven't used most of the languages you mention I've found that any markdown language is fairly easy to use if you have the desire to learn it. I've had no problem using either HTML or several markup languages for wiki's. Part of it will depend on how invested the users are in your site. If it's a site that will be visited infrequently or for short periods of time, it's much less likely that a user will take the time to learn the required markup whether they are blind or not. Unfortunately, I have not found an accessible JavaScript WYSIWYG editor but I find it easier to manually enter the markup so haven't looked very hard.
the first question is: how important is semantic structure? could you get away with plain text. You could do simple parsing like treating blank lines as paragraph markers, treating a series of lines which begin with * as a bulleted list, identify URLs and make them into links, etc.
As a blind developer myself, I have no problem in understanding languages like Markdown. But if it's a syntax I'm unfamiliar with, I'll only learn it if I expect to use the site very often, or care deeply about the content.
Two final thoughts come to mind: while I certainly experience some accessibility challenges using TinyMCE, you could develop something much simpler - provide less than 10 formatting options, like inserting hyperlinks, making lists, centering text, setting the style (such as heading) etc.
And lastly, when I talk to non-technical blind people, they often just write their content in Word and paste into a wiki or blog post. This sounded strange when I first heard it, but it does make sense. So an ideal solution would accept pasted in content.
In closing - it depends how important this is, and how much effort you want to expend. Maybe a Markdown editor with a live preview (like on this site), buttons for inserting simple formatting like URLs, and the ability to paste in rich text would tick all boxes :-)
On a web page, the most accessible embedded text editor for blind users is one that uses standard HTML, such as a <textarea> element, with a corresponding <label> element:
<label for="editor">Enter your text here using wiki markup:</label>
<textarea id="editor"></textarea>
If a WYSIWYM tool is built using standard accessible HTML, then blind users can easily enter text into it, with full confidence that they're entering text in the right place. Then the question becomes: Which is the better markup language? They all require memorization, but some may be more intuitive than others. One way to find out which is best would be to do some usability testing with a wide variety of target users. Also be sure to providing easy, accessible access to syntax help.
Picture yourself working in pure text 80x4 display (just open a console and resize appropriately), then use vi/emacs/ed and you'll soon realize what markup will get in the way.
Try to do as much work as possible to understand plain text, else use light markup like POD, finally things like AsciiDoc are very powerful but needs training.
I don't know about WYSIWYG/WYSIWYM tools, but I do know that complying with W3C standards (especially their HTML5 en CSS3 drafts) while writing your own editor code will help a lot.
In CSS you can specify speed and intonation of speech. In HTML you can specify alternative text (alt attribute in many elements) that screen readers are compatible with. Be sure to know when to use the abbr and the acronym elements. Use the former when you want the screen reader to read the meaning of an abbreviation and the latter when the acronym should be read as a word (e.g. ASAP, NATO and OS).
For the editor itself, I recommend creating a WYSIWYG editor that uses divs and spans. Screen readers will understand easily the structure of a document. For the current line, use a text box; for every other line that's not being edited, convert the contents immediately to valid HTML.
If you find a good tool, be sure to post it here. I'm looking for one too. :-)