The Complete Guide to Social Engine 4 Module Development Part 2: Model, Item, Db Table

The stuff that makes SocialEngine4 go are items. Items are the things that go around the community. Photos, albums, groups, videos even users are items in the context of SE4. Items normally have title, description, body or content, slug, owners, parents etc. Items can be shared, commented on and liked.

In our module we have cars. Cars are owned by users. They have a profile page, a profile photo, can be liked, shared, commented on, can have a number of photos and can have videos.

Please note the following regarding items in SE4:

• Items have type which is the item’s name prefixed with the enclosing module’s name and an underscore. In our case it’s car_car. The prefixed can be dropped but adjustments must be made elsewhere.
• Item name/type is used as database table names. It follows that you can only use characters that are allowed in mysql table names. I don’t have an exhaustive list but to be safe use only alphanumeric characters and underscores.
• Items have a globally unique identifier which formed by the item’s type an underscore and the primary key of the item. For example car_1.
• Items’ class extends Core_Model_Item_Abstract.
• Items class declaration resides in application/modules/<ModuleName>/Model/<ItemName>.php
• The class name is prefixed with <ModuleName>_Model_
• Item’s can be retrieved anywhere using Engine_Api::_()->getItem('<item_type>', '<item_id>') or Engine_Api::_()->getItemByGuid('<item_guid>'). In view scripts items can be retrieved using the item view helper $this->item('<item_type>', '<item_id>'). To be able to use these methods the item must be declared in the module's manifest. This is done by adding an 'items' key in the manifest. In our case:
• In addition the module's core api must be defined. Create the directory application/modules/Car/Api and create the file Api/Core.php:
• Another way to retrieve an item is via the items table discussed below.

Create the file application/modules/Car/Model/Car.php:

and the file application/modules/Car/Model/DbTable/Cars.php:

And in application/modules/Car/settings/my.sql:

Run the query in mysql as well.

Please note the following:

• The table class name is the item name prefixed with <Modulename>_Model_DbTable_ and suffixed with an “s”. SE4 tries to pluralize the name of your item. Take for example the item “members” in the module “family”. The item name is “members” and type is “family_members”. The table class name is Family_Model_DbTable_Members. SE4 attempts to pluralize the item name such that category becomes categories and key becomes keys. If the item name is already plural SE4 doesn’t attempt to pluralize.
• The corresponding mysql table name is the item type prefixed with engine4_ and suffixed with an “s”. The “s” suffix is added only as needed following the pluralization that SE4 follows discussed above.
• As mentioned above the item type prefix can be dropped. In our case if we choose not to use the default item type “car_car” an use “car” instead, then the item type we declare in the manifest is “car”. In the item’s table we set $_name to “cars” and our the mysql table name will be engine4_cars.
• To get an instance of the db table we use Engine_Api::_()->getDbTable(‘<item_name_s_suffixed>’, ‘<module_name>’). Another way is via Engine_Api::_()->getItemTable(‘<item_type>’). This only works if the item is declared in the manifest and the modules core api is declared. To get an item via it’s id we use Engine_Api::_()->getDbTable(…)->find(<id>)->current.
• Engine_Db_Table extends Zend_Db_Table you may refer to the zf documentation to see what you have at your disposal.

Let’s go back to the my.sql file. Queries in this file are run when the module is installed. Since this file doesn’t exist when we install our module at the start development we had to run this manually. Any errors encountered the execution of the statements in this file will cause the whole installation process to fail.

Since as mentioned earlier, cars have owners, we have owner_id, owner_type in the table definition. With this we can query for the owner of a car using the getOwner method. By default the owner type is user so getOwner will return an instance of User_Model_User. In the future we may decide that other items can own cars. So for example we may decide that groups can own cars. A car owned by a group will have an owner_type of ‘group_group’ and calling getOwner in that instance of car will return an instance of Group_Model_Group.

Items can also have parents. The table definition must have a parent_type and parent_id which work just like owner_type and owner_id. getParent() and getChildren will be at your disposal if you plan on using parents/children on items. In addition you may set the property protected property $_parent_is_owner to make the getParent() return the owner of the item.

Cars have a primary photo. That is why on the table definition we have photo_id. When to photo_id is set. We can use the getPhotoUrl on the item to get the url of the photo file. It accepts an optional parameter that controls the size of the image whose url will be returned. In view scripts the itemPhoto view helper can be used to generate an image tag for an item’s photo.

Items can be liked, commented on and tagged. To enable any or all to this you just need to add the interface in the item’s model class:

That covers everything about items, models, and db tables. You may now proceed to the next step.

Originally published in https://social-engine-tutorials.blogsplot.com.