Example / stub module

mtakacs
mtakacs's picture

Joined: 2004-04-14
Posts: 4
Posted: Mon, 2004-11-22 08:25

Hi,
Any plans to release an example / stub module. Its much easier for module developers to get off the ground running if there's a (functional) do-nothing module that has all the right hooks / interface calls in place. Then u can just gut it's 'do nothing' functions and put in your code...

I can always copy a (small) module and try and strip it down to basics, but as a new developer there's a chance i might strip out / leave out something essential.

Maybe y'all already have a stub module you use when you're making new modules?

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Mon, 2004-11-22 16:58

I suggest:
1) read phpdoc in modules/core/classes/GalleryModule.class to see what the module api can do.
2) start with a copy of a module.inc that does things similar to what you need and modify that.
3) look through modules/core/classes/GalleryCoreApi.class to see what core api's are available

(oh, and 4: start with a recent snapshot or cvs as there were some tweaks to the module api a few days ago)

 
bharat
bharat's picture

Joined: 2002-05-21
Posts: 7993
Posted: Tue, 2004-11-23 05:40

Long term, we'd definitely like to have a stub (or "tutorial") module. Short term, we haven't had time to write it. If anybody out there would like to write and submit a useful tutorial module (and is willing to put sometime into maintaining it) we'll help out as best we can.

 
virshu
virshu's picture

Joined: 2003-09-13
Posts: 314
Posted: Tue, 2004-11-23 06:27

As I am writing (more like struggling with :wink: ) custom module, I had similar questions. I think I got over them, so I'll try to package a "stub" module (including tags for a table), hopefully next week.

I have to say, though, that once I got over the hurdles of creating a proper module, the bigger challenge seems to find the right API. The GalleryCoreApi and GalleryUtilities (just to name a few) have over hundred of functions. They are quite well commented, but it still takes awhile to figure out what I am looking for :o

But it's all quite rewarding once you figure it all out!

 
virshu
virshu's picture

Joined: 2003-09-13
Posts: 314
Posted: Fri, 2004-11-26 23:49

OK, here is step 1. It isn't much, but it has all the required pieces (so it can get installed, activated, and reversed). In addition to looking at this example I would also recomment reading the docs!

It also shows in Admin Options (which is, strictly speaking, optional), but the view doesn't do much.

The next 2 steps are (1) to handle a form in Admin Options that sets some setting and (2) have a module that has an associated table. Any preferences?

Couple disclaimers -
I am not a member of development team; so my findings may be wrong (and corrections or additional comments are more than welcome);

English is my third language; so don't expect a fancy tutorial :P

With that said, hopefully this will be helpful...

 
bharat
bharat's picture

Joined: 2002-05-21
Posts: 7993
Posted: Sat, 2004-11-27 05:08

virshu, excellent work! A few notes:

  • In Step1.inc you set the controller to migrate:ImportResults (which is a clue as to which module you started from :-)). I'd change this to an empty field, or better yet change it to tutorial1:Step1 and then add a simple do-nothing Step1Controller.
  • I'd add a simple form and a button to Step1 so that you demonstrate how to pass data from a view to a controller.
  • Create a po directory and put the localization strings in it. It's easy -- here's what I do for new modules. Make the po dir and copy the GNUmakefile and the de_DE.po into it from any other module except from core (whose po dir is slightly different than the rest). Then edit the de_DE.po, fix the first msgid block to have the right dates and put your name in there. Delete everything from the second msgid onwards. Then run "make" and it should rebuild the de_DE.po file with the strings from your module (and it will create the actual localization for you). You can test it out by putting your "translations" in there and running make -- then when you select German from the language dropdown your stuff should be translated.

If you'd like to work with us to make a full blown tutorial and keep it up to date, that would be tremendously helpful. Come on by #gallery and talk to me about it if you're interested...[/]

 
baschny
baschny's picture

Joined: 2003-01-04
Posts: 328
Posted: Tue, 2004-11-30 01:19

bharat, virshu, I have once started on tutorial modules that were meant to come together with Daniel "CloCkWeRX" O'Connor's tutorial start (http://www.freshfm.com.au/gallery2/). Unfortunately my time got scarce and I haven't heard from him too.

My "vision" was a tutorial based on a step by step approach, where each step adds more functionality to a tutorial module while having the developer learn more and more from g2's working:

Tutorial 1: a new module is born

- explain what the required files for a module are, how it will be integrated in G2 (the modules subdirectory, etc) where the user should place the files, etc
- create a very simple GalleryTutorial module just like you did, but just with a constructor and a single ItemLink, so that the user can already see its results (in form of a link for each item, which won't work yet) and doesn't have too much information he doesn't need right now.

Tutorial 2: a new view

- fill the created View (i.e. the ItemView) with some content: Create a view (explaining what a view is etc), use the templating engine,

Tutorial 3: a new entity

- create a new entity in gallery: The required files, the @g2 tags, the database files, the class-file and the interface to its members. The first usage of registerFactoryImplementation() to add the entity to G2-core.

Tutorial 4: a controller and a view using the new entity

-

Tutorial 5: more functionality a module can use

- internationalization: $this->translate() etc
- module parameters with $this->get/setModuleParamter()
- maybe a light intro to GalleryCoreApi

Tutorial 6: more module's integrability into G2

- registerEventListeners: checking when an user logs in and out
- performFactoryRegistrations: adding implementation to other module's
interface, e.g. the GallerySearchInterface_1_0.

Tutorial 7: GalleryCoreApi

- how to use, and what to know about other core functionality...

I am attaching my work on the sample code (which was halted during production of tutorial4). Each tutorial is supposed to have a separate module. So maybe someone can continue where I left it and send that to Daniel so he can continue working on the tutorial (maybe he's still waiting for this..). It was based on a previous g2-alpha API, I just updated some basic stuff for it to work with the current api, but there might be issues left.

 
bharat
bharat's picture

Joined: 2002-05-21
Posts: 7993
Posted: Tue, 2004-11-30 05:03

That is totally bad ass! I would be eternally grateful to anybody who is willing to pick this up and run with it. If you do, we (the whole G2 team -- not just I) will help you with any questions you have!

 
virshu
virshu's picture

Joined: 2003-09-13
Posts: 314
Posted: Tue, 2004-11-30 07:31

baschny, I am still at step2 (see attached). The biggest challenge I see with step 3 (and actually, with step 2 as well, since I added localization) is to write instructions how to build this thing on Windows. I can bet that you all build Gallery on Linux. Which is great, but for some of isn't an option :cry:

Anyway, I was able to build G2 on cygwin (I gave up on 'pure' Windows after getting too many make errors). So, cygwin looks like reasonable compromise! I am writing pre-requisites, changes in some command files; hopefully, will be done by the end of this week. Without such instructions Step 3 (entity) seems more like a giant leap!

 
alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Sat, 2005-12-31 07:38

Hi, I know it's an old thread but I wanted to know if somebody was still working in the module development tutorials. Baschny and Virshu's examples are very helpful but there's still much to be explained.

Gallery's source code is very clear but jumping from file to file and understanding how the whole system works is a little confusing at first and takes some time for new developers.

I would be glad to help in collaborating with a module development tutorial as soon as I get more used to the code.

Regards!

Alexis Bellido - Ventanazul web solutions

 
valiant

Joined: 2003-01-04
Posts: 32509
Posted: Sat, 2005-12-31 13:38

much will change in G2.1. and we'll definitely add more documention in future. but for now there's nothing new.

 
alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Wed, 2006-01-18 17:12

Hi, a couple of quick questions about baschny's tutorial2.

In ViewInfo.inc you have:

function getViewDescription() {
  list ($ret, $core) = GalleryCoreApi::loadPlugin('module', 'core');
    if ($ret->isError()) {
      return array($ret->wrap(__FILE__, __LINE__), null, null);
    }

  return array(GalleryStatus::success(), $core->translate('show tutorial2 info'));
}

Why is that method there?, I don't see where it fits, I can't find the string 'show tutorial2 info' anywhere.

I also wanted to be sure why the use of $core->translate versus using $this->translate as in the getItemLinks() method in module.inc.

Thanks!
Alexis Bellido - Ventanazul web solutions

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Wed, 2006-01-18 18:02

you can't use $this->translate because $this is your GalleryView, not your GalleryModule.
however, you don't want $core->translate either.. you want:

function getViewDescription() {
  list ($ret, $module) = GalleryCoreApi::loadPlugin('module', 'yourmoduleid');
  if ($ret->isError()) {
    return array($ret->wrap(__FILE__, __LINE__), null, null);
  }
  return array(GalleryStatus::success(), $module->translate('show tutorial2 info'));
}

or for current CVS / Gallery 2.1:

function getViewDescription() {
  list ($ret, $module) = GalleryCoreApi::loadPlugin('module', 'yourmoduleid');
  if ($ret) {
    return array($ret->wrap(__FILE__, __LINE__), null, null);
  }
  return array(null, $module->translate('show tutorial2 info'));
}
 
alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Wed, 2006-01-18 18:30

Hi Mindless, thank you for the explanation.

And what about the getViewDescription() method? I can't figure out what is doing in this example module, I see it's returning a sucess status code and a string but I don't see where this information is, or should be, used.

Regards!

Alexis Bellido - Ventanazul web solutions

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Wed, 2006-01-18 19:20

oh.. it's just used in the navigation links. if you're viewing your view and then click "site admin" or "your account" or some other links, then navigation section on the sidebar will show "back to {your view description}". if you don't implement this method i think the link just says "back".

 
alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Wed, 2006-01-18 20:40

All clear now, thanks a lot!

Alexis Bellido - Ventanazul web solutions

 
alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Mon, 2006-01-23 03:20

Hi, I'm programming with 2.1 CVS now and baschny's tutorial modules are not working, I changed the setRequiredCoreApi and setRequiredModuleApi calls to the correct numbers (7.1 and 3.0 respectively), references to GalleryStatus::Status to null and if ($ret->isError()) to simply if($ret), however it's not working yet.

In tutorial 3 I can get the module installed and activated and I can see the link "tutorial3 item info" in the sidebar, however when I click on it I get a blank page (running Firefox 1.5 on Fedora Core 3).

Any idea what little detail I may be missing?

Thanks.

Alexis Bellido - Ventanazul web solutions

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Mon, 2006-01-23 16:24

also remove autoConfigure (now defaults to true) and isRecommendedDuringInstall (obsolete) from module.inc.
not sure what other api change was missed (you can check the list on codex).. does immediate debug mode give you any clue why the view doesn't come up? i assume all paths have tutorial3..

 
alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Wed, 2006-01-25 19:22

Hi Mindless, thanks, I will review the code again and take a look at API changes in Codex.

Alexis Bellido - Ventanazul web solutions

 
alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Wed, 2006-01-25 22:57

Hello, I didn't find more references in Codex about changes for API in 2.1 (CoreApi: 7.1 and ModuleApi: 3.0, please correct if I'm wrong), I looked at Codex API Changes.

I've made some changes in tutorial3, including updating the version and following Valiant's great suggestions on how to create tables in the database, this way I was able to create the table using Site Admin > Modules > Upgrade.

I also deleted references to the Tutorial3Entity_core class and included everything for creating the new entity in Tutorial3Entity.class.

However I found some methods which are not existant now in 2.1 and are called in Tutorial3Entity.class:

getPersistentMemberInfo()
getMemberData()
setModifiedFlag()

They were in class GalleryEntity in 2.0.2. How should I replace them for 2.1?

I'm attaching my current tutorial3 if anybody wants to take a look (I am seeing it listes as tutorial3.tar.gz.txt once uploaded, if you download like that jusr rename it to .tar.gz, I just used tar czvf to create it), still not working, and I will upload the final version for 2.1 (and hopefully for tutorial4 too) once I fix it.

I hope you can help. Thanks!

Alexis Bellido - Ventanazul web solutions

 
kpmd

Joined: 2006-01-25
Posts: 5
Posted: Wed, 2006-01-25 23:43

So is tutorial3 for G2 or G2.1? I want to take it for a spin but am on 2.0.2

 
alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Thu, 2006-01-26 00:10

The tutorial modules in this thread are currently for 2.0.2, I'm working to get them ported to 2.1 and just need to resolve some small details to have it ready, I just need some details about the new 2.1 API to get it done.

Regards.

Alexis Bellido - Ventanazul web solutions

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Thu, 2006-01-26 00:31

from codex main page click API, then API changes since last release (not the changes from alpha to 2.0 that you mentioned).

 
alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Thu, 2006-01-26 01:07

Hi, thanks for the link, I got the info I was looking for.

I've just uploaded the modified tutorial3 module, this time I used .zip instead of .tar.gz, Drupal was not allowing to download and was showing just plain text.

It's working with G2.1 now, however I didn't know what to do with this:

function getPersistentMemberInfo() {
	$meta = parent::getPersistentMemberInfo();
    
	$meta['members']['text'] = array(
	    'class' => 'Tutorial3Entity',
	    'type' => STORAGE_TYPE_TEXT
	);
    
	return $meta;
    }

So I just commented it out, would this be good?

I'm going to work in tutorial4 now and hope to have an updated version uploaded soon.

Regards.

p.s: For the picky guys, there is an XHTML validation error in ViewInfo.tpl, in the "br" tag, it should end with "/>", in the uploaded module is ending in "\".

Alexis Bellido - Ventanazul web solutions

 
kpmd

Joined: 2006-01-25
Posts: 5
Posted: Thu, 2006-01-26 01:53

Thanks for the info. When I try to install it complains it is an invalid module:

Tutorial 3 Module
Incompatible module!
Core API Required: 7.1 (available: 6.8)
Module API Required: 3.0 (available: 2.0)

 
alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Thu, 2006-01-26 02:41

Hi, you need to have Gallery 2.1 for the updated tutorial3 to work, get a nightly snapshot and let me know if it's working.

Regards.

Alexis Bellido - Ventanazul web solutions

 
alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Thu, 2006-01-26 04:40

Hi, I have almost completed the upgrade of tutorial4 module to Gallery 2.1, however I'm getting an error when adding a record to the g2_Tutorial4Entity table.

The error is:

Error (ERROR_MISSING_OBJECT)
* in modules/tutorial4/AddEntity.inc at line 60 (AddEntityController::error) 

I've compared my tutorial4/AddEntity.inc file to comment/AddComment.inc in G2.1 and at the fundamental level they both seem to be doing the same thing.

I added a date field to the original tutorial4 and fixed capitalization for settext() method, now it's setText().

I'm attaching my code and hope you could give me a hint to get it working.

Thanks!

Alexis Bellido - Ventanazul web solutions

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Thu, 2006-01-26 19:47

(Note: Gallery 2.1 is not released.. you need current CVS / nightly snapshot which is nearing 2.1)

Thanks alexisb!

for the error above, the path to Tutorial4Entity.class is missing "classes/" in module.inc, performFactoryRegistrations.

 
alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Thu, 2006-01-26 20:02

Hi, thanks, I'll take a look.

You are right, I'm just using nearing 2.1 snapshots, it's good to remind our friends that it's not a final version yet.

Alexis Bellido - Ventanazul web solutions

 
alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Thu, 2006-01-26 20:12

Oops, that didn't fixed it, I'm still getting:

Error (ERROR_MISSING_OBJECT)

    * in modules/tutorial4/AddEntity.inc at line 60 (gallerycoreapi::error)
    * in main.php at line 202 (addentitycontroller::handlerequest)
    * in main.php at line 87
    * in main.php at line 80

I've rechecked everything and can't find what I'm missing, any other idea?

Alexis Bellido - Ventanazul web solutions

 
mindless
mindless's picture

Joined: 2004-01-04
Posts: 8601
Posted: Thu, 2006-01-26 23:55

did you deactivate/reactivate the module after fixing that? you need to refresh the factory registration.

you might also correct the @package lines in various files..

 
alexisb
alexisb's picture

Joined: 2005-11-24
Posts: 56
Posted: Fri, 2006-01-27 00:26

Great, it's working now, I just had to deactivate and activate as you suggested.

I'm attaching the complete tutorial4 module for Gallery 2.1, I mean, for Gallery CVS which is going to be 2.1.

I know it's not a super module and could be optimized but it's a good learning experience.

Thanks to Baschny and all the others who participated in this thread, thank you Mindless, thank you Valiant.

Regards!

Alexis Bellido - Ventanazul web solutions