MINOR API CHANGE SUGGESTIONS

[masterchief]

READ THIS FIRST BEFORE POSTING

The purpose of this thread is collect suggestions from Developers about very minor changes to the Joomla API that are too insignificant to warrant the writing of a full White Paper.

Please post only one change per reply.
Please edit the subject of your reply to reflect what your suggestion is about.

Posts that are deemed to have more than a minor impact and that will need a White Paper will be split out.

[masterchief]

File(s):
/library/joomla/error/error.php

Changes:
The $code argument in the following methods:
JError::raise
JError::raiseNotice
JError::raiseWarning
JError::raiseError

should be able to accept a JException object natively.

This only needs on method change in JError::raise to something like:

Code: Select all

	/**
	 * Create a new JException object given the passed arguments
	 *
	 * @static
	 * @param	int		$level	The error level - use any of PHP's own error levels for this: E_ERROR, E_WARNING, E_NOTICE, E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE.
	 * @param	mixed	$code	The application-internal error code for this error, or a JException object
	 * @param	string	$msg	The error message, which may also be shown the user if need be.
	 * @param	mixed	$info	Optional: Additional error information (usually only developer-relevant information that the user should never see, like a database DSN).
	 * @return	mixed	The JException object
	 * @since	1.5
	 *
	 * @see		JException
	 */
	function & raise($level, $code, $msg='', $info = null, $backtrace = false)
	{
		jimport('joomla.error.exception');

		// build error object
		$exception = is_a( $code, 'JException' ) ? $code : new JException($msg, $code, $level, $info, $backtrace);

This would allow a developer to pass back JException objects from deep within extension logic, and pass that object to JError::raise (or similar) without the need to disassemble the object.

[RoscoHead]

See http://forum.joomla.org/viewtopic.php?f=38&t=253009

I would like the filelist and folderlist parameter elements to be able to accept something like "blah_(.*)\.php" in the filter attribute and have the list populated with the first matched subpattern instead of the whole file/folder name.

ROSCO

[RoscoHead]

See: http://forum.joomla.org/viewtopic.php?f=38&t=252107

I would like the extension installer to automatically create the index.html file in each sub-directory as it installs the extension. There could be an optional noindex attribute in the <folder> tag that is either yes or no, and defaults to no. This would save having to include all those copies of index.html in the extension ZIP, and also many lines in the install file.

ROSCO

[masterchief]

IMPLEMENTED $sql is cast as a string allowing an object implementing __toString to be used.

File(s):
/libraries/joomla/database/database.php

This change involves making a forward compatible change in the event that Developers implement a Query Class. The change is simply to access whether the $sql argument is an object an has a toString method.

The required change might be:

Code: Select all

	/**
	 * Sets the SQL query string for later execution.
	 *
	 * This function replaces a string identifier <var>$prefix</var> with the
	 * string held is the <var>_table_prefix</var> class variable.
	 *
	 * @access public
	 * @param string The SQL query
	 * @param string The offset to start selection
	 * @param string The number of results to return
	 * @param string The common table prefix
	 */
	function setQuery( $sql, $offset = 0, $limit = 0, $prefix='#__' )
	{
		if (is_object( $sql ))
		{
			if (method_exists( $sql, 'toString )) {
				$sql = $sql->toString();
			} else {
				// possible raise an error ??
			}
		}

[masterchief]

COMMITTED

File(s):
/libraries/joomla/application/component/model.php

The JModel::getState method uses a parameter get internally, which supports a default value. Therefore it would be useful for this method to also be able to accept a default.

Changes required would be:

Code: Select all

	/**
	 * Method to get model state variables
	 *
	 * @access	public
	 * @param	string	Optional parameter name
	 * @param	mixed	Optional default value
	 * @return	object	The property where specified, the state object where omitted
	 * @since	1.5
	 */
	function getState($property = null, $default = null)
	{
		return $property === null ? $this->_state : $this->_state->get($property, $default);
	}

[RoscoHead]

See: http://forum.joomla.org/viewtopic.php?f=38&t=246033

I would like the template preview to display a dummy message where the

Code: Select all

<jdoc:include type="message" />

is in my template. Something like "This is where system messages will be displayed" (obviously it would be localised for other languages).

ROSCO

[bass28]

If I use JPagination twice on the same page (page contains 2 tables that need paging) I do not know which table the limitstart variable belongs to when the user clicks a page link. A way to tell JPagination what variable name to use for limitstart would help.

[ewel]

Perhaps this is not exactly API but certainly it is too small a suggestion to merrit a white paper.

In the Article manager the list can be narrowed down by way of the drop down select boxes of sections, articles, authors and states. These are inclusion filters.

It would be extremely convenient to also use these boxes as exclusion filters. For example instead of seeing only articles of the 'Joomla' category listed, one might want to see all articles except those of the 'Joomla' category.

In the interface, all this would require is a checkbox 'Exclude' or 'Include' or something like that. Under the hood it would require some extra queries.

[Kampp]

It seems that there are some confusion about the usage of the Calendar that has not been there before. Please see this related thread and how some people have used workarounds in order to get it to work.
http://forum.joomla.org/viewtopic.php?f=304&t=288343

Perhaps the only thing thats needed is more documentation on how to use the Calendar API

[Kampp]

There is a bug in the API about the tab system:
http://forum.joomla.org/viewtopic.php?f ... 3#p1316328

Also it seems that there potentialy could be a bug with this function as all I get is an error saying the function does not exsits: http://dev.joomla.org/component/option, ... erystring/

[ewel]

Perhaps this is not exactly API but certainly it is too small a suggestion to merrit a white paper.

In the Article manager the list can be narrowed down by way of the drop down select boxes of sections, articles, authors and states. These are inclusion filters.

It would be extremely convenient to also use these boxes as exclusion filters. For example instead of seeing only articles of the 'Joomla' category listed, one might want to see all articles except those of the 'Joomla' category.

In the interface, all this would require is a checkbox 'Exclude' or 'Include' or something like that. Under the hood it would require some extra queries.

Yuri Volkov was kind enough to create a hack with a similar effect for his component's users, see his yvcomments website. You might call this a sort of proof of concept of the request.

Still it would be great if there would be a tick box next to the section and category select boxes which would reverse the filtering and would exclude the selected category or section from the article list. Then this simple but convenient functionality can be used by anyone for any reason.