Dizkus

randomblink wrote:
Which forum do I use to ask questions about designing customized modules?
__________________________________________________
The nearest is proably the third party modules forum but here will do ok. The other option is the pnDev (or possibly pnLegal these days!!!) mailing list.

So ask away.....

-Mark
__________________________________________________

OK!
So here I go.
I am working on a personal module for my site, I have downloaded and printed out and bound all of the online documentation for building modules. None of them easily explain the current modules.

Question 1) I am wanting to rate items using the core ratings module, except my items are in two to three tables out of the ten that I need for my module as it is. Each table holds a unique item and I would like them rated... but I can't figure out how! Is there a documentation on utilizing the Ratings Module?

Question 2) I have read, and re-read, the API reference manual. I understand the basics of the PostNuke commands, I am even picking up some PHP as I go (new to PHP AND PostNuke... learning them together!). Anyway, does anyone have a manual with the API commands broken down? For instance, I would like to see what pnSerUserVar looks like in PHP... with nice commenting, etc... Does such a thing exist? (Oh, and I would just use the API book... except it has VERY LITTLE examples used, and most of the commands have so little in the sections that it is sad.

Question 3) I am curious about the whole block-to-module relationship. I am in the middle of just learning how to build tables with pntables.php and pninit.php, so I haven't even started to learn how to build a block, but does someone have an easy to understand example of what a block is and what is should be built for...?

If there are weblinks to information I haven't found... PLEASE point me to it. I would much rather get this stuff printed out and bound into little books I can read over...

I did not say anything to criticize anyone, so if you get upset reading this message, then you are looking for a reason to get mad. I am not saying that the PostNuke developers aren't doing a good job, I am merely saying that there is a powerful need for more documentation on the PostNuke system.

BTW: If you are a PostNuke developers, and you are reading this, I have technical writing experience, both military and corporate (no training, just a knack... mother was an english major... I lernt me sum werdz.) anyway, I would be very interested in documenting the PostNuke system, but I would need some place to drop questions... And as long as I was given decent credit, I would be happy for it to remain public GPL or whatever... (but if anyone makes any money off of it, I would want a slice! )

And I believe that does it.
Thank you in advance for any help.
If you get annoyed at me for these questions, please just move on to the next message and stay happy man. I would rather get NO replies... than someone mad because I am clueless...

peace out

Right lets take this one bit a time...


But does the combination of data form a single logical item? The ratings module will rate a single logical item not a single record from a table. As long as the tables are logical joined by an item id the underlying structure doesn't matter.

However if your module stores several logical different item types then the ratings module will have a problem

Ratings stores moduleid, itemid and rating.

A bit more detail on your module may be requred for me to answer this is any authority



I saw post on support.postnuke.com where someone has broken down the API reference into a seperate article per function so this would be a good place to look.



A block is a single view on some data from a module or a small stand alone piece of code. Blocks can be displayed on pages around the main content of a page to enhance the functionality of that page or the site in general.

An example of the first would be the display of a poll display block. This would output a single view on a single poll from the polls module. An example of latter would be an RSS newsfeed block. All the code for this function is in the block itself and this isn't dependant on any module.



As for the documentation I agree fully. I've only been on the dev team since the end of january.

PN is in a state of flux and has been since last summer with changes in the dev team. This is now (hopefully) beginning to settle down.

As far as the code is concered we are also in a interim state. One of the major tasks of the dev team at the moment is to get all the modules ported to the API.

Once this has been done I fully intend of reviewing the Module devlopers guide and updating it to reflect the ability to able to interact with a lot of the core modules which currently can't be done due the lack of API status as well as improving the overall structure of the document.

I'm not a technical writer and would never pretend to be one so anyone that is willing to help is more than welcome. All this documentation would be GPL (or another open licence approapriate to documentation).

As someone that was undertaking the same learning curve as you 18 months ago I can appreciate the postion you're in. As for being upset then no one can be upset over constructive criticism.

Hope this answers the questions and feel free to ask anymore.

-Mark

Wow Mark...

Those are excellent answers...



Well, I am building a Profiles module.
It creates tables to hold:
A Gamer account which holds:
-> A list of games played
-> A list of gaming groups (members of)
A Gaming Group Account which holds:
-> A list of gamers
-> A list of games
A Game account which holds:
-> Game data
-> Company Data
A Company / Store account that holds:
-> A list of employees (mainly for President, etc.)
-> A list of games sold / produced
-> A list of gaming groups that congregate at the store

So, there are like 5 tables... (I might have left one out) and they are all related to some degree. I am wanting to rate gamers and gaming groups and games and companies and stores... The purpose being that eventually I want to offer a trading-spot on my web and if gamers/traders can be rated, then people can avoid bad trades, etc... And if we can rate games, well duh... obvious...

But does that explain it?

Next:



Um, I have browsed all over the PostNuke site. I have downloaded about everything you can download, then I printed it out, then I took it to our printing department and had them bind it into book form... Most of what I have is, well, pretty weak on the documentation-side. BUT, I will look again.

That is the best block information, and I had already assumed that that was what it did, but not knowing was driving me crazy. THANK YOU THANK YOU THANK YOU!

Well, I am serious about doing the documentation. I have written manuals, training and spec books for the military, so I think I could provide something to the group. If someone will contact me using my e-mail from my profile, I will gladly work with PostNuke to put together a well documented setup!

Just let me know...
Oh, and again... Mark, THANK YOU!

I try.



This helps my analyse your aims a bit further. A 'gamer account' sounds like a user with some additional info. So we look at using the dynamic user data feature of PN to add the additional fields. DUD is one area that needs some work to provide DUD API functions. I've written most of this an it's in CVS at moment.

A gamer group sounds like a set of standard PN groups to which a user can subscribe. Chestnut a regular PN hacker just release a hack for group subscriptions. See this article.

For games themselves the reviews module with ratings or this third party reviews module may help.

Overall I think your currently trying the make a single module do too much. My (personal) opinion is that a module should achieve a single task, manage a single type of data and expose an number API's for other modules to interact with.

It's a matter of development philosophy I suppose.



This is the article I was meaning but you may have seen it already.

I'll mention your name at our next dev meeting for our documentation team.

-Mark

Whoa, whoa, whoa...
Wait a minute...
Back the truck up...

So let me get this straight.
(big lightbulb buzzing above my head right now!) :idea:

So, when building modules.
Let's say I wanted to build an Engineering Portal (thinking about it for an intranet where I work)...
And I want Engineers and Contractors to be able to work with their projects, hope you don't mind... let me walk throug an example module creation here...

What I would do... Let's say we start with Users.
I would set up two groups using regular PN permissions.
-> Engineers
-> Contractors

Then, I setup one module for Projects.
It creates three tables.
let's call the module: Eng_Projects
It creates a table called: Eng_Projects
and it creates a table called: Rqst_ProjectAuthorization
and it creates a table called: Bckup_Projects
We setup functions to:
-> insert new project requests
-> move authorized project from the Rqst table to the Eng table
-> edit current (un)authorized Projects
-> delete Projects from the Rqst table if they fail to get approval
-> remove Projects from Eng_Projects and move to Bckup_Projects

and that does it for that module... (follow with me on the no block yet thing)...

Then, I setup another module for Invoices.
It creates a single table.
let's call the module: Eng_Invoices
It creates a table called Eng_Invoice
We setup functions to:
-> insert new Invoices
-> edit current Invoices
-> calculate invoice amounts

Then, I create a module to bring them together.
Call it: Eng_ProjectManagement
I create functions to:
-> compare Invoice totals for a given project compared to budget
-> check dates on project events and see what is late
---> see what is coming up
...as well as other management functions

In that module I create my blocks.
Blocks where users can put in the initial project request to the Rqst table.
--> can create a new invoice.
--> can edit project data using the functions from Eng_Project

etc...

Am I right?

Sorry about that; I work in technical developments for a large organisation. Thinking through large corporate style IT deployments is what I do.



Yep that sounds feasable. You'll have to plan the specifics but as a overview you're heading in the right direction. The overview module would implement what could be defined as the workflow of the process - the passing of data between the modules.

For me this break down of modules to simpler processes not only simplifies the development process but makes better, more modular code.

It's certainly easier to debug a single process module and then a larger more complex module.

-Mark

No problem kind sir.
I am just stunned.
I have way too much to think about.
That changes everything.
I see... very modular.
I do like that.
A little different, but definitely easier to debug.
wow.

Hey, Mark, I really wanna thank you. This helps ALOT... and it is greatly appreciated. You mentioned that 18 months ago you were in my shoes, any tips to help me pick all this up (besides what you already gave me)?

I can only tell you the way I went about it. It worked me but may not for others.

I had a good educational grounding in programming and programming theory anyway so this was a good starting point as well as being a full time IT professional.

I wrote my own module which I now distribute (Advanced polls - http://www.markwest.me.uk) and spend a fair bit of time answer other peoples queries here.

The time spent here allows you to work with aspects of the software you wouldn't otherwise touch so you end up with a better overall view of the code. You also see other users requirements which leads to an overall generalisation and modularity in your own code.

-Mark

Ok...
I checked out the pncgroups files that you mentioned. Didn't like em.
And since enough of it was in french, I decided to create my own, but I think I can figure out enough of the code he used that it might help to have the access to it. He does similar enough to what I want that it just might work!

I am working on a new module grouping for my site now.
Using the single module per table (or similar tables), I am building a module for memberships... a module for groups... a module for games... a module for stores/companies... and then each module will include linking tables...
For instance, the store/company module, will create two tables:

table: gf_business
:fields:
- businessID
- businessName
- link_contactDetails
- link_memberType
- link_relatedGames

table: link_mainGames
:fields:
- entryID
- gameID
- link_relatedGames

I am going to link the LINK fields of course.
So that every Business CAN be linked to a list of games that they produce/publish, whatever...

The game module will create a table with fields like:
gameID (linked to the table: link_mainGames)

Of course this is ALL in flux, in fact, I am rewriting some of this as I am typing this message. But, basically, you get the gist.

I really appreciate your help.

And if the PostNuke team could use my help, tell em I am ready and willing... Thanks again...