This is written as an overview for a phpLD developer for creating listing types and their corresponding template. This is an ADVANCED topic, but great to share with a PHP developer who is going to be helping you build your site.
Listing types development guide
Smarty templates
Each listing has 3 template files to render details page, list item and grid item. Those templates are in /templates/[CURRENT_TEMPLATE_DIR]/views/_listings/ directory in details, grid and list folders. In /templates/[CURRENT_TEMPLATE_DIR]/views/_listings/ directory there are common templates, which used to render some complex html, which moved from listing template to make it easier.
PHP Code
Each listing is rendered by Model_Link_Entity::render($purpose, $style=”list”) method.
$purpose parameter determines what for it rendered – as a list part or as listing details page.
$style parameter determines grid/list style. When u need to pass these aprameters to this method use constants, defined in Model_Link_Entity, they are PURPOSE_LISTING, PURPOSE_DETAILS, STYLE_LIST and STYLE_GRID, don’t use render(1, “grid”), use ender(Model_Link_Entity::PURPOSE_DETAILS, Model_Link_Entity::STYLE_LIST).
There are also 2 helper methods: listing($style=”list”) and details(). They call render() inside, just allow to define less parameters.
Listings also have adapters, to define listing type specific code. For example some listing types should have specific template placeholders or specific behaviors. For example “Video” listing type should know how to get a video thumbnail and render flash embed code. Handler class determines in Model_Link_Entity::__construct() by “LINK_TYPE” parameter. Let’s take a look on Model_Link_Handler_Default handler. This is default handler, which implements abstract method Model_Link_Handler_Abstract::_assignPlaceholders(), which assigns common placeholders. In this method we use assigned placeholders, which are built from other smarty templates, for example:
$view->assign(‘LISTING_URL’, $view->fetch(‘views/_listings/_placeholders/listingUrl.tpl’));
Assigns listingUrl.tpl content to LISTING_URL smarty variable (placeholder), which is used in listing detail/grid/list templates.
If you need to add something that is listing type specific – you should define a new handler, like it’s done with Model_Link_Handler_Video, which defines video-related methods and implements its own _assignPlaceholders method, which assigns own placeholders.
Template HTML
Grid templates should be wrapped into
List templates into
When list rendered – all listings are wrapped into div tags with class listing-style-grid andlisting-style-list. Keep this in mind when developing css, try to bring as less new css classes as possible. If you need to define some listing specific css – add “listing-[LISTING_NAME]” class to listing wrapper tag.
Exact steps to create a new listing type
- Create 3 template files in /templates/[CURRENT_TEMPLATE_DIR]/views/_listings/ folder in grid, list and details folders
- Add new “Submit item” in admin panel – “Link Types” -> “New Submit Item”. Choose just added templates in List template and Details template select boxes.
- Manage submit items in “Link Types” -> “Available Submit Items” section (cog icon)
- Add submit items if needed
- Create a handler class if needed
- Define templates html and put placeholders on their places
Placeholders list
Common placeholders
LISTING_SUBMIT_ITEMS – views/_listings/_placeholders/submitItems.tpl
LISTING_URL_TITLE – views/_listings/_placeholders/listingUrlTitle.tpl
LISTING_URL – views/_listings/_placeholders/listingUrl.tpl
LISTING_THUMBNAIL – views/_listings/_placeholders/listingThumbnailList.tpl OR views/_listings/_placeholders/listingThumbnailGrid.tpl (Depends on listing style)
LISTING_IMAGE – views/_listings/_placeholders/listingImage.tpl
LISTING_CATEGORIES – views/_listings/_placeholders/categories.tpl
READ_MORE_LINK – views/_listings/_placeholders/readMoreLink.tpl
LISTING_STATS – views/_listings/_placeholders/listingStats.tpl
ADDRESS – views/_listings/_placeholders/address.tpl
GOOGLE_MAP – views/_listings/_placeholders/googleMap.tpl
PAGERANK – views/_listings/_placeholders/pagerank.tpl
LISTING_RATING – views/_listings/_placeholders/listingDetailsRating.tpl
LISTING_COMMENTS – views/_listings/_placeholders/listingComments.tpl
LISTING_TELL_FRIEND – views/_listings/_placeholders/tellFriend.tpl
Video placeholders
LISTING_VIDEO_EMBED – views/_listings/_placeholders/videoEmbed.tpl
VIDEO_THUMBNAIL – views/_listings/_placeholders/videoThumbnail.tpl
