1: <?php
  2: /**
  3:  * Class QHListControl
  4:  *
  5:  * A control that lets you dynamically create an html unordered or ordered hierarchical list with
  6:  * sub-lists. These structures are often used as the basis for javascript widgets like
  7:  * menu bars.
  8:  *
  9:  * Also supports data binding. When using the data binder, it will recreate the item list each time it draws,
 10:  * and then delete the item list so that the list does not get stored in the formstate. It is common for lists like
 11:  * this to associate items in a database with items in a list through the value attribute of each item.
 12:  * In an effort to make sure that database ids are not exposed to the client (for security reasons), the value
 13:  * attribute is encrypted.
 14:  *
 15:  * @property string     $Tag            Tag for main wrapping object
 16:  * @property string     $ItemTag        Tag for each item
 17:  * @property bool       $EncryptValues  Whether to encrypt the values that are printed in the html. Useful if the values
 18:  *                                      are something you want to publicly hide, like database ids. True by default.
 19:  */
 20: 
 21: 
 22: class QHListControl extends QControl {
 23: 
 24:     use QListItemManager, QDataBinder;
 25: 
 26:     /** @var string  top level tag */
 27:     protected $strTag = 'ul';
 28:     /** @var string  item tag */
 29:     protected $strItemTag = 'li';
 30:     /** @var null|QListItemStyle The common style for all elements in the list */
 31:     protected $objItemStyle = null;
 32:     /** @var null|QCryptography the temporary cryptography object for encrypting database values sent to the client */
 33:     protected $objCrypt = null;
 34:     /** @var bool Whether to encrypt values */
 35:     protected $blnEncryptValues = true;
 36: 
 37:     /**
 38:      * Adds an item to the list.
 39:      *
 40:      * @param QHListItem|string $mixListItemOrName
 41:      * @param null|string $strValue
 42:      * @param null|string $strAnchor
 43:      */
 44:     public function AddItem($mixListItemOrName, $strValue = null, $strAnchor = null) {
 45:         if (gettype($mixListItemOrName) == QType::Object) {
 46:             $objListItem = QType::Cast($mixListItemOrName, "QHListItem");
 47:         }
 48:         else {
 49:             $objListItem = new QHListItem($mixListItemOrName, $strValue, $strAnchor);
 50:         }
 51: 
 52:         $this->AddListItem ($objListItem);
 53:     }
 54: 
 55:     /**
 56:      * Adds an array of items to the list. The array can also be an array of key>val pairs
 57:      * @param array $objItemArray   An array of QHListItems or key=>val pairs to be sent to constructor.
 58:      */
 59:     public function AddItems($objItemArray) {
 60:         if (!$objItemArray) return;
 61: 
 62:         if (!is_object(reset($objItemArray))) {
 63:             foreach ($objItemArray as $key=>$val) {
 64:                 $this->AddItem ($key, $val);
 65:             }
 66:         } else {
 67:             $this->AddListItems ($objItemArray);
 68:         }
 69:     }
 70: 
 71:     /**
 72:      * This is not a typical input control, so there is no post data to read.
 73:      */
 74:     public function ParsePostData() {}
 75: 
 76:     /**
 77:      * Validate the submitted data
 78:      * @return bool
 79:      */
 80:     public function Validate() {return true;}
 81: 
 82:     /**
 83:      * Return the id. Used by QListItemManager trait.
 84:      * @return string
 85:      */
 86:     public function GetId() {
 87:         return $this->strControlId;
 88:     }
 89: 
 90:     /**
 91:      * Returns the HTML for the control and all subitems.
 92:      * 
 93:      * @return string
 94:      */
 95:     public function GetControlHtml() {
 96:         $strHtml = '';
 97:         if ($this->HasDataBinder()) {
 98:             $this->CallDataBinder();
 99:         }
100:         if ($this->GetItemCount()) {
101:             $strHtml = '';
102:             foreach ($this->GetAllItems() as $objItem) {
103:                 $strHtml .= $this->GetItemHtml($objItem);
104:             }
105: 
106:             $strHtml = $this->RenderTag($this->strTag, null, null, $strHtml);
107:         }
108:         if ($this->HasDataBinder()) {
109:             $this->RemoveAllItems();
110:         }
111: 
112:         return $strHtml;
113:     }
114: 
115:     /**
116:      * Return the html to draw an item.
117:      *
118:      * @param mixed $objItem
119:      * @return string
120:      */
121:     protected function GetItemHtml ($objItem) {
122:         $strHtml = $this->GetItemText($objItem);
123:         $strHtml .= "\n";
124:         if ($objItem->GetItemCount()) {
125:             $strSubHtml = '';
126:             foreach ($objItem->GetAllItems() as $objSubItem) {
127:                 $strSubHtml .= $this->GetItemHtml($objSubItem);
128:             }
129:             $strTag = $objItem->Tag;
130:             if (!$strTag) {
131:                 $strTag = $this->strTag;
132:             }
133:             $strHtml .= QHtml::RenderTag($strTag, $this->GetSubTagAttributes($objItem), $strSubHtml);
134:         }
135:         $objStyler = $this->GetItemStyler($objItem);
136:         $strHtml = QHtml::RenderTag($this->strItemTag, $objStyler->RenderHtmlAttributes(), $strHtml);
137: 
138:         return $strHtml;
139:     }
140: 
141:     /**
142:      * Return the text html of the item.
143:      *
144:      * @param mixed $objItem
145:      * @return string
146:      */
147:     protected function GetItemText ($objItem) {
148:         $strHtml = QApplication::HtmlEntities($objItem->Text);
149: 
150:         if ($strAnchor = $objItem->Anchor) {
151:             $strHtml = QHtml::RenderTag('a', ['href' => $strAnchor], $strHtml, false, true);
152:         }
153:         return $strHtml;
154:     }
155: 
156:     /**
157:      * Return the item styler for the given item. Combines the generic item styles found in this class with
158:      * any specific item styles found in the item.
159:      *
160:      * @param mixed $objItem
161:      * @return QListItemStyle
162:      */
163:     protected function GetItemStyler ($objItem) {
164:         if ($this->objItemStyle) {
165:             $objStyler = clone $this->objItemStyle;
166:         }
167:         else {
168:             $objStyler = new QListItemStyle();
169:         }
170:         $objStyler->SetHtmlAttribute('id', $objItem->Id);
171: 
172:         // since we are going to embed the value in the tag, we are going to encrypt it in case its a database record id.
173:         if ($objItem->Value) {
174:             if ($this->blnEncryptValues) {
175:                 $strValue = $this->EncryptValue($objItem->Value);
176:             } else {
177:                 $strValue = $objItem->Value;
178:             }
179:             $objStyler->SetDataAttribute('value', $strValue);
180:         }
181:         if ($objStyle = $objItem->ItemStyle) {
182:             $objStyler->Override($objStyle);
183:         }
184:         return $objStyler;
185:     }
186: 
187:     /**
188:      * Return the encrypted value of the given object
189:      *
190:      * @param string $value
191:      * @return string
192:      */
193:     protected function EncryptValue($value) {
194:         if (!$this->objCrypt) {
195:             $this->objCrypt = new QCryptography(null, true);
196:         }
197:         return $this->objCrypt->Encrypt($value);
198:     }
199: 
200:     /**
201:      * Return the decrypted value of the given value string.
202:      *
203:      * @param $strEncryptedValue
204:      * @return string
205:      */
206:     public function DecryptValue ($strEncryptedValue) {
207:         if (!$this->objCrypt) {
208:             $this->objCrypt = new QCryptography(null, true);
209:         }
210:         return $this->objCrypt->Decrypt($strEncryptedValue);
211:     }
212: 
213:     /**
214:      * Return the attributes for the sub tag that wraps the item tags
215:      * @param mixed $objItem
216:      * @return array|null|string
217:      */
218:     protected function GetSubTagAttributes($objItem) {
219:         return $objItem->GetSubTagStyler()->RenderHtmlAttributes();
220:     }
221: 
222: 
223:     /////////////////////////
224:     // Public Properties: GET
225:     /////////////////////////
226:     /**
227:      * PHP magic function
228:      * @param string $strName
229:      *
230:      * @return mixed
231:      * @throws Exception|QCallerException
232:      */
233:     public function __get($strName) {
234:         switch ($strName) {
235:             // APPEARANCE
236:             case "Tag": return $this->strTag;
237:             case "ItemTag": return $this->strItemTag;
238:             case "EncryptValues": return $this->blnEncryptValues;
239:             default:
240:                 try {
241:                     return parent::__get($strName);
242:                 } catch (QCallerException $objExc) {
243:                     $objExc->IncrementOffset();
244:                     throw $objExc;
245:                 }
246:         }
247:     }
248: 
249:     /////////////////////////
250:     // Public Properties: SET
251:     /////////////////////////
252:     /**
253:      * PHP magic method
254:      * @param string $strName
255:      * @param string $mixValue
256:      *
257:      * @return mixed
258:      * @throws Exception|QCallerException|QInvalidCastException
259:      */
260:     public function __set($strName, $mixValue) {
261:         switch ($strName) {
262:             // APPEARANCE
263:             case "Tag":
264:                 try {
265:                     $this->strTag = QType::Cast($mixValue, QType::String);
266:                     break;
267:                 } catch (QInvalidCastException $objExc) {
268:                     $objExc->IncrementOffset();
269:                     throw $objExc;
270:                 }
271:             case "ItemTag":
272:                 try {
273:                     $this->strItemTag = QType::Cast($mixValue, QType::String);
274:                     break;
275:                 } catch (QInvalidCastException $objExc) {
276:                     $objExc->IncrementOffset();
277:                     throw $objExc;
278:                 }
279: 
280:             case "EncryptValues":
281:                 try {
282:                     $this->blnEncryptValues = QType::Cast($mixValue, QType::Boolean);
283:                     break;
284:                 } catch (QInvalidCastException $objExc) {
285:                     $objExc->IncrementOffset();
286:                     throw $objExc;
287:                 }
288: 
289: 
290:             default:
291:                 try {
292:                     parent::__set($strName, $mixValue);
293:                 } catch (QCallerException $objExc) {
294:                     $objExc->IncrementOffset();
295:                     throw $objExc;
296:                 }
297:                 break;
298:         }
299:     }
300: 
301: }
302: 
303: