Dynamic Data min-HOWTO

G'day:

Here's the first draft of the Dynamic Data mini-howto.  If you find any 
errors or have any suggestions don't hesitate to blame the UN.

skribe

--- HOWTO Begins---
Xaraya Dynamic Data Mini-HOWTO
Skribe <[email protected]>

Version 0.1.  4th June, 2003

1. Introduction
1.1 Why this HOWTO?
This HOWTO is designed to be used with Xaraya Beta (v .90x) and may be of 
only limited help with other versions. It aims to teach admins how to set-up 
basic dynamic data objects.

1.2 Assumptions
Xaraya is very extremely configurable thanks to dynamic data so at this stage 
it would be impossible to list every possible combination. Therefore, to give 
you a basic familiarity with how dynamic data works I have assumed that you 
have a default version of the latest Xaraya core Beta (version .903 at the 
time of this writing), that you have chosen the Community Site (with all 
options enabled) install and that you have enabled the Articles, Categories 
and Comments modules. It is also assumed that you have created a Main Menu 
and listed the modules in it.

1.3 Copyright
(c) 2003 skribe <[email protected]>
Parts are (c) 2003 mikespub <[email protected]>

Permission is granted to copy, distribute and/or modify this document under 
the terms of the GNU Free Documentation License, Version 1.2 or any later 
version published by the Free Software Foundation; with no Invariant 
Sections, no Front-Cover Texts, and no Back-Cover Texts.

2. Adding a picture to user info

This is a tutorial created by Mikespub to show what dydnamic data can do.  It 
is basically setting up a dynamic data structure so that users can add a 
picture of themselves to their user info.

2.1 Enabling the dynamic data hook

The first thing you have to do is enable the dynamic data hook for the roles 
module.  To do this:

1. Go to Admin->Modules->ConfigureHooks.
2. Click on Dynamic Data
3. Activate the check box for roles (it should be down the bottom)
4. Save changes.

2.2 Setting up the dynamic data object

Now we need to create the dynamic data object that will hold the picture 
information for roles.  To do this:

1. Go to Admin->DynamicData->ViewObjects
2. Click on View Properties for the Roles module.
3. In Label type "My Picture".
4. In Property Type select "Image".
5. In status select "Display Only".  This will stop it showing in the 
membership list but will still make it visible in the user info.
6. Click Update Properties.


This will take you back to a similar-looking screen with your new dynamic 
data object being shown.

2.3 Adding a picture to your user info.

The first thing you'll need is a picture that is accessible via the web.  
Once you have that organised you need to add it to your user info.  To do 
this:

1. Go to Main Menu->Modules->Roles.
2. Click on "Your Basic Details".
3.  Add the URL of your picture to the 'My Picture" field.
4. Click Submit.

2.4 Viewing your picture.

There are two ways to do this.  Once you've added your picture's URL you can 
click on the 'show' link next to it in "Your Basic Details".  Or you can 
click on the info link next to your name in the membership list.


3. Adding scores to Reviews.

One of the things I missed not having in Xaraya's reviews was a rating or 
scoring system.  Ratings didn't work how I wanted them to so I used dynamic 
data to create my own.  Here's how I did it.

3.1 Setting up the scores Dynamic data object

Just like the My Picture object in roles we start by enabling the dynamic 
data hook for articles (see 2.1 above for details). Then we need to create 
the object.  To do this:

1. Go to Admin->Articles->ModifyConfig
2. Click on Reviews
3. Down at the bottom of the page there should be Dynamic Data Fields.  Click 
on Modify.
4. In Label write "Score".  BTW naming your label 'ratings' would cause a 
clash with an existing label (from the ratings module) and it wouldn't work. 
That's why I've chosen score.
5. In Property Type select "Dropdown List"
6. In Validation write "1,2,3,4,5,6,7,8,9,10".  There should be no spaces 
between the comma and the next number.  This will give us a dropdown list 
from 1 to 10 - our score for the review.
7. Click on Update Properties.

3.2 Displaying the score.

The dynamic data object is all set so now we need to modify the review 
templates to show the score. If you haven't overriden your reviews template 
in your theme all you have to do is change the following two files:

modules/articles/xartemplates/user-summary-reviews.xd
modules/articles/xartemplates/user-display-reviews.xd

I simply replaced the #$rating# tag with #$score# in mine.  Here's how:

In user-summary-reviews.xd I replaced:

<xar:if condition="!empty($rating)">
    - <xar:mlstring>rating</xar:mlstring> : #$rating#
</xar:if>

with

<xar:if condition="!empty($score)">
    - <xar:mlstring>Score</xar:mlstring> : #$score#
</xar:if>

In user-display-reviews.xd I replaced:

<tr><td align="right">
Rating:
</td><td align="left">
#$rating#
</td></tr>

with

<tr><td align="right">
Score:
</td><td align="left">
#$score#
</td></tr>

An alternative way to show the score is through the following:

<xar:data-getitem name="$properties" module="articles" itemtype="3" 
itemid="$aid" />
<xar:data-output property="$properties['score']" />

At this stage you can leave the name set as $properties for most dynamic data 
displays.  

Module refers to the module that we're associating the dynamic data with - in 
this case articles.  

Itemtype can be found by going to Admin->DynamicData->ViewObjects.  

In this case the itemtype for reviews was "3".  Unless you've altered/created 
pubtypes yours should be too.  You'll also notice on the page that you get by 
going to Admin->DynamicData->ViewObjects that the table shows the listing of 
dynamic data objects and that the label and name for reviews is articles_3.  
The '_3' refers to the itemtype but it's also mentioned on that page under 
the very appropriately named heading itemtype. 

Itemid in this case is set at $aid which is the article id.

When we're outputing the data we want to show the relevant property so we 
include the $properties['score'].  Score is the name of the label that we 
used for this dynamic data.

If you've overriden the reviews template in your themes you'll need to alter 
all those templates as well.
This should allow your scores to be shown.

3.3 Scores in Reviews
Now when you write a review you should have a dropdown list of scores 
available.  Just write your review, select the relevant score and you're 
away.  The score should show up when you read the review.

That's it.
---HOWTO ends---
-- 
Public key information available at:
http://www.amber.com.au/~skribe/publickey.html
Key fingerprint = A855 9CA3 953B 5195 C518  12F2 0E05 DCCD 5A88 E8A4 

Take everything in stride.  Trample anyone who gets in your way.

Xaraya Content Management Solutions http://www.xaraya.com/