Example / stub module

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?

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.

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, 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.

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!

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

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'));
}

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".

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

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

Alexis Bellido - Ventanazul web solutions

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

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

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)

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

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

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..