Odyssey | Το Ελληνικό CMS | Δημιουργώντας ένα απλό module

ODYSSEY CMS

Ενθέματα (modules ή widgets)

Δημιουργώντας ένα απλό module

Δημοσιεύτηκε : 22/12/2012

Στο άρθρο αυτό θα δούμε πώς μπορούμε να δημιουργήσουμε ένα πολύ απλό module από το μηδέν! Θα ακολουθήσουμε την πεπατημένη του Hello World και θα δημιουργήσουμε ένα module που απλά θα εμφανίζει το διάσημο πλέον μήνυμα. Αυτό που κάνει ενδιαφέρον αυτό το module, είναι οι δυνατότητες παραμετροποίησης που θα του προσθέσουμε. Οι συγκεκριμένες ρυθμίσεις θα μας δίνουν την δυνατότητα να ορίζουμε την γραμματοσειρά, το μέγεθος και το χρώμα με τα οποία θα εμφανίζεται αυτό το μήνυμα.

Ακολουθώντας αυτό το tutorial, θα έχετε μάθει πώς αρχίζουμε από το μηδέν την δημιουργία ενός module, πώς δημιουργούμε το archive εγκατάστασης, πώς το εγκαθιστούμε και πώς το εισάγουμε στο template μας παραμετροποιώντας τις διαθέσιμες ρυθμίσεις του!

Προετοιμασία του module

Για τις ανάγκες του testing όλων των σταδίων της ανάπτυξης (development) του module, αυτό πρέπει να είναι ήδη ενσωματωμένο στο template μας! Για το λόγο αυτό, στην αρχή πρέπει να δημιουργήσουμε ένα empty module, να το μετατρέψουμε σε zip archive, να το εγκαταστήσουμε και να το ενσωματώσουμε στο template μας. Τότε θα συνεχίσουμε την ανάπτυξη του μέσα από τον φάκελο εγκατάστασής του.

Αρχίζοντας θα πρέπει να έχουμε καταλήξει στο system name του module μας. Στην περίπτωση αυτή θα το ονομάσουμε hello_world. Το όνομα αυτό θα το χρησιμοποιήσουμε ως τιμή στην παράμετρο name του XML, και ως όνομα του php αρχείου του module.
Κατεβάζουμε το δείγμα του XML για έναρξη νέου module και αφού το αποσυμπιέσουμε το ονομάζουμε install.xml.
Δημιουργούμε στο ίδιο σημείο με το install.xml και ένα php αρχείο με όνομα hello_world.php.
Ως περιεχόμενα εισάγουμε τον ακόλουθο κώδικα:

<?php
//define this module's name
$mn = "module_system_name";
include("modules/modules.php");

/*
Available variables:
All system classes
All request variables
$p (the template path)
$mp (the module path)
$sufixID (id sufix for this module's divs)
*/
$marginTop = ($moduleParameters['marginTop'] == "__EMPTY__" || empty($moduleParameters['marginTop'])) ? 0 : $moduleParameters['marginTop'];
$marginRight = ($moduleParameters['marginRight'] == "__EMPTY__" || empty($moduleParameters['marginRight'])) ? 0 : $moduleParameters['marginRight'];
$marginBottom = ($moduleParameters['marginBottom'] == "__EMPTY__" || empty($moduleParameters['marginBottom'])) ? 0 : $moduleParameters['marginBottom'];
$marginLeft = ($moduleParameters['marginLeft'] == "__EMPTY__" || empty($moduleParameters['marginLeft'])) ? 0 : $moduleParameters['marginLeft'];
$paddingTop = ($moduleParameters['paddingTop'] == "__EMPTY__" || empty($moduleParameters['paddingTop'])) ? 0 : $moduleParameters['paddingTop'];
$paddingRight = ($moduleParameters['paddingRight'] == "__EMPTY__" || empty($moduleParameters['paddingRight'])) ? 0 : $moduleParameters['paddingRight'];
$paddingBottom = ($moduleParameters['paddingBottom'] == "__EMPTY__" || empty($moduleParameters['paddingBottom'])) ? 0 : $moduleParameters['paddingBottom'];
$paddingLeft = ($moduleParameters['paddingLeft'] == "__EMPTY__" || empty($moduleParameters['paddingLeft'])) ? 0 : $moduleParameters['paddingLeft'];
$useModuleContainer = ($moduleParameters['useModuleContainer'] == "__EMPTY__" || empty($moduleParameters['useModuleContainer'])) ? 0 : (int)$moduleParameters['useModuleContainer'];
$widthInPixels = ($moduleParameters['widthInPixels'] == "__EMPTY__" || empty($moduleParameters['widthInPixels'])) ? null : (int)$moduleParameters['widthInPixels'];


if(empty($marginTop) && empty($marginRight) && empty($marginBottom) && empty($marginLeft)){
	$Mmargin = "0";
}else{
	$Mmargin = $marginTop." ".$marginRight." ".$marginBottom." ".$marginLeft." ";
}
if(empty($paddingTop) && empty($paddingRight) && empty($paddingBottom) && empty($paddingLeft)){
	$Mpadding = "0";
}else{
	$Mpadding = $paddingTop." ".$paddingRight." ".$paddingBottom." ".$paddingLeft." ";
}

if($useModuleContainer ){

?>

<div id="<?php echo $mn.$sufixID;?>" data-editable="editable">
<?php
if($moduleParameters['moduleAlign'] && $moduleParameters['moduleHR']){ // there are system parameters...
?>
<style scoped type="text/css">
#<?php echo $mn.$sufixID;?>{
	text-align: <?php echo $moduleParameters['moduleAlign'];?>;
	margin : <?php echo $Mmargin;?>;
	padding : <?php echo $Mpadding;?>;
<?php
if($widthInPixels){
	?>
	width: <?php echo $widthInPixels;?>px;
	<?php 
}
if($moduleParameters['moduleHR'] == "top" || $moduleParameters['moduleHR'] == "bottom"){
?>
	border-<?php echo $moduleParameters['moduleHR'];?> : 1px solid black;
<?php 
}
?>
}
</style>
<?php 
}
}
// here goes your module's php code






// here end your module's php code
if($useModuleContainer ){
?>
</div>
<?php
}
?>

Στην δεύτερη γραμμή ορίζουμε στην μεταβλητή $mn (module name) το όνομα του module μας, αντικαθιστώντας το

$mn = "module_system_name";

με το

$mn = "hello_world";

Στον υπόλοιπο κώδικα δεν κάνουμε κάποια άλλη αλλαγή και μπορούμε να αρχίσουμε να προσθέτουμε τον δικό μας κώδικα ανάμεσα στα ακόλουθα σχόλια που θα βρούμε στο κάτω μέρος του υπάρχοντος περιεχομένου:

// here goes your module's php code






// here end your module's php code

Πριν συνεχίσουμε με τον php κώδικα, πάμε να ολοκληρώσουμε το install.xml στο οποίο θα ορίσουμε τις παραμέτρους που θέλουμε (γραμματοσειρά, μέγεθος, χρώμα) για το μήνυμα Hello World. Για αρχή τροποποιήστε το XML ώστε να μοιάζει με το ακόλουθο, φροντίζοντας να προσθέσετε το όνομα σας ως συγγραφέα στο <author></author>:

<?xml version="1.0" encoding="utf-8" ?>
<install type="module">
	<name>hello_world</name>
	<title>The Hello World Module</title>
	<protected>0</protected>
	<version>1.0</version>
	<author></author>	
	<files>
		<file type="root">hello_world.php</file>
	</files>			
	<params>
		<param type="textfield" size="10" name="marginTop" label="marginTop" description="Το άνω εξωτερικό περιθώριο του ενθέματος">0</param>
		<param type="textfield" size="10" name="marginRight" label="marginRight" description="Το δεξί εξωτερικό περιθώριο του ενθέματος">0</param>
		<param type="textfield" size="10" name="marginBottom" label="marginBottom" description="Το κάτω εξωτερικό περιθώριο του ενθέματος">0</param>
		<param type="textfield" size="10" name="marginLeft" label="marginLeft" description="Το αριστερό εξωτερικό περιθώριο του ενθέματος">0</param>
		<param type="textfield" size="10" name="paddingTop" label="paddingTop" description="Το άνω εσωτερικό περιθώριο του ενθέματος">0</param>
		<param type="textfield" size="10" name="paddingRight" label="paddingRight" description="Το δεξί εσωτερικό περιθώριο του ενθέματος">0</param>
		<param type="textfield" size="10" name="paddingBottom" label="paddingBottom" description="Το κάτω εσωτερικό περιθώριο του ενθέματος">0</param>
		<param type="textfield" size="10" name="paddingLeft" label="paddingLeft" description="Το αριστερό εσωτερικό περιθώριο του ενθέματος">0</param>	
		<param type="checkbox" name="useModuleContainer" label="useModuleContainer" description="Να εσωκλείεται το περιεχόμενο μέσα σε container. Χωρίς αυτό κάποιες παραμετροποιήσεις δεν θα είναι εφικτές">1</param>				
		<param type="textfield" size="10" name="widthInPixels" label="widthInPixels" description="Πλάτος του module container σε pixels"></param>	

<!-- Start of custom module parameters -->


		
<!-- End of custom module parameters -->				
		
		<param type="select" default="center" name="moduleAlign" label="moduleAlign" description="Η στοίχιση με την οποία θα εμφανίζεται το ένθεμα">
			<item value="left">αριστερά</item>
			<item value="center">κέντρο</item>
			<item value="right">δεξιά</item>
		</param>
		<param type="select" default="none" name="moduleHR" label="moduleHR" description="Εμφάνιση διαχωριστικού hr στο ένθεμα">
			<item value="none">χωρίς διαχωριστικό</item>
			<item value="top">επάνω διαχωριστικό</item>
			<item value="bottom">κάτω διαχωριστικό</item>
		</param>
	</params>
</install>

Δημιουργία archive εγκατάστασης

Στο σημείο αυτό έχουμε όλα τα απαραίτητα στοιχεία ώστε να δημιουργήσουμε ένα installation zip archive, να εγκαταστήσουμε το module στο Odyssey και να συνεχίσουμε την ανάπτυξη του κώδικα μέσα από το περιβάλλον της πλατφόρμας μας.

Συμπεριλαμβάνουμε λοιπόν τα δύο αρχεία μας (install.xml & hello_world.php) σε ένα zip αρχείο με όνομα module_hello_world.zip ακολουθώντας τις ίδιες οδηγίες για την δημιουργία zip στην ενότητα templates.

Εγκατάσταση & παραμετροποίηση

Στη συνέχεια θα εγκαταστήσουμε το νέο μας module στο Odyssey. Από τον πίνακα διαχείρισης αφού επιλέξουμε ΔΙΑΧΕΙΡΙΣΗ ΕΜΦΑΝΙΣΗΣ -> ΕΝΘΕΜΑΤΑ ΣΕΛΙΔΑΣ -> ΕΓΚΑΤΑΣΤΑΣΗ ΝΕΟΥ ΕΝΘΕΜΑΤΟΣ θα ολοκληρώσουμε την διαδικασία ορίζοντας το zip αρχείο μας στο ζητούμενο αρχείο εγκατάστασης. Ακολούθως θα πρέπει να το ενσωματώσουμε στο template μας επιλέγοντας ΔΙΑΧΕΙΡΙΣΗ ΕΜΦΑΝΙΣΗΣ -> ΕΝΘΕΜΑΤΑ ΣΕΛΙΔΑΣ -> ΔΙΑΧΕΙΡΙΣΗ ΕΝΘΕΜΑΤΩΝ. Στη σελίδα αυτή βλέπουμε μια λίστα με όλα τα ενθέματα που χρησιμοποιούνται στο τρέχον template. Δεξιά υπάρχει η επιλογή «Προσθήκη νέου ενθέματος», και μέσω αυτής θα οδηγηθούμε σε ένα αναδυόμενο παράθυρο όπου πρέπει να επιλέξουμε το δικό μας.

Με τον τρόπο αυτό περνάμε στο παράθυρο παραμετροποίησης του module, ώστε να το ενσωματώσουμε στο template μας. Υποθέτοντας πως έχετε το default template του Odyssey, θα ορίσουμε ως σημείο εμφάνισης (slot) το Copyright Links ώστε να εμφανιστεί χαμηλά στο footer μας. Επίσης θα επιλέξουμε να εμφανίζεται μόνο στην ενότητα ΑΡΧΙΚΗ ΣΕΛΙΔΑ για τις ανάγκες των δοκιμών μας. Αφού ολοκληρώσετε τις συγκεκριμένες επιλογές πατήστε Αποθήκευση ώστε να ολοκληρωθεί η διαδικασία. Από το σημείο αυτό θα πρέπει να συνεχίσουμε την ανάπτυξη του module με τα εγκατεστημένα αρχεία!

Πού όμως θα βρούμε το xml και το php αρχείο μας;

Επεξεργασία των αρχείων

Το xml θα το βρούμε στον φάκελο συστήματος «modules» στο root της εγκατάστασής μας, με ένα νέο όνομα. Το Odyssey μετονομάζει πάντα το xml εγκατάστασης σε ένα όνομα που αποτελείται από το system name του module και το επίθεμα _install. Στην περίπτωση μας θα το βρούμε ως hello_world_install.xml και θα το ανοίξουμε για επεξεργασία.

Το php αρχείο μας θα το βρούμε σε ένα άλλο φάκελο «modules» που θα βρείτε μέσα στον φάκελο του τρέχοντος template. Η διαδρομή είναι templates/[template_name]/modules/hello_world/hello_world.php

Αυτό συμβαίνει μόνο για όσα modules έχουν στο xml τους την παράμετρο protected ίση με μηδέν (<protected>0</protected>). Σε αντίθετη περίπτωση το module ορίζεται ως system module (κοινόχρηστο για όλα τα templates) και θα το βρίσκατε στον πρώτο φάκελο όπου αποθηκεύτηκε και το xml της εγκατάστασης.

Αφού εντοπίσουμε το php αρχείο, το ανοίγουμε κι αυτό για επεξεργασία.

Πρώτα θα ολοκληρώσουμε το xml ώστε να του προσθέσουμε τις δικές μας παραμέτρους. Για την γραμματοσειρά θα επιλέξουμε τύπο select (λίστα επιλογής), για το χρώμα τύπο colorpicker (επιλογέα χρωμάτων) και για το μέγεθος ένα τύπο textfield (πεδίο κειμένου).
Προσθέστε τις παραμέτρους που ακολουθούν στο σημείο του xml που μας υποδεικνύουν τα σχετικά σχόλια.

<!-- Start of custom module parameters -->
		<param type="select" default="Verdana, Geneva, sans-serif" name="fontFamily" label="fontFamily" description="Η γραμματοσειρά του μηνύματος">
			<item value="Verdana, Geneva, sans-serif">Verdana</item>
			<item value="Georgia, 'Times New Roman', Times, serif">Georgia</item>
			<item value="Arial, Helvetica, sans-serif">Arial</item>
			<item value="Tahoma, Geneva, sans-serif">Tahoma</item>
		</param>
		<param type="colorpicker" name="fontColor" label="fontColor" description="Το χρώμα της γραμματοσειράς του μηνύματος">000000</param>
		<param type="textfield" size="5" name="fontSize" label="fontSize" description="Το μέγεθος σε pixels της γραμματοσειράς του μηνύματος">18px</param>	
<!-- End of custom module parameters -->

Τώρα αν μεταβούμε από τον πίνακα διαχείρισης στα ενθέματα και επιλέξουμε το νέο μας module, θα δούμε πως έχουμε στην διάθεση μας τρεις επιπλέον παραμέτρους, την γραμματοσειρά, το χρώμα και το μέγεθος του μηνύματος Hello World. Επιλέξτε τις τιμές που επιθυμείτε και πατήστε Αποθήκευση.

Τέλος θα προσθέσουμε και το κώδικα που θα τυπώνει το μήνυμα σύμφωνα με αυτές τις παραμέτρους στο php αρχείο μας. Στο σημείο που μας υποδεικνύουν τα σχόλια, προσθέτουμε τον ακόλουθο κώδικα:

// here goes your module's php code

$fontFamily = $moduleParameters['fontFamily'];
$fontColor = ($moduleParameters['fontColor']) ? "#".$moduleParameters['fontColor'] : null;
$fontSize = $moduleParameters['fontSize'];
if(!preg_match('/px$/', $fontSize)) $fontSize = (int)$fontSize."px"; // προσθέτουμε το επίθεμα px αν δεν έχει δοθεί
?>
<div style="font-family: <?php echo $fontFamily; ?>; color: <?php echo $fontColor; ?>; font-size: <?php echo $fontSize; ?>">Hello World!</div>
<?php

// here end your module's php code

Όπως βλέπετε, οι παράμετροι του xml είναι διαθέσιμες στο php αρχείο μας μέσω του πίνακα $moduleParameters και κάθε τιμή είναι αποθηκευμένη με array key το όνομα της παραμέτρου.
Είναι καλή πρακτική να δημιουργούμε τοπικές μεταβλητές με ονόματα ίδια σαν τα keys, ώστε να τα χρησιμοποιούμε πιο εύκολα. Επίσης στο στάδιο αυτό γίνεται και ο τελικός έλεγχος και το φιλτράρισμα. Για παράδειγμα προσθέτουμε το πρόθεμα # στην δεκαεξαδική τιμή του χρώματος και ελέγχουμε αν ο χρήστης έχει χρησιμοποιήσει το επίθεμα px (αν όχι το προσθέτουμε με μια απλή συνθήκη).
Τέλος τυπώνουμε το μήνυμα κάνοντας χρήση των τιμών των παραμέτρων ως inline css styles (θα μπορούσαμε επίσης να δημιουργήσουμε μια css class και να δώσουμε ως τιμές των rules, τις τιμές των παραμέτρων μας).

Όταν αποθηκεύσετε το php αρχείο και κάνετε ένα refresh στην αρχική σας σελίδα, θα δείτε στο footer το Hello World! σύμφωνα με τις παραμέτρους που ορίσατε...

Να θυμάστε πως για πιο σύνθετες εφαρμογές, στο συγκεκριμένο php αρχείο, σας είναι πάντα διαθέσιμες:

Όλες οι κλάσεις του Odyssey API
Όλες οι μεταβλητές του page request (φιλτραρισμένες)
η $p που περιέχει το path προς το template σας
η $mp που περιέχει το path του module

Όταν βεβαιωθείτε πως όλα λειτουργούν όπως επιθυμείτε, δημιουργείτε το τελικό zip archive εγκατάστασης για μελλοντική χρήση...

επιστροφή