difference between Mapper.asHtml and Mapper.toHtml

[Damian H]

Hi,

I was wondering if anyone could help me understand the difference between the asHtml and toHtml methods on Mapper? I see that toHtml is used to render a read only representation of the object in HTML but I can't see what the asHtml method would be used for:

scala> val x = Event.findAll.head

scala> x.toHtml

res5: scala.xml.NodeSeq =

NodeSeq(<tr>

      <td>Event Name</td>

      <td>My Event</td>

             </tr>)

scala> x.asHtml

res6: scala.xml.NodeSeq = NodeSeq(Event, ={ , <span>Event Name=My Event&nbsp;</span>,  })

Thanks

Damian.

[David Pollak]

asHtml displays the class name followed by ={ followed by strings containing the name/value pairs of each of the fields in the record followed by "}"

toHtml displays a series of <tr>s containing <td> with the field name and field value.

--
Lift, the simply functional web framework: http://liftweb.net
Code: http://github.com/lift
Discussion: http://groups.google.com/group/liftweb
Stuck? Help us help you: https://www.assembla.com/wiki/show/liftweb/Posting_example_code

--
Lift, the simply functional web framework http://liftweb.net

Simply Lift http://simply.liftweb.net
Follow me: http://twitter.com/dpp
Blog: http://goodstuff.im

[Damian H]

I guess I was more curious as to when asHtml would be used? I started using it by accident when I should have been using toHtml. 

Could we get a note in the api doc at some point to draw people's attention to the difference in usage - to help others avoid making the same mistake I did?

Thanks

Damian.

[David Pollak]

On Wed, Oct 19, 2011 at 2:58 AM, Damian H <damia...@gmail.com> wrote:

I guess I was more curious as to when asHtml would be used? I started using it by accident when I should have been using toHtml. 

Dunno. :-)  I wrote those methods back 5 years ago and at the time, I had a good reason (they may have mirrored something in Rails.)

 

Could we get a note in the api doc at some point to draw people's attention to the difference in usage - to help others avoid making the same mistake I did?

This goes to the core of the discussion we were having the the Scala Lift Off London and another thread on the mailing list... how do we open Lift's documentation/ScalaDocs to the community?

I'd love to hear suggestions that do not involve GitHub pull requests.

I'd ideally like to see ScalaDoc be able to reference external documents so that we could open the external documents up to community editing without opening all of the source base up to external editing/pull requests.

 

Thanks

Damian.

--
Lift, the simply functional web framework: http://liftweb.net
Code: http://github.com/lift
Discussion: http://groups.google.com/group/liftweb
Stuck? Help us help you: https://www.assembla.com/wiki/show/liftweb/Posting_example_code

[Ben Phelan]

What about a community-managed documentation extension database?  Set it up as a webapp, pre-populate the database with versions/packages/classes/objects/methods from relevant projects then allow the community to discuss methods and edit a community-supplied doc entry for the method.  Publish the community doc entries via REST and add a tiny little extra JavaScript to the actual ScalaDocs to check the web service for any community entries then display them alongside the scaladoc comments from the code, making it clear to the reader which is which.

The advantages of this are that the webapp/database would be relatively simple, very few changes are needed for the ScalaDocs, the ScalaDocs can run anywhere and still take advantage of the community additions and it provides a record of the discussion surrounding any particular community doc entry.  (Kind of similar to how it used to be possible to download the PHP language spec docs along with all the user comments.)

[Ben Phelan]

You could also add links from the ScalaDocs to the community discussion page for that method/class/object to make it easier for people to find more info, ask questions or improve the docs themselves.

[Damian H]

Hi Ben - Interesting idea - have you any experience of working with this kind of set up?

My reservation regarding this approach would be not being able to see the full (or at least essential) documentation from within the scala file itself. Having the full documentation next to the code would make life so much easier for committers who are enhancing / bug fixing existing code, committers who are adding to the documentation within the code - (avoiding duplicating what might otherwise be in community database), users of the library who are browsing the code from within the ide etc

Yes they could go and search the community database (even assisted with a link from the code possibly), but that's an extra step that would be great not to put in people's ways.

Also, I guess we'd need to put a bit of extra effort into creating an off-line version of the ScalaDocs.

If we could make it work somehow, I'd prefer to get as much documentation into the scala file as possible. But I guess if there are technical or managerial challenges that get in the way then having a split system may be the next best thing.

[David Ashirov]

Had this same exact idea on my drive to work. with so many versions it will get pretty hairy though.

In the end, API documentation must be in the source code. How we get there is another matter.

1. Wider community of users can, with a consorted effort and a little ingenuity assemble most of the docs around the scaladoc skeleton. Then commiters review, edit and embed the comments into the source. Alternative path - scaladoc with user comments, ala postgresql documentation.

2. Committers may take an additional burden onto themselves to update the code with comments every time and place they change the codebase.

3. A new team is formed, focused only on doc updates. Sign what they need to sign. Get access to the repository with write privileges.  Doc branch is merged with trunk by the core team post review of the documentation quality.

I think #2 is most sound, and industry standard, but given the fact no one is going to sponsor the time wasted by core team on the effort this path is least appealing.
#1 is most "lockdown" friendly, but in the long run will be proven disastrous - it will be another outdated pile of garbage and yet another source of confusion. More questions to the list, more time wasted answering them.
#3 may be an ok option. Responsibilities are split, but control remains with people who wrote the code, with bulk of the work done, leaping the last mile should be painless.

Thoughts?

[Naftoli Gugenheim]

What ever happened to David Bernard's system of linking APIs to mailing list threads?

On Thu, Oct 20, 2011 at 4:32 AM, Ben Phelan <bem...@gmail.com> wrote:

You could also add links from the ScalaDocs to the community discussion page for that method/class/object to make it easier for people to find more info, ask questions or improve the docs themselves.

--

[Jeppe Nejsum Madsen]

David Pollak <feeder.of...@gmail.com> writes:

> On Wed, Oct 19, 2011 at 2:58 AM, Damian H <damia...@gmail.com> wrote:
>
>> I guess I was more curious as to when asHtml would be used? I started using
>> it by accident when I should have been using toHtml.
>
>
> Dunno. :-) I wrote those methods back 5 years ago and at the time, I had a
> good reason (they may have mirrored something in Rails.)
>
>
>>
>> Could we get a note in the api doc at some point to draw people's attention
>> to the difference in usage - to help others avoid making the same mistake I
>> did?
>>
>
> This goes to the core of the discussion we were having the the Scala Lift
> Off London and another thread on the mailing list... how do we open Lift's
> documentation/ScalaDocs to the community?
>
> I'd love to hear suggestions that do not involve GitHub pull requests.

Is there a reason why it can't involve pull requests? This does seems to
be an easy way to get it going. The committer merging the pull request
of course needs to make sure it is only docs being merged.

While the docs are technically part of the source, they are not in the
final artifacts so maybe they are not covered by the license. But ianal
:-)

/Jeppe