Elegant code annotation for tutorials? - jquery-ui

I've been writing some tutorials, and I'm trying to figure out an elegant way to add line-by-line annotations to the code in the tutorials.
For example, suppose I have some code like this:
<h1>Demo of web page</h1>
<p>This is a paragraph</p>
I'd like to be able to add something (maybe a tooltip or some kind of lightbox effect) that allows me to present an explanation of each line to the reader, while still letting them see the line in context. The best I've been able to come up with is prose explanations that say things like "The line that starts with <h1> is a headline."
Anyone ever seen something like this?

You might want to check out docco:
http://jashkenas.github.com/docco/
It's written in CoffeeScript and generates an HTML doc from a source file breaking up the comment sections and the code. It sets up the comments as annotations for each section in one column and the corresponding properly highlighted code in the other column. I think it's a great simple way to grok annotations while keeping the code in context. Oh, and it also knows markdown.

What about using title attributes?
<h1 title="your hover text">your text</h1>

I think I might have found something to rival Docco: the popover feature of Twitter Bootstrap: http://twitter.github.com/bootstrap/javascript.html#popover
I'm not sure that it will actually look good, but it seems like a good start.

Old but good question, I was searching for similar things when I found this. There are tons of ways of doing HTML annotation, see this article for a very nice listing and explanations.
If you want annotation that simply tells the user what each line does, I would write HTML comments for small pieces of code, and larger external annotations for large amounts of code. You could then parse them using custom JS to show prettier boxes if you so wish.
<h1>Heading</h1> <!-- A heading element -->
<p>paragraph</p> <!-- A paragraph element -->
<p>Paragraph with
<b>Bold</b> <!-- An inline Bold element -->
text</p>
For larger amounts of code, I would consider using something like the documentation that Docco creates. Sure, it's for JavaScript but who says a similar one can't be done for HTML. As this was tagged with jquery-UI, you also might be interested in a jQuery text annotater.

Related

grails fields plugin <f:display is 'chopping off' bootstrap dropright action with a table of values

grails v 3.3.9, fields plugin
fighting with fields plgin and theres a problem when rendering domain objects and using bootstrap
i've got a sample here from a simple standalone page to show the problem
<p>f:display category </p>
<f:display bean="maintenanceAgreement" >
</f:display>
<hr />
<p>f:field category</p>
<f:field bean="${this.pageScope.maintenanceAgreement}" property="category">
<g:render template="/_fields/map/displayWidget" ></g:render>
</f:field>
<hr />
in essenence i have added a template in "/_fields/map/displayWidget" that renders a drop right table on a button
when you render a map field directly from your Domain object the sample table opens and you get all of the table
however when you
you can see the differences between using f.display (has clipping problem), f.field ( which seems to work) and f.all that ignores my _fields/map/_displayWidget.gsp
I dont want to have not use the fields plugin but its not working with bootstrap templating
has any one come up with a fix for this problem?
the project demo page is here
github standalone page to show rendering problem
the attached shows the output as you try each and select category property
well goldarn it another 2 days down the pan - but i have it !
I thought at first it was something to do with fields plugin processing. so i hacked a clone of plugin project locally and added some bits so i could watch it/debug step through it
in doing so i noted that my dummy web domain class page i'd cut across to the plugin didnt have the clipping problem. but the styles were not the same so i copied main.css and grails.css from ordinary project back into the plugin, then re rendered in the browser - and the clipping happened again.
so its in the css!. some very careful watching of browser and looking at the browser 'inspect' indicated that the clipping seemed to be enabled very early on in the journey.
so in my dummy page i just used
I then spent a day wandering round the various bits of fields plugin as its not that well explained anywhere.
if you look at the plugins taglib display method, by default that triggers the /templates/fields/_list.gsp. naming is a little odd but its the gsp that renders the domains persistent attributes as an ordered list - the plugins default _list.gsp looks like this
<ol class="property-list ${domainClass.decapitalizedName}">
<g:each in="${domainProperties}" var="p">
<li class="fieldcontain">
<span id="${p.name}-label" class="property-label"><g:message code="${domainClass.decapitalizedName}.${p.name}.label" default="${p.defaultLabel}" /></span>
<div class="property-value" aria-labelledby="${p.name}-label">${body(p)}</div>
</li>
</g:each>
</ol>
so after much exploration coming up through templates, from the bottom I ended up right at the top with the '
so nearly there now. back into main.css that i'd copied in. if you edit that, down around line 215 you get this style. If you comment out the overflow property - its all fixed !
.property-list .fieldcontain {
list-style: none;
/*overflow: hidden; */
zoom: 1;
}
I tried auto, scroll, and visible but that seems to much about with too much of the page so best to just comment it out.
once you do that - the rest of the rendering of your forms starts to work !! blimey one line of css for all that pain. Attached is the page using
Lastly through out all this, id ended up digging through /tracing fields plugin. What a nest that is. Not really finished here, but basically
with no body just renders a label and no content. So you either need to provide provide a body tag, say to get the value field displayed.
as
if no widget template has been defined then the renderDefaultDisplay is called which again has very limited options for controlling the rendering by falling through a 'switch (prop.type)' and basically calls either g.format (bool), g.formatDate (but no LocalDateTime/LocalDate Support) or g.fieldValue, non of which are bootstrap enabled.
if you call
these two diagrams are not beautiful but just high level pseudo code walk through for what the core tags are trying to do. One day i'll try and pretty that up but it might help you if you get stuck
I'll raise a bug for the main.css clipping directly to the grails team and see what happens, but you can comment the line out yourself if you fall foul of it.

Rails]Using Markdown Markup Language

In my rails application, people are supposed to submit "posts." However, in the default scaffolding, there are some problems in the text input: not allowed HTML code, changing the line doesn't work, etc. From what I've learned, I need to use a markdown-markup language to solve this issue. Is there a guide for me to follow to apply such language to solve my problem?
UPDATE: Here are my problems.
1) Every sentence is combined into one line even if I put a line space.
first line
second line
becomes
first line second line
2) I can't make text bold, italicized, or hyperlink. Like in stackoverflow, user should easily put <b> and make bold text, ** to make italicized, etc. And URL address should automatically be translated to href link.
To do these, I thought I had to use markdown library. I could be mistaken, so I needed someone to guide me through. Railscasts on Markdown
Well, yes, new lines in HTML have no meaning. You need to replace line breaks with <br> to preserve them in HTML. To automatically highlight links, you need to look for links in the text and wrap them in appropriate <a> tags. Finally, if you're not filtering HTML tags, they should still be in there. It all depends on what you're doing. Markdown is something entirely different, a special markup language that enables you to do the above while being easier to write than HTML. It depends on what you want to use.

Orchard CMS Recent Blog Post Widget Alternate View

I'm new to Orchard CMS and MVC so please forgive my ignorance. I've done a search and not found anything apparently relevant....
In one of the Footer Quad zone on my Orchard site I want to show the 5 most recent blog posts, just by title. At present it show the title, post, tags etc all in their unformatted state(Ive not style the blog yet).
Using the tracing tool I've created an alternate view called;
Parts.Blogs.RecentBlogPosts
However the only content in this view is;
#Display(Model.ContentItems)
Which -unlike other installed widgets Ive edited alternate views for- doesn't give me anything to play around with to create the layout I'm needing to create.
Have I selected the wrong shape / view, or do I need to get stuck in with some coding???
As I say, I'm new to both MVC and Orchard but very keen to learn. Any help on this will, as always, be greatly appreciated.
I got the exact same problem while trying to differentiate recent blog posts layout from blog summary posts. I followed this concept
http://weblogs.asp.net/bleroy/archive/2011/07/31/so-you-don-t-want-to-use-placement-info.aspx
and created Parts.Blogs.RecentBlogPosts alternate. Then while navigating through the model using shape tracing tool I found all elements I was looking for and put them in my new shape. I know that my approach might not be the most appropriate one but it works. Maybe it would be a starting point for someone who would need to do similar thing:
<div class="last-news">
<ul>
#foreach (var item in Model.ContentItems.ContentItems.Items)
{
var max = (item.ContentItem.BodyPart.Text.Length > 100) ? 100 : item.ContentItem.BodyPart.Text.Length;
<li><header>#Display(item.ContentItem.CommonPart.PublishedUtc.ToShortDateString())</header></li>
<li><h1>#Display(item.ContentItem.TitlePart.Title)</h1></li>
<li>#Display(Html.Raw(item.ContentItem.BodyPart.Text.Substring(0, max)))</li>
}
</ul>
</div>
It does deserve an explanation. Model.ContentItems here really is a List shape. When you call Display with it, it will locate the most appropriate template for a list shape (and that can be an alternate) and renders it. The default List rendering just renders UL/LI and in each LI calls Display on the individual Content shape for the list element, but with the Summary display type. When that in turn gets rendered, the system locates the most relevant Content template, which usually renders a bunch of zones, inside of which the parts get pushed according to placement. So there is a lot going on, in quite a few nested levels.
Still, it is possible to override the whole thing at any level. The difficulty is to know what to put there. The easiest for this is to explore the Model in shape tracing and see what you can use.
This article shows how to override list rendering in a particular situation and take it over entirely:
http://weblogs.asp.net/bleroy/archive/2011/03/27/taking-over-list-rendering-in-orchard.aspx
The Parts.Blogs.RecentBlogPosts view displays Parts_Blogs_BlogPost_List shape (Parts.Blogs.BlogPost.List.cshtml) which displays BlogPost content items. (You can see it in RecentBlogPostsPartDriver.cs). BlogPost content type consists of TitlePart and BodyPart parts which has their own shapes and views (or templates in Orchard terminology).
So to make some corrections for those templates you could try to alternate Parts_Blogs_BlogPost_List, Parts_Common_Body_Summary and other shapes.
Please see the following instructions on Orchard docs page especially:
Alternates
Accessing and Rendering Shapes

How do I remove HTML tags from within a text area using MVC 3?

I have difficulty getting a value from a text area of the CKEditor
when I save something that has nothing inside the textarea HTML tag. In this case, it puts this text inside:
<html>\r\n\t<head>\r\n\t\t<title></title>\r\n\t</head>\r\n\t<body>\r\n\t</body>\r\n</html>\r\n"
Is there some way to strip off all these html tags?
I'm using MVC 3, and I've researched something about: Content(Server.HtmlEncode),
but I'm still not 100% if this is the best way to do this kind of treatment.
I found a class listed below that looks like it should solve your problem. Just add it to your solution and you can then call it statically and strip the html.
This kind of assumes that you are wanting to do the stripping of html on the server side.
On a side note not accepting answers like you are doing is hazardous to people willingness to help...I'd recommend that you reward the people that are helping you if you'd like to continue getting help!
Link to Solution
#Html.DisplayTextFor(modelItem => item.content)

Usage of image in sIFR

I want to use sIFR in my blog posts also. But there's a major problem that I couldn't fix.
Let's say the blog post is between these divs:
<div class="post">BLOG POST IS HERE</div>
So, my selector is .post.
When I insert an image tag inside this div, the image isn't being showed by the browser. Just like this:
<div class="post"><img src="myimage.jpg" align="left" />BLOG POST IS HERE</div>
Is there a way to use sIFR with images?
As far as I know sIFR is not capable of displaying images. It is not intended to change an entire blog post. You should concentrate on the headlines.
i would recommend you place your blog post paragraphs inside <p> tags and then sIFR .post p in your css if you're going to do it, but as said above sIFR on a large amount of text is a bad idea...
I'd recommend reforming your markup so that the headline is in some sort of header element. like so...
<div class="post"><img src="myimage.jpg" align="left" /><h2>BLOG POST IS HERE</h2></div>
Then you could select on .post h2 in your sIFR declaration. This should achieve the effect you're looking for, and be much better for SEO.
Not really meant to be used for huge blocks of text. It's a fairly elegant solution for problems, but it's still flash, so don't go mental because you'll begin to degrade the user's experience, and that's counter to what you're after.

Resources