How to generate an <abbr> abbreviation element in ReST?
<abbr title="Hypertext Markup Language">HTML</abbr>
The documentation indicates that "The abbreviation element is not exposed in default restructured text. It can only be accessed through custom roles." I'm not sure how to create such a custom role, and the rest of the documentation is a tad obscure to me.
For Sphinx users, an abbreviation can be added using the :abbr: role. For example,
This :abbr:`SDP (Software Development Plan)` defines ...
results in the following HTML
<p>This <abbr title="Software Development Plan">SDP</abbr> defines …</p>
I have solved it for now by adding this at the bottom of the document:
.. |HTMLabbr| raw:: html
<abbr title="Hypertext Markup Language">HTML</abbr>
Then in the document I've used this "tag"/custom role like this:
This document is written in |HTMLabbr| and renders nicely in a modern browser.
For each abbreviation you would have to define a new custom role, I'm wondering if there is a way to have a "tag" that would take the value and the title as parameters instead of having to hard-code it like this.
Creating custom docutils rst role is not hard (compared to other ways how to extension docutils). See rst roles howto, which contains all the details along with a full implementation of example RFC role. I was able to create custom bugzilla referencing role based on this document.
Related
I have a Plone 4 site where I currently use the following method to embed objects (e.g. images, videos, tables …) in user-editable HTML content:
I have a custom transform browser which takes HTML text and transforms all a and img elements which refer to an element by UID (i.e., which have an href="…/resolveuid/abc123…" or src="…/resolveuid/abc123…").
My view templates read the text field and let that browser transform it;
the browser has a Python dict TYPE2TEMPLATE which has portal_type keys and template_id values;
for each a or img which refers to an object by UID,
the object is fetched by o = brain._unrestrictedGetObject()
the template id t_id is taken from the TYPE2TEMPLATE dict
the "embed" method is fetched by method = o.unrestrictedTraverse(t_id)
that method is called (in some cases with some keyword arguments), and the result - which is contained in one top HTML element - replaces the "raw" a or img element.
Now that I'm developing an additional customization package (which contains new object types, now using Dexterity), I wonder whether there is some more "plonish" way. Is there, for example, some embed action?
i don't know of a package that does the same and what you're doing sounds sane to me ;-)
i just would use https://pypi.python.org/pypi/plone.outputfilters instead of your transform BrowserView.
if it's possible to explicitly mark links that should not be auto-embedded (eg via span.noEmbed a.internal-link selector) this could become a useful addon.
i guess for portal_type=='File' you'll need to check the mimetype too in order to decide if you're embedding a video file or something else...
other products i know of embed content outside of your plone site (eg. collective.embedly)
another approach would be a to use a tinymce plugin to genereate the proper embed html when editing the html-body of your page (i personally would not go this route because there are different tiny versions to support for 4.3 and 5.0 and we're not sure if tiny woun't be replaced as default editor in the future)
Recently I've been reading about how you can make custom tags valid in HTML5 by putting a dash in the name, so I've been wondering what the actual rules / guidelines are for custom tags.
custom-tag √
custom X
-custom ?
custom- ?
What I want to know is if the last two are valid.
Also, as a bonus, I'm kind of curious about how custom attributes work.. as far as I know:
<div my-attribute="demo"> X
<div data-my-attribute="demo"> √
<custom-tag my-attribute="demo"> √
<custom-tag data-my-attribute="demo"> √
But what happens if I'm trying to use existing global attributes, such as title or class?
Does this CSS..
custom-tag.banana {
color: yellow;
}
target this HTML?
<custom-tag class="banana">
Test!
</custom-tag>
Also, this CSS should target the above HTML whether or not global attributes work with custom tags, correct?
custom-tag[class=banana] {
color: yellow;
}
Finally, is there a rule/guideline stating I should have a "-" in the name of my custom attribute, like custom tags? E.g. <div custom-tag="demo">. If there is, like my original question, does it work with -customtag, and customtag-?
Thanks for the help. :)
TL;DR: There are no valid custom HTML5 tags.
I think you may be referring to this Custom Element Working Draft proposed by the Web Applications Working Group, which describes this:
The custom element type identifies a custom
element interface and is a sequence of
characters that must match the NCName
production, must contain a U+002D HYPHEN-MINUS
character, and must not contain any uppercase
ASCII letters. The custom element type must not
be one of the following values:
annotation-xml
color-profile
font-face
font-face-src
font-face-uri
font-face-format
font-face-name
missing-glyph
Additionally, according to HTML5 specification, HTML tag names can only start with ASCII letters. If we assume that the Custom Element proposal does not propose any changes to the HTML Syntax specification, then elements starting with hyphens-minus character is not a valid HTML tag name. If we combine what the Custom Element Working Draft proposal and the HTML5 Syntax specification says, then we can conclude that <-custom> is not a well-formed HTML and so cannot be a valid Custom Element because the tag name does not start with ASCII letter. On the other hand, custom- is both a well-formed HTML and a valid Custom Element.
Note that Custom Element is a Working Draft, not a W3C Recommendation. This means that Custom Elements is not valid in HTML5. Don't get your hopes up either, a lot of Working Drafts that are proposed in W3C never got anywhere (and for good reasons too, not all of the proposals are good).
<rant>Personally I hope that this proposal got shot down. I spent some time reading this proposal, it looks like this proposal tried to reinvent XML Namespace and SGML poorly, and probably forgot about what HTML and the semantic web is supposed to be. In any case, HTML5 syntax already allows authors to use elements that aren't specified in HTML5 specification, I don't see any need to standardize how to create custom elements any further than that. I hope that there would be people in HTML5 working group sane enough to realize how bad this proposal is and vote this proposal off. Keep HTML5 closed from author-defined custom modifications.</rant>
If you want to define your own custom vocabularies, I suggest you should write an XML application with XHTML5, which actually specifies how you can define your own custom elements with XML namespaces. Unlike HTML, XML is designed to be extensible.
As for your question about custom data attribute, this is what the HTML5 specification says:
A custom data attribute is an attribute in no namespace whose name starts with the string "data-", has at least one character after the hyphen, is XML-compatible, and contains no uppercase ASCII letters.
So with your examples, these are valid data-* attributes:
data-my-attribute
while these are not:
my-attribute
As far as I can tell, the Custom Elements Working Draft does not specify any additional syntactical requirement for custom attributes on Custom Elements, nor does it explicitly permit using arbitrary non-data-* attributes and how custom attributes interacts with existing HTML attributes, although we can reasonably infer that allowing custom attributes is probably the intent of the proposal.
As for your question about CSS, yes you understood correctly, those are valid CSS selectors to target those Custom Elements. CSS can be used to style any elements, not just elements defined by HTML, but also other markup languages like SVG, MathML, as well as arbitrary XML vocabularies when using XHTML. The CSS Selectors specification does not actually depend on HTML vocabulary in any substantial way (although HTML is used heavily in the examples, as it's what most people are most familiar with). It is for this reason that CSS Selector syntax can be used to refer to any elements in the document, including custom elements that aren't specified in the HTML specification. Styling custom tag already works in all major browsers today. You can use any arbitrary tag names, and select them with the selector that you expect, and CSS will style them as you would expect them to be. There is no requirement for having hyphen-minus in the tag name for this to work.
To pass validation, all attributes you add that aren't available for the element by default should be prefixed with data - it has nothing to do with it containing a dash or not.
Targeting these in CSS is done by using something like element[data-attribute].
So this is valid: <div data-title="Custom Data Title"></div>,
this would not be : <div custom-title="Custom Title"></div>.
Targeting could be done by using div[data-title="Custom Data Title"]{}
Concerning tags, you are limited to the tags provided by the browser if you want your site to validate. You cannot use custom elements willy-nilly, as it increases processing of your page.
You can use javascript to require a page to recognise certain tags, but it still won't validate. This will work, but is not advised:
<script type="text/javascript">document.createElement("custom");</script>
<custom data-name="Something">Here</custom>
Theres more info here: https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Using_data_attributes
HTML5 does not have a specific doctype definition or an XML schema definition.
It is possible to create custom HTML tags (custom elements) as they can be used to create web components
Custom attributes are also valid as they can serve to supply a web component with required information
e.g.
<custom-element a="x" b="y"/>
Right now I've been implementing User Interface 2012 and after some hurdles it works just fine. I've been looking to optimise the usability of any UI-editable fields, and run into a related challenge.
Within a component there are several fields that are not mandatory, and as such should not be displayed when they are empty. As soon as an editor enters UI and selects the component holding said fields, several labels such as <add text> and <add internal link to component media> appear.
I am looking to change these labels to something more descriptive of their content, because additional html will be added to the page when a field is not empty.
For example (using Razor Mediator):
#if(Component.Fields.location != null) {
<span class="row">
<strong>Where:</strong>
<span>#RenderComponentField("location", 0)</span>
</span>
} else {
<tcdl:ComponentField name="location"></tcdl:ComponentField>
}
When the location field is empty, it just says <add text>. I would like to change that to <Add location to event>.
I've tried putting something between the tcdl-tags, but they display even when not editing in UI2012. I've been searching the SDL Live content sites but I cannot find any reference to it. Anyone have an idea?
There is no supported way for customizing placeholder text of the empty field. But you could try to write an extension, which overrides the following method:
Tridion.Web.UI.SiteEdit.ComponentField.prototype.setPlaceholderType
This method is responsible for setting up the placeholder text.
I was looking for the same when I was checking this, but I don't think that is doable easily AFAIK. I went little bit deep and found that the labels are part of resource file Tridion.Web.UI.Editors.SiteEdit.Strings.resx EmptyTextField. I did not pursue the option to fiddle with this because it would not be the supported way, nor documented and on top of it I still don't have the flexibility of adding my own text for the each field.
Back to your question, I was tossing up an idea (not necessarily answer to your question) and want to share here so the experts could provide some valuable suggestions. I did not try this option (i felt too much work) and this is in my long todo list and might have some drawbacks as well.
Create Schema Fields with "default values" (e.g; "Add location to event"). the default text will be displayed in your UI.
Write Your templates in a way that if the Schema field value is same as default
##if(Component.Fields.location.value == [Compare the schema field definition - default value of the field]) {
//--> Note: I could not find a straight API for this.. but I am assuming it should be there.
#RenderComponentField("location", 0)
} else {
<span class="row">
<strong>Where:</strong>
<span>#RenderComponentField("location", 0)</span>
</span>
}
Perform above condition check based on target type UI enabled, since we do not want to display the default text for live target etc.
Also, posting Tridion Idea as enhancement request will be great. I will do it in next few days if none exist already.
I like the approach as it'd be a quick way to give author's instructions at the field level. We use the description field to typically provide this type of help in the CME.
For inline editing, content types (SDL Live Content - login required) is another option since they define schema (and prototype component), template, instructions, and "save-to" context. You can offer dummy text that authors replace.
Tips:
Add sample content and/or instructions (Lorem Ipsum) in the prototype component.
Add additional instructions in the content type description.
Select storage location other than the prototype component's folder.
Let us know how it goes. :-)
EDIT: Would it be more elegant to tweak the GUI using CSS, or some other way?
Is there any good documentation (the official one only shows a basic example) for this tag?
I want to use it like this:
<s:decorate template="template.xhtml">
....richfaces UI...
</s:decorate>
in order to format a list of question-answer pairs without using rich tables or nested panels.
I get the gist of what it does, but I don't understand exactly how I can edit my own template.xhtml files and make the UI look as I want by using it.
The s:decorate is basically the same as ui:decorate with some extra functionality like rendered
The ui:decorate can be explained as:
The UI Decorate tag is a templating
tag that decorates content included
from another Facelet. Any content
outside of the UI Decorate tag will be
displayed by the Facelets view
handler. Any content within the
decorate tag will be passed to the
associated template as parameters or
simply ignored. You can use nested
ui:define tags to pass named content
to the associated template. See
ui:insert for more information.
For more info you can read here and here
To answer your update question. You should also use CSS to style the content of your template
I'm using reStructuredText with epydoc. How can I have the text of an internal link different than the target of the link? I have:
:todo: Figure out the `Product.manufacturer` relationship in `Product`.
The Product link looks fine and links to the Product object. The Product.manufacturer link goes to the proper member variable, but instead of the text being Product.manufacturer, I'd like to just be manufacturer.
I know this can be done if I use epytext, but we'd like to stick with reStructuredText so that we can switch documentation generators later if we want to.
I'm not familiar with epydoc myself, but the normal reStructuredText way would be this:
`manufacturer <Product.manufacturer>`_
Or, with Sphinx,
:attribute:`manufacturer <Product.manufacturer>`
Considering that epydoc seems to have overridden the default role to provide links, it will be being left to it. However, this is the most likely to work:
:todo: Figure out the `manufacturer <Product.manufacturer>` relationship in `Product`.