The Joomla! Forum ™

Download

Demo


Board index » Joomla! Official Sites & Infrastructure » Documentation - Feedback/Information/Suggestions

Forum rules


Please click here to view the forum rules



Post new topic Reply to topic  Page 1 of 1
  [ 8 posts ] 
  Print view Previous topic | Next topic 
Author Message
almoravit
PostPosted: Wed Oct 28, 2009 2:52 pm 
User avatar
Joomla! Enthusiast
Joomla! Enthusiast

Joined: Fri Sep 25, 2009 10:41 pm
Posts: 120
Location: Barcelona, Europe
Hi,

I supose that this question should be posted here. If not, please, feel free to move it where you think is the right place.

I think it could be a good help for the coders community to have a repository of code snippets. I've spend many hours looking for code examples on google, docs.joomla and even Joomla! source code to find those five code lines which, sure, every other coder has searched before.
Subjects like "Component creation tutorial" are not the target of this repository, but "Add style sheet" are more appropiated to the resource I'm thinking.
Is there something like this?
Do you think this could be a useful resource ?
It has sense to have something like this ?
Is docs.joomla the right place to host this resource ?

Thanks for your time.

_________________
Almoravit
Top
 Profile  
 
Chris Davenport
PostPosted: Wed Oct 28, 2009 8:41 pm 
User avatar
Joomla! Ace
Joomla! Ace

Joined: Thu Aug 18, 2005 8:57 am
Posts: 1376
Location: Shrewsbury, Shropshire, United Kingdom
Yes, we would very much like to encourage people to add code snippets to the documentation, particularly for the class and method pages in the API Reference (http://docs.joomla.org/Framework). Something like "Add style sheet" might be added as an example to http://docs.joomla.org/JDocument/addStyleSheet, for example. More extensive examples could be given their own pages and we can easily set up a new category to make it easier to find them.

Regards,
Chris.

_________________
Joomla Leadership Team - Production Working Group

Joomla Web Services http://www.kickstarter.com/projects/964120480/joomla-web-services
Lion Coppice http://www.lioncoppice.org
Top
 Profile  
 
almoravit
PostPosted: Fri Oct 30, 2009 12:18 am 
User avatar
Joomla! Enthusiast
Joomla! Enthusiast

Joined: Fri Sep 25, 2009 10:41 pm
Posts: 120
Location: Barcelona, Europe
Hi Chris,

Would you mind to check that ? http://docs.joomla.org/JTable/getobjectslist
As it is my first document I only want to know if I'm moving on a good way. Is there any style book for documentation and any conventions for page names?

Thanks.

_________________
Almoravit
Top
 Profile  
 
Chris Davenport
PostPosted: Sat Oct 31, 2009 6:39 pm 
User avatar
Joomla! Ace
Joomla! Ace

Joined: Thu Aug 18, 2005 8:57 am
Posts: 1376
Location: Shrewsbury, Shropshire, United Kingdom
The pages in the wiki which have the names of Joomla Framework classes are effectively "reserved" for the API Reference. Sub-pages of the form <class>/<method> where <method> is a method of the Framework class called <class> are also reserved for the same reason. At the present time I think it's best not to add any sub-pages beneath a class page that are not method pages.

It could be added as an example to this page: http://docs.joomla.org/index.php?title= ... &redlink=1 which doesn't exist yet. This is part of the API Reference and you should read these guidelines if you want to add a page there: http://docs.joomla.org/API_Reference_Project

A good example of adding an example code snippet to an API Reference page is: http://docs.joomla.org/JDocument/addScriptDeclaration

You might also like to read this page: http://docs.joomla.org/How_to_use_the_d ... our_script which includes an example similar to yours and is a more task-orientated page.

It is also possible to create a separate code snippets area and I'm open to suggestions on how that might be organised.

Regards,
Chris.

_________________
Joomla Leadership Team - Production Working Group

Joomla Web Services http://www.kickstarter.com/projects/964120480/joomla-web-services
Lion Coppice http://www.lioncoppice.org
Top
 Profile  
 
almoravit
PostPosted: Sat Nov 07, 2009 8:29 am 
User avatar
Joomla! Enthusiast
Joomla! Enthusiast

Joined: Fri Sep 25, 2009 10:41 pm
Posts: 120
Location: Barcelona, Europe
Hi,

I was a litle busy this days, sorry for delay. Thanks your suggestions and links. As far as I've read they I'm sure will help me!
A separate area for code snippets could be nice. As they are more a cooking receipt, then it could be nice to have links in the <class>/<method> document with several code snippets.
To help readers to find code snippets could be usefull to add a 'Code snippets' title anywhere (pe, after 'See also' paragraph ) in the <class>/<method> document, in the <class> document or even both. This allows to share code snippets with different <class>/<method> and <class> because one code snippet could involve several classes and several methods.

Best regards,

_________________
Almoravit
Top
 Profile  
 
Chris Davenport
PostPosted: Mon Nov 09, 2009 12:05 am 
User avatar
Joomla! Ace
Joomla! Ace

Joined: Thu Aug 18, 2005 8:57 am
Posts: 1376
Location: Shrewsbury, Shropshire, United Kingdom
Here's a suggestion that would make the code snippets easier to find and maintain...

When creating a new code snippet, give it a sensible, descriptive title. No need to include "Code snippet" or anything similar in the title. Instead, add [[Category:Code snippets]] to the end of the page, together with other relevant categories. In particular, add a [[Category:JClass]] and [[Category:JMethod]] for each class and method used.

Then, in the JClass page, add a Code Snippets section with the following code:
Code:
<dpl>
  category=Code snippets
  category=JClass
<dpl>
for a class page, or
Code:
<dpl>
  category=Code snippets
  category=JMethod
</dpl>
for a method page.

The code snippets lists will then be generated automatically.

Chris.

_________________
Joomla Leadership Team - Production Working Group

Joomla Web Services http://www.kickstarter.com/projects/964120480/joomla-web-services
Lion Coppice http://www.lioncoppice.org
Top
 Profile  
 
daverii
PostPosted: Mon Nov 09, 2009 7:53 am 
User avatar
Joomla! Enthusiast
Joomla! Enthusiast

Joined: Fri Mar 06, 2009 4:20 pm
Posts: 104
Location: Switzerland, UK & France
I am sure that Chris knows about this but I had a similar requirement although I did not know about this thread.

I found the same tool and this page describes how to get various kinds of Category list.

I was looking for a way of controlling the size/appearance/relevance of the list so that my page design stayed reasonably balanced.

Time will tell but this seems to be the man for the job.

_________________
Tony Davis

Wengen, Switzerland
Top
 Profile  
 
almoravit
PostPosted: Wed Nov 11, 2009 10:14 am 
User avatar
Joomla! Enthusiast
Joomla! Enthusiast

Joined: Fri Sep 25, 2009 10:41 pm
Posts: 120
Location: Barcelona, Europe
Hi,

Nice suggestions Chris!...
I we'll play with it the sandbox first...

Good link daverii. Will be useful!

Thanks!

_________________
Almoravit
Top
 Profile  
 
Display posts from previous:  Sort by  
Post new topic Reply to topic  Page 1 of 1
  [ 8 posts ] 


Board index » Joomla! Official Sites & Infrastructure » Documentation - Feedback/Information/Suggestions

Who is online

Users browsing this forum: No registered users and 3 guests

You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Jump to:  
Powered by phpBB® Forum Software © phpBB Group