#526 ✓resolved
Artem Medeu

Cheat sheets feature for docviewer plugin

Reported by Artem Medeu | January 4th, 2011 @ 10:58 AM | in 1.2

New feature for built in docviewer plugin: cheat sheet page (e.g. http://playcheatsheet.appspot.com/).

Discussion thread: https://groups.google.com/forum/#!topic/play-framework/L-YytX0IMtg

Comments and changes to this ticket

  • Artem Medeu
  • Peter Hilton

    Peter Hilton January 8th, 2011 @ 03:08 PM

    • Tag set to documentation
  • Peter Hilton

    Peter Hilton January 8th, 2011 @ 06:01 PM

    This is pretty cool, although I don't think I'm the one to decide whether this should become part of the official documentation. The documentation already links to the static version at - http://www.crionics.com/products/opensource/play/TheUltimatePlayChe...
    (which reminds me that I need to update http://download.playframework.org/miscellaneous/play-cheat-sheet.pdf)

    We do add this, then some fairly straightforward improvements are possible:

    • make the look and feel fit better with the current documentation, e.g. fonts and colours
    • consider using CSS3 columns instead of the table/JavaScript layout (I'm not sure about browser support)
    • add a print stylesheet to make it look good on paper
    • for use in a web-browser add some way (e.g. tabs) to navigate between sections like Controllers and Templates.
  • Artem Medeu

    Artem Medeu January 10th, 2011 @ 04:47 PM

    Hi, Peter

    Thanks for your valuable reply. I'll see what can I do with styling. It's my main weakness though.

    Little offtopic:
    I saw your commit [#488] (added keywords), which is partially covers this ticket. Is this going to evolve to dynamically generated keywords? Maybe there is no need of such feature (I mean this ticket)?

  • Peter Hilton

    Peter Hilton January 10th, 2011 @ 05:34 PM

    Don't worry too much about the styling - there are other people who can do that easily (e.g. me).

    I'm not sure what the future holds for the #488 keyword indexes. That's more about navigation than being a quick-reference, but there's certainly overlap. The main thing that's cool about your cheat sheet is that you summarise key parts of the API that you use when writing controllers, for example.

    Perhaps it would also be cool to #{include} the controllers section from the cheat sheet at the end of the controllers chapter in the manual, for example.

    I'd like to hear what the others think about how cheat sheets relate to the main documentation.

  • Artem Medeu

    Artem Medeu January 10th, 2011 @ 05:56 PM

    The main thing that's cool about your cheat sheet is that you summarise key parts of the API that you use when writing controllers, for example. Thanks, but my work here was converting Olivier Refalo's pdf to a set of textile files. So many thanks to him for content.

    Perhaps it would also be cool to #{include} the controllers section from the cheat sheet at the end of the controllers chapter in the manual, for example. I got your idea and like it. Thinking about using subfolders (e.g. controllers, templates etc.) in documentation/cheatsheets folder to make it more structural and self-described.

  • ronin-124355 (at lighthouseapp)

    ronin-124355 (at lighthouseapp) January 10th, 2011 @ 10:07 PM

    Hi there, sorry to catch the train so late. I only noticed this discussion today.

    I personally like the online version better than the PDF ! it's easier to search and faster to change in the future. I am getting into issues with the PDF version: I tried to segment areas per pages, page1 controller, page2 view, page3 model. But it comes with a trade off... some page are full and I need to take decisions as to which methods are more important: kind of hard to do... I like them all ;-)

    If it can help, I can share the document on github. It's built with Pages (MacOS). I can convert it to Word but the layout will most likely be screwed up.

    Anything I can do to help, just let me know,
    Kind regards,
    Olivier

  • Peter Hilton
  • Peter Hilton

    Peter Hilton January 12th, 2011 @ 12:47 PM

    • Assigned user set to “Peter Hilton”
  • ronin-124355 (at lighthouseapp)

    ronin-124355 (at lighthouseapp) January 12th, 2011 @ 03:40 PM

    Kind of cool, how can I edit the sheet ?

    TO ADD
    play.db.DB.execute("raw sql")

    added:

    @{ Controller.action().secure() } Calculates url relative https path to the action

    added
    better descriptions and samples for @on()

    typo:
    /app/view/tag/domain/mytag.tag -> /app/view/tags/domain/mytag.tag

    the latest sheet is attached

  • Artem Medeu

    Artem Medeu January 12th, 2011 @ 06:28 PM

    Just updated my pull request (rebased from latest master, squashed all my commits into one).
    Changes:

    1. Divided cheatsheets to categories. Now "documentation/cheatsheets" folder contains subfolders (each is named as category, e.g. "tests", "model" etc.)
    2. Changed route to @documentation/cheatsheets/{category}
    3. On cheat sheet category view page (e.g. "@documentation/cheatsheets/model") added top menu which contains links to other categories
    4. Using CSS3 columns
    5. Some styling

    Direct link to cheat sheet of any category can be obtained as @PlayDocumentation.cheatSheet("categoryName"). List of categories can be obtained by calling Map<String, String> helpers.CheatSheetHelper.listCategoriesAndTitles (where key = category, value = human readable title).

    Problebms:

    Cheat sheet page is statically divided into 3 columns by using CSS styling. If cheat sheet is small (for example @documentation/cheatsheets/multiEnvironment) browser divides it into three small height columns, hard to read. Any ideas how to better fix it?

    Made preview screenshot: http://goo.gl/zX1Ac

  • Artem Medeu

    Artem Medeu January 13th, 2011 @ 04:55 AM

    Hi, Olivier

    Many thanks for your participation.

    You can view all cheat sheets from my github clone of play at https://github.com/armed/play/tree/lighthouse-526-patch/documentati.... Consider it draft, because the patch is still in review :)

  • Peter Hilton

    Peter Hilton January 13th, 2011 @ 12:34 PM

    • State changed from “new” to “confirmed”
  • Guillaume Bort

    Guillaume Bort February 3rd, 2011 @ 10:10 PM

    • State changed from “confirmed” to “inprogress”
    • Milestone set to 1.2
    • Milestone order changed from “323” to “0”
  • Play Duck

    Play Duck February 3rd, 2011 @ 11:01 PM

    (from [e0c7b18483dda0cec4b9326a81bc72a35cd052f8]) [#526] Added cheat sheet support to standard docviewer module

    Each cheat sheet could be accessed via url '@documentation/cheatsheets/{category}'
    https://github.com/playframework/play/commit/e0c7b18483dda0cec4b932...

  • Peter Hilton

    Peter Hilton February 6th, 2011 @ 11:20 AM

    I've made some look-and-feel changes to the cheat sheets, which I hope are improvements. The biggest change is to lay out each section horizontally across three columns, instead of the whole cheat sheet. A minor tweak was to set the min-height for each column, for small sections. I also added a basic two-column print-stylesheet.

    Are we done (resolved)?

  • Adam Livesley

    Adam Livesley March 4th, 2011 @ 12:42 AM

    Should remove the min-height: 6.5em; rule on div.cs { } otherwise the browser tries to make more columns which are hidden, so most of the "cheats" are hidden. Screenshot from WebKit: https://img.skitch.com/20110304-m7nj3f9wncq64pkg9w1hffi645.jpg

  • Peter Hilton

    Peter Hilton March 4th, 2011 @ 05:52 AM

    I can reproduce that in Google Chrome on OS X (but not on Safari 5.0.3). It's not obvious how min-height could cause the problem that the screenshot shows; I'm looking into it.

  • Peter Hilton

    Peter Hilton March 4th, 2011 @ 06:47 AM

    • State changed from “inprogress” to “resolved”

Please Sign in or create a free account to add a new ticket.

With your very own profile, you can contribute to projects, track your activity, watch tickets, receive and update tickets through your email and much more.

New-ticket Create new ticket

Create your profile

Help contribute to this project by taking a few moments to create your personal profile. Create your profile »

<h2>Play framework</h2>

Play makes it easier to build Web applications with Java. It is a clean alternative to bloated Enterprise Java stacks. It focuses on developer productivity and targets RESTful architectures. Learn more on the <a href="http://www.playframework.org">http://www.playframework.org</a> website.<br><br>

<h2>Source code is hosted on github</h2>Check out our repository at <a href="http://github.com/playframework/play">http://github.com/playframework/play</a><br><br>

<h2>Contributing, creating a patch</h2> Please read the <a href="http://play.lighthouseapp.com/projects/57987/contributor-guide">contributor guide</a><br><br>

<h2>Reporting Security Vulnerabilities</h2> Since all bug reports are public, please report any security vulnerability directly to <em>guillaume dot bort at gmail dot com</em>.<br><br>

<h2>Creating a bug report</h2> Bug reports are incredibly helpful, so take time to report bugs and request features in our ticket tracker. We’re always grateful for patches to Play’s code. Indeed, bug reports with attached patches will get fixed far quickly than those without any.<br><br>

Please include as much relevant information as possible including the exact framework version you're using and a code snippet that reproduces the problem.<br><br>

Don't have too much expectations. Unless the bug is really a serious "everything is broken" thing, you're creating a ticket to start a discussion. Having a patch (or a branch on Github we can pull from) is better, but then again we'll only pull high quality branches that make sense to be in the core of Play.

Attachments

Referenced by

Pages