We held a mini documentation sprint this evening and tried to flesh out some of the sparse-looking Advanced Help docs. Participants included stephthegeek, Harry Slaughter, Michelle, esmerel, merlinofchaos, Randy Fay, Brent Ratliff, myself, and probably others (sorry, I lost track :\).

Here's an upload of the current state of http://typewith.me/pvyR0RWDuS where we were collaborating on this (html, renamed to .txt to appease drupal.org's filters). Please feel free to continue editing this more! Ultimately, these need to be split up into separate .html files and put into Advanced Help, which is a nice task for someone who doesn't feel comfortable writing docs but wants to see this happen.

There's also this great step-by-step tutorial about taking over the home page that Harry Slaughter is working on: http://tinyurl.com/panels-tutorial-doc

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Harry Slaughter’s picture

http://tinyurl.com/panels-tutorial-doc is image heavy, so I left it on Google Docs until it's ready to be checked in.

I think it has sufficient screen shots, but the textual explanation is not finished. The document is publicly editable by anyone with the URL.

If you are comfortable with Panels, please feel free to review/edit this document. Maybe leave a note here about your changes.

If the document is no longer there, it is likely that it has been checked into the code base.

merlinofchaos’s picture

Consolidating issues. Closing http://drupal.org/node/683704 and moving text here:

Regarding 'Views' vs 'View panes':

They are two different ways of doing things, and in a way it's tailored very much to how you want your site administration to work.

The 'Views' section just lists all views. (It can be turned off too). It makes them all available and provides the most generic interface possible. The problem with it is that you might have content editors who aren't really site builders who can manage your panels. Particularly if you're using something like OG Panels that lets people build panels on top of OG. That gets way too complicated for them.

So Views Panes allows you to customize views *before* they get to Panels. And you can control what arguments they get, but it's controlled in the view display itself. Check out the settings in the Views UI. You can control what contexts it wants for the arguments, and what settings are changeable in the UI.

This needs to be better documented somewhere within...actually it's within CTools I suppose, but possibly Panels as well.

emmajane’s picture

I've updated the Typewith.me page with extra words too. And I'm flagging myself on this issue so that I remember to take some time to go back and hack my words into the main flow of what's already there.

teleted’s picture

Documentation is so desperately needed.
I'm glad to see it's being worked on actively.
Argument and argument handling is very undocumented.

christoph’s picture

FileSize
717.18 KB

I hope I haven't duplicated anyone's work... we had a new person starting and since we use panels a lot I started to write up how to use them. It seemed useful, so I've fleshed it out into a full blown manual and hopefully this goes some way to the need for documentation (I think it's fairly complete for our use cases). Sorry to be lazy, but I haven't really looked at how documentation is licensed - but more than happy to make available however makes sense. Also apologies that it's in PDF format - it just started out that way. Again, if someone can tell me how I can help in moving it to a more accessible format & to where, I'll do that.

christoph’s picture

Just edited document in post #5 to include passing URL arguments in as contexts and implementing a ctools argument plugin. Keeping updated version on our site until we figure out where best to put it Our guide to Drupal Panels

merlinofchaos’s picture

Status: Needs work » Active

drupal.org documentation is automatically licensed under Creative Commons sharealike, see here: http://drupal.org/node/14307

All documentation bundled with modules is automatically licensed under the GPL, which is pretty similar. Mostly both licenses amount to "Do whatever you want with it, except prevent other people from doing whatever they want with it."

I took a quick skim through this document. It's pretty amazing, though in PDF form I'm not sure what to do with it. Documentation on drupal.org is typically structured as HTML and images. Documentation in modules is usually structured similarly through the use of advanced help. That said, perhaps this could be converted to advanced help as well.

To be fair, the PDF looks pretty darn nice, and could be made available nearly as it is. Probably the biggest thing that would have to change would be the prominence of the company logo. The company should have space to take attribution, without a doubt, but the logo and website on every page makes it a little too easy to misunderstand that Olamalu actually built the package, not just the documentation. But the PDF alternative format is really handy for some people. Web browsing of documentation is simply not always ideal.

Let's start with this: The best thing to do is format this for advanced help. Right now the advanced help is completely in shambles, both in CTools and Panels. One of the biggest problems is that the separation of the systems makes it difficult to document cohesively. You don't need Panels to use Page Manager (technically -- right now there's a missing piece to make this absolutely true) but you do need Page Manager to use Panels. And right now, at least half of the documentation is about Page Manager. Those aren't separate conceptually. Yay reality meeting vision badly.

I'm going to move this issue to 'active'. needs work is accurate, but I think it hides it and isn't a good state for something that is broader than bug/feature patches.

merlinofchaos’s picture

Some random comments:

The description of the term panel page conflates nodes with page manager. Page manager pages are not nodes, and therefore they are not under content administration.

In the documentation for templates, I would probably focus a little more on the idea of a 'System' page (which is often a template) and a 'Custom' page. Node and taxonomy templates are system pages, and they override default Drupal behavior on these pages.

Variants: All page manager pages can have variants, but they are most useful on system pages where you are, more or less, formatting an object (term, node, user) for viewing.

Bulk export: You should use this more. For deployment it is the bomb -- you develop on your dev site, export everything to code, then push your page manager pages with all their configuration to your live site just by updating the code.

Panel nodes: You're correct. In general, you will not use page manager AND panel nodes in the same application. If you find yourself wanting a truly panel-node solution, the new panelizer module is a better solution anyway. It is possible that as we move forward, panel nodes will be ejected from Panels into their own project and we will favor Panelizer as the solution.

The panels dashboard: This is really kind of an overview; because Panels is so spread out, this brings everything into one place primarily to help you find it. You don't actually truly administrate things from here, but it's a good starting location to get to what you do want to administer. As such, I wouldn't really recommend editing pages from the panels dashboard. What it shows you from page manager is a pretty small snippet of what's available.

Walking through the example is where your documentation really shines. Got to step away, so I'll post this and come back with more later.

christoph’s picture

Glad this will be useful - yes accept it should be Drupal branded. I'll take a look at how advanced help works and see how I can adapt - maybe useful to have as both HTML and PDF, but need to see how to keep the 2 in sync whilst we continue to add to this document. Will commit to getting this into a useable format and including your comments in the next couple of weeks. I'll assign myself to this issue.

christoph’s picture

Assigned: Unassigned » christoph

Assigned myself to get this documentation in format for advanced help.
Quick update: Am writing a conversion program to convert OpenOffice document to advanced help structure - in Java, but will be able to post results in the next few days and also means the primary document can be used as source for advanced help and PDF output.

christoph’s picture

I've made some progress on incorporating some of your feedback in #7 and #8 above and building an easy way for converting Open Office documents into advanced help documents. I realise this document will still need work to be advanced help, but this is a start to see if what I'm doing works, and maybe make it more flexible for others to edit the work as time goes on.

So I'm posting the following. The OpenOffice document, the PDF exported from that document, the advanced help package generated from that document and the little Java code I wrote to do that conversion (releasing that under GPL in case anyone wonders). For the moment, happy to take feedback and bring it all back in until it's finally crafted. Comments as per #8, where I could work out where in the document to change were helpful.

I do need to fix a bit of the code markup on the help for the final release.

Ahh - see I can't post a *.jar file. That's on our website at this link

christoph’s picture

FileSize
742.52 KB

This is a tar of the advanced help generated from the document in #11

joecanti’s picture

Good work Christoph - that PDF is looking pretty comprehensive. I got your note about overlapping, and I dont think we'll overlap as at the moment. I'm just doing quick hands-on examples. whereas I can see a manual like yours is more of a resource to be referred to and completed. I guess that's the bonus of written documents is that they can be added to and developed.

I've added some screencasts here - this is the first: http://www.youtube.com/watch?v=v6zMcfTxkhc

It's my first screencast so I definately need to improve a few things - but it's a start! I think for the next one I'll do from start to finish - a step-by-step guide from photoshop to a panels everywhere finished site. I dont like the sound of my own voice (who does apart from the A list), but I actually quite enjoyed doing it!

All the best, Joe

spineless’s picture

I don't know. This is not very useful. The 'help' documentation is more of a self glorying explanation on how the system was built, how great the panels module is......

I just need some help understanding how to use panels. i do not want to learn about what development was put into it.

Do you have a help file on how to actually do something with panels.... without having to recode it? I mean it has got to do something straight out of the box. What can I do with it that will produce something?

I need help with mini-panels.

How do you use substitutions to replace the title of a mini-panel? I changed the title type to "Manual set". I then selected something simple like " %node:title " or "Hello World" in the Title cell. I saved it and took a look at the block which I placed in 'sidebar one' but nothing appears in the new block. I can see the block but there are no words.

I am also having issues attempting to understand the following:

How do you select a item from the commerce module?
How do you add a picture to a mini -panel?

Are there any help files to show me how to use panels?

joecanti’s picture

In answer to your questions:

- What can I do with it that will produce something out of the box?
Start by creating a test page. Go to pages > Add custom page. Give it a path and a layout, then add some content to each section. Maybe experiment by creating a home page - with a title, some text and maybe a 'view' of recent posts in the right hand column.

Next try using it to template a node type. First create a new 'about us' content type and create a few 'about' pages. Next go to panels and enable 'node template' - then click 'edit' and create a new variant. In selection rules choose 'node type' and choose your about us node type. Now add some content in the content section, including some node stuff - like title and body.

You have now created a way to template the about us section of your website, so that every page you create that is of the type 'about' will follow this template.

- replace the title of the mini panel?
Whenever I am adding a title to a panel I always choose 'no title' - and then make a 'view' to display the node title, which I then add to the mini panel. This way I can style the content as I like with CSS and I don't need to set up any contexts for the mini panel. It's also good for caching, and I use the same 'node:title' view throughout my panels designs.

- How do you select a item from the commerce module?
Again this is Views stuff - the commerce module integrates tightly with views, so use Views to build your lists of products, which you can then insert into panels.

- How do you add a picture to a mini -panel?
The easiest way is to use basic html in a custom content piece, and make sure the 'full html' option is on.EG:

http://www.w3schools.com/html/html_images.asp

(just paste the html into a 'custom content' area and change the values to suit}

If you want to add it using an image upload wizard, you can enable the CK editor module and install the CK editor - this gives you a full wysiwyg editor in the cutom content area, and you can add pictures through the image section in that. ( I think - havent done this for a while)

- Are there any help files to show me how to use panels?
There are lots of help files, and also videos on youtube. I did a series which covers panels and panels everywhere - the first one is here:

http://www.youtube.com/watch?v=v6zMcfTxkhc

It's important to remember though that Panels isn't just an out-of-the-box design system - it does have a learning curve. To get the most out of it you want to have a good grasp of CSS anda little html. Once you;ve learnt it though, it's great at quickly creating designs without php, and adjusting them visually. Also a good knowledge of views is essential really, because Views is great at pulling content out of the DB and putting it together.

NB: To be able to insert Views into Panels, you need to have the 'views content panes' module turned on, which is part of ctools.

cheers, Joe

spineless’s picture

Thanks Joe,

This is very helpful. Thanks a lot. :)

I am attempting to create a title in the mini panel that will display the book parent when the user is on a child page. I am using node tokens ie: %book_parent:title. However this substitution is not working when I replace it in the titles cell. Here is the post I have describing the issue. http://drupal.org/node/1288250.

joecanti’s picture

I see the problem. I think this would be possible with context, but tricky to get right. If it were me doing this I would forget contexts and mini panel titles and make a view instead, and then insert it into the mini panel.

You want to get it so that when you put in the node ID of the child book, the title of the parent book appears, and this is really where Views relationships will help you out alot. 3 key parts of your view are as follow:

- Argument: Node:ID > default argument > get node ID from URL. (If you're using Views 3 this is called contextual filters, and instead of Node ID it's called content NID - and the default argument is called 'default value')

- Relationship: Node: Parent

- Field: Node title (making use of the relationship above)

(Get it working without the relationship first, just to check things. So your node ID outputs the node title.)

If this is all correctly set up, you will be able to preview it in Views by putting the node:ID of the child node into to preview box, and press update preview. Then the node title of the parent should now be displayed.

You can now insert this view directly into your mini panel, or into your panel, or make it into a block and insert it elsewhere in your site.

Cheers, Joe

spineless’s picture

FileSize
57.72 KB

Hello Joe,

I kind of understand what you are telling me . I just do not see these cells in the views window.

I am using Druapl 7 with views 7.x-3.0-rc1.

To access views i go to Structure --> views --> Add new view.

In the window that appears I see the following:

view name:

Show "content" of type "book page" sorted by "newest first"

I uncheck create page

I create block.
block title
display format

_________________

I am not sure where to see the argument, relationship and field that you are describing. Where do I find these fields?

Thanks,

Spineless

joecanti’s picture

FileSize
4.31 KB

In Views 3 you see this step first, where you can add some basic info about your view, which it then helps to set up. Press 'continue and exit' to go into the main views setup page, and under advanced you will see your relationships and contextual filters.

I have attached a View for you to import, which can be a starting point. It simply gets the node title from the Node URL. So go to views, and then import. Paste everything in the text file and import. Then when you see the view, try putting a node ID into the preview box and press update preview. You will see the node title appear in the content.

And dont forget to save.

There is a block also, so you can insert this block around your site, including mini panels. It will look at the URL, get the node ID and spit out the node title.

Get this working, get used to how it works, and then add a relationship in the view so that instead of giving you the node title, it gives you the node parent title.

Also check out the node one screencasts:

http://nodeone.se/blogg/learn-views-with-nodeone-part-1-overview

If you're building a D7 shop with commerce then good views knowledge is a must.

Sorry - it's a lot to learn!

All the best, Joe

spineless’s picture

Thanks Joe,

The link you provided me helped a lot. i was able to understand views after going through the first 7 episodes of the presentation and managed to get what i want. :)

Letharion’s picture

Assigned: christoph » Letharion

Re-assigning to myself as I'm actively working on putting this information together.

Letharion’s picture

Here is the branch I've started this work in. http://drupalcode.org/project/panels.git/tree/refs/heads/6.x-3.x-lethari...
Far from done, but it allowed me to close some old issues, and I intend to improve it incrementally. We'll see when it get's merged into mainline.
I'm leaving this issue open as I haven't ensured all info from here has found it's way in yet.

  • Commit 854d064 on 7.x-3.x, pipelines, 7.x-3.x-i18n, 8.x-3.x by esmerel:
    Issue #1077976 by esmerel: added link to issue #887560 to README.TXT
    
    
DamienMcKenna’s picture

japerry’s picture

Status: Active » Closed (won't fix)

I forsee us writing documentation for D7... maybe? if there is interest. But not D6. I'm moving the documentation tasks to D7 and closing this d6 issue.