What about a code snippets collection resource ?

Joomla! Documentation Workgroup
User avatar
almoravit
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 121
Joined: Fri Sep 25, 2009 10:41 pm
Location: Barcelona
Contact:

What about a code snippets collection resource ?

Postby almoravit » Wed Oct 28, 2009 2:52 pm

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

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1382
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: What about a code snippets collection resource ?

Postby Chris Davenport » Wed Oct 28, 2009 8:41 pm

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.
Chris Davenport - Joomla Production Leadership Team

Lion Coppice http://www.lioncoppice.org/
Davenport Technology Services http://www.davenporttechnology.com/

User avatar
almoravit
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 121
Joined: Fri Sep 25, 2009 10:41 pm
Location: Barcelona
Contact:

Re: What about a code snippets collection resource ?

Postby almoravit » Fri Oct 30, 2009 12:18 am

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

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1382
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: What about a code snippets collection resource ?

Postby Chris Davenport » Sat Oct 31, 2009 6:39 pm

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.
Chris Davenport - Joomla Production Leadership Team

Lion Coppice http://www.lioncoppice.org/
Davenport Technology Services http://www.davenporttechnology.com/

User avatar
almoravit
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 121
Joined: Fri Sep 25, 2009 10:41 pm
Location: Barcelona
Contact:

Re: What about a code snippets collection resource ?

Postby almoravit » Sat Nov 07, 2009 8:29 am

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

User avatar
Chris Davenport
Joomla! Ace
Joomla! Ace
Posts: 1382
Joined: Thu Aug 18, 2005 8:57 am
Location: Shrewsbury, Shropshire, United Kingdom

Re: What about a code snippets collection resource ?

Postby Chris Davenport » Mon Nov 09, 2009 12:05 am

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: Select all

<dpl>
  category=Code snippets
  category=JClass
<dpl>
for a class page, or

Code: Select all

<dpl>
  category=Code snippets
  category=JMethod
</dpl>
for a method page.

The code snippets lists will then be generated automatically.

Chris.
Chris Davenport - Joomla Production Leadership Team

Lion Coppice http://www.lioncoppice.org/
Davenport Technology Services http://www.davenporttechnology.com/

User avatar
daverii
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 104
Joined: Fri Mar 06, 2009 4:20 pm
Location: Switzerland, UK & France
Contact:

Re: What about a code snippets collection resource ?

Postby daverii » Mon Nov 09, 2009 7:53 am

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

User avatar
almoravit
Joomla! Enthusiast
Joomla! Enthusiast
Posts: 121
Joined: Fri Sep 25, 2009 10:41 pm
Location: Barcelona
Contact:

Re: What about a code snippets collection resource ?

Postby almoravit » Wed Nov 11, 2009 10:14 am

Hi,

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

Good link daverii. Will be useful!

Thanks!
Almoravit


Return to “Documentation - Feedback/Information/Suggestions”

Who is online

Users browsing this forum: No registered users and 3 guests