Class:SmartestCmsItem

From The Smartest Wiki
Jump to: navigation, search

SmartestCmsItem is the main class from which all items, including their properties and values, are built. It implements a DataObject/ARS-type way of working with the data stored in items.

SmartestCmsItem is almost never instantiated itself - rather, it is extended by auto-generated classes in System/Cache/ObjectModel/Models/, which are in turn extended by one-time auto-generated user-editable classes in either Library/ObjectModel/ (shared models) or Sites/SITENAME/Library/ObjectModel/ for site-specific models. This way, every model class is an instance of the SmartestCmsItem class and thus inherits its functionality. Each SmartestCmsItem object contains an instance of SmartestItem tied to the database row in the Items table where the item's core information (but not properties) are stored.

Besides the offsets and get/set methods that are specific to each model, the underlying SmartestCmsItem class also provides functionalities that are available to all its subclasses:

Offsets

SmartestString $obj.name - provides the value from the getName() method, meaning that if this method is overridden for a specific model, the behaviour of this offset also changes.

string $obj._editor_name - provides the value of the built-in name field, regardless of the getName() method.

string $obj._php_class - provides the class name of the current object.

string $obj._type_label - returns the name of the model. This is part of a broader system-wide API whereby objects that are listed together have a harmonised set of offsets and available information about them so that they can be distinguished.

string $obj._type_varname = returns the name of the model in varname format.

bool $obj.has_tag - Allows you to check in a template whether the given object has the specified tag, referred to by its short name/slug:

<?sm:if $item.has_tag.politics:?><p>This item is tagged "politics"</p><?sm:/if:?>

Note that offsets are always in varname format (underscores; lower case), while tag short names are in slug format (dashes/hyphens; lowercase). In this case, you can substitute a hyphen for a dash and the check will still work:

<!--Tag is food-drink-->
<?sm:if $item.has_tag.food_drink:?><p>This item is tagged "Food & drink"</p><?sm:/if:?>

string $object.tags_cs_string - returns a string containing comma-separated names of the tags applied to the object.

bool $obj._is_linkable - Returns whether the object has an available meta-page, and thus can be linked to.

string $obj.url or $obj.permalink returns the live url (the default if there is more than one) of the item, if it is linkable.

string $obj.absolute_uri or $obj.absolute_url - returns the full URL of the object, including protocol and hostname.

string $obj._description returns the description field contents. If a property called description actually exists, it will not necessarily use that: A property can be selected for each model that should be used as its description in this case. The advantage of this is that with mixed lists, this same _description offset could be used to display item descriptions and synopses, regardless of the name of the actual property. If no property is selected, and there is a property called Description, that property will be used.

SmartestDateTime$obj._auto_date similar to the _description offset above, returns the value of any property that is selected as the model's date property (revision 834 onwards), or if this is not set, the value of any property called "Date published" (varname date_published), or if that does not exist, the built-in date the item was last published.

string $obj._auto_date_raw retrieves the same value as _auto_date but formatted as a unix time integer.

SmartestRenderableAsset $obj._auto_thumbnail Returns the value of whichever property is selected as the default thumbnail property, much like _auto_date and _description.

SmartestBoolean $obj._is_published Tells you whether or not the item is published at the moment.

string $obj._byline A quick way to print an unlinked byline, generated from the authors selected under the Authors tab in Smartest.

SmartestModel $obj._model retrieves the model that this item is created with.

SmartestSIte $obj._site retrieves the site where this item was created

Methods

array getPropertyVarNames() returns all the model's property names in varname format.

void setDraftMode($mode) - allows you to tell the item to behave as it would in preview mode and to retrieve data from the site and about itself accordingly.

bool getDraftMode() - allows you to know whether the item is currently in draft mode.

string getModelVarname() - returns the name of the item's model in varname format.

void setSiteId($site_id) only used when creating the item: allows you to set which site the item belongs to.

int getSiteId() allows you to get the ID of the site the item belongs to.

SmartestSite getSite() returns the site that the item belongs to.

int getMetapageId() returns the ID of the default meta-page that will be used to display the item, if any. Returns null if no metapage exists or none has been chosen.

SmartestPage getMetaPage() - returns the actual meta-page as an object.

bool isLinkable() Returns true if a viable meta-page can be found, otherwise false.

SmartestRenderableAsset getDefaultThumbnailImage() if a property has been selected as the default thumbnail property for the item's model, returns the value of that property, otherwise returns null.

bool find($id) Looks up an item by ID, retrieves all data from the database and populates the object (and property and property value objects) to make the item ready to use. Returns false if the ID was not found.

bool findBy($field_name, $field_value) allows you to look up an item by another unique built-in field such as name or long ID. Retrieves all data from the database and populates the object (and property and property value objects) to make the item ready to use. Returns false if the ID was not found.

int getId() returns the item's main ID, which is its primary key in the database field item_id.

string getName() returns the item's built in name field. If the item is unpublished and is being viewed in the web page preview, an asterisk is appended to the beginning of the name to denote the unpublished status.

void setName($name) sets the item's built-in name field.

void setSlug($slug) sets the item's short name/slug field (used in URLs, etc; lowercase, with hyphens and no spaces or underscores); Casts accented characters such as é to their non-accented equivalents using SmartestStringHelper::toAscii()

void setIsPublic($visibility) Sets the public visibility of the item.

void setLanguage($language_code) Sets the built-in language code for the item.

string getDate() returns the value of any property that is selected as the model's date property (revision 834 onwards), or if this is not set, the value of any property called "Date published" (varname date_published), or if that does not exist, the built-in date the item was last published.

mixed getDescription() or mixed getDescriptionFieldContents() returns the content of the automatic description field. This is the value of the property chosen as the default description field. If this property is a file property, a SmartestRenderableAsset object will be returned, otherwise a string.

string __toJson() - returns the object as JSON. Not completed.

mixed getPropertyValueByNumericKey($key, $draft_mode) - returns the value of an item property by its numeric key, as opposed to using property-specific methods.