More Documentation on creating skins

If you visit admin/help/jcarousel, you'll get some live examples of jCarousel being used. What other documentation did you want?

Whoops, didn't mean to change to fixed.

Well I seem to not be able to implement jcarousel in my website...
I've googled, checked the jCarousel help, searched and tried lots of things but still have not managed to succeed...
So I would appreciate if there was more documentation...

What are you trying to make a jCarousel of? This is just an API module, so you'd have to write code:

$rows = array('ntg', 'werd', 'herrro');
echo theme('jcarousel', $rows);

I have been starring at the admin/help/jcarousel file, and all the examples work beautifully. What the file is MISSING is actual instructions. For instance,

1. where do I place: jcarousel_add()
2. Do I need to surround in PHP tags?
3. How do I place the parameters?

The help page simply shows that it is possible, but it does not show how the page itself was created, i.e., what jquery was called, how each one was set, where the call is places, etc. It would be VERY HELPFUL if above each example was a jcarousel_add (etc) simply presenting the code used to create each example. then the link to Sorgulla would be helpful for people to expand.

It seems the problem is not building on the code, it is knowing where to place it in the first place. If someone will tell me how to do it, i can rewrite the help page and send it to someone so it can be posted.

Well, those questions are Drupal theming basics, as far as I can tell. Which is why they're not documented in this module.

Wim,

I mean this in the nicest way, but I have read through the documentation and the issues on this site, and the number of 'basic' questions which you do not answer are plenty. I am not a basic themer, though there there are clear holes in my knowledge. This is one of them. I did figure out the answer and am happy to add to the documentation page included in the module. I think this would be immensely helpful for people, far more helpful than dismissing such requests as "basic" and not deserving of documentation.

Currently, the documentation shows that the code works. It does not show where to place the code, etc. If the documentation can list, before or after each example, something like this, it would really save frustration:

"Place the following in the body of your node, enclosed in the PHP tags. Be sure to include the PHP tags and select PHP as your input format.

<?php jcarousel_add
('#carousel',
array(
        'scroll'=>'1',
        'wrap'=>'both',
        'animation'=>'slow',
        'start'=>'4',        
        ),
      'mgm'
);
?>

Where should we put that documentation though? In README.txt for Drupal 6?

Currently, the standard help includes some very nice examples. I think the ideal is that immediately before each of these examples, the sample code which creates the carousel would appear. Further, the Sorgalla configuration link could be highlighted as a place to see all the options. A single example could be placed in the read me. I think that would cover the important areas.

I think the biggest problem with jCarousel's documentation is the fact that it didn't do what most people needed it to do. I think there was a built-in expectation that this module would actually *do something*, but out-of-the box it includes a help page, a JavaScript file, and some skins. It required custom coding to do anything, which most users don't know how to do (see the help requests in this issue above for examples).

The new 2.x version on the hand includes what most people want: Views support and a way to make carousels without any coding. I rewrote the example in README.txt when I made the new 2.x port to describe how to make a carousel with Views, but this patch revamps the help page to clarify how to use carousels and better code samples (where you can actually see the code, rather than needing to open up the jcarousel.module).

This still doesn't tell people where to put the code exactly (other than references to in "template files or custom modules"), because like Rob said above, we shouldn't be documenting how to accomplish theming or write custom modules in the help for a single module.

Keeping track of this thread

@naoise: Any particular suggestions? We already document how to use the module with Views and how to implement the module through the API. I don't believe that we should re-document every property of the entire library, since the jCarousel library documentation already covers all of it: http://sorgalla.com/projects/jcarousel/

This module already has a 100 line README and a half-dozen implementation examples in the built-in help at admin/help/jcarousel.

Ah, okay so this is not on actually how to *use* the module but more on how to create a custom skin (through a different module). Thanks, I'd have to agree that our documentation is minimal on that front. Currently we're expecting users to sift through the source code to figure out how to implement hook_jcarousel_skin_info(), which many developers probably won't be able to figure out.

subscribing. I need to create some custom jCarousel skins, so, I'll try to contribute some docs when I do. Is there a handbook page set up for this, or is this a README.txt effort?

wuh posted a very good howto in #469322-8: Where to put custom skins:

For version 6.x-2.4:

If you want to set things up so that you can select a custom skin via jcarousel settings in views, make a custom module and use hook_jcarousel_skin_info()

For example:

/**
 * Implements hook_jcarousel_skin_info().
 */
function my_module_jcarousel_skin_info() {
  $skins['myskin'] = array(
    'title' => t('My Skin'),
    'file' => 'jcarousel/skins/myskin/jcarousel-myskin.css',
  );

  return $skins;
}

Note that you should place all the skin's files inside your custom module's folder. In the example above, the jcarousel folder would be inside a module folder called my_module

I find it ridiculous that I have to edit the existing module's directory or create a new module entirely in order to create a have a new skin for this module.

@Jumoke: I'd be happy to listen to any suggestions you might have for making a skin easier. As I've said several times before, I strongly suggest people just use no skin at all and write all the CSS directly into style.css or override the jcarousel-default.css file that comes with the module by copying it into their theme. How many sites really need multiple "skins" in the same theme? And if your site needs to have multiple skins, where would you place these skins if it weren't a module?

That we actually have to write a module (even a small one) is more than many folks care to do.

For me, the expectation would be to have new skins in the skins directory in the jcarousel module itself. That the module would scan the existing directory and add in any skins it found.

The other option would be to have a something in the themes/css directory.

But having to code a small module is daunting to many. Ah, just realized this is over a year old -- so maybe some new developments have happened that I am not aware of. Right now, I can't get my new module hook to work correctly.