This plugin allows you to create your own query of posts and pages and displays the result wherever you like it on a page only by adding a shortcode to the page. The great feature is, that you can use nearly all the capabilities of a Wordpress query without having to change anything in the themecode of the page and this is completly independent from the internal Wordpress-loop for the page.

You can query posts by custom defined taxonomies (if supported by your theme) as well as custom and standard catagories, post-types, meta-data and other parameters and combine them to your wishes.

An installed parser checks your input and supports you with Errormessages and helps you to form a correct query.

There are predefined output sections, that allow you to choose, what parts of information of your queryresults you want to show.

The output is styled with CSS-classes and has therefore a standard behaviour, that can be used without any changes by many themes. An extensive set of custom CSS-classes, which are bound to the query, allow you to customize the output of each query independently in nearly any way you like.

An Administration panel allows you to write your queries and select the output you want and stores the information in a database, so you can reuse the same query on multiple pages. (this feature is NOT available in the free lite version). As you only have to write the ID or the name of the query in the shortcode, it helps you to keep your pagecontent more clearly.

Most of the code is based on modern OOP-Technics (object orientated programming), that ensures a high stability of this plugin. Also the possibility of interfering with other plugins due to identical functionnames is very low.

This plugin is currently available in 2 versions:

- Premium Version:

It offers you the follwing two possibilities to place your query and output selection:

• directly in the shortcode on the page, where you want your results to be displayed
• in an option panel on the administration page you can save your query and selected output in a database and reuse this on different pages, if you like

The option panel also supports you with a syntaxchecker - button and shows you the SQL-statement generated by WordPress immidiatly, so you can form your query on the production site without interferring and disturbing it. It also assists you in defining the output sections.

- Free Lite Version:

It offers you the possibility to use some of the features. You can form nearly all the queries as in the premium version, but it has only a limited output capability and no administration panel, so you cannot store the queries for reuse in a database.

The downloadable .zip package contains the following folders and files:

• /documentation_multiselect -> the file index.html in this directory contains the documentation to this plugin.
• inoplugs_multiselect_premium.zip or inoplugs_multiselect_lite.zip ->This file can be used for a direct upload by Wordpress. Alternativly you can unzip this file and upload the complete folder in your Wordpress plugin directory (usually found in Your_Wordpress_directory/wp-content/plugins/) via ftp or any other utility.

To install, follow the following steps:

• Download the package and unzip
• Upload the file 'inoplugs_multiselect_premium.zip' or 'inoplugs_multiselect_lite.zip' with Wordpress
  or
  Unzip the file 'inoplugs_multiselect_premium.zip' or 'inoplugs_multiselect_lite.zip' and upload manually as described above.
• Activate the plugin (adminpage -> plugins -> 'Multiselect Premium Ultimate Query' or 'Multiselect Lite Ultimate Query')

To uninstall, follow the following steps:

• In the option panel -> General Settings set field 'Delete Database' to 'Delete' (case sensitiv, without '), if you want to remove all your stored queries permanently and clean up the database. If you want to keep your queries, write any other value in this field. On your next reactivation of the plugin all datas are available again. This step is not possible in the free lite version (there is no data left behind in this version anyway).
• Deactivate the plugin (adminpage -> plugins -> 'Multiselect Premium Ultimate Query' or 'Multiselect Lite Ultimate Query')

To upgrade to the Premium version, follow the following steps:

• Deactivate the plugin 'Multiselect Lite Ultimate Query' and delete the plugin files (via Wordpress or manually)
• Download the premium package and follow instructions for installing
• All your queries defined on the pages will work as before

To use this plugin you create your page with the content, you need. At the point, where you want to implement the query and show the results, you write the shortcode. If you wish, you can place multiple shortcodes on a page. You have two possibilities to implement it.

You will find a general overview, how to build the shortcode first, later a detailed specification about possible parameters and syntax will follow.

a) Define Query in Shortcode:

You define the complete query and the selection of the output directly in the shortcode. You have several keywords, which are described later. Do not nest any other shortcode inside (currently not supported by WP !!!).

[inoplugs_multiselect parameter="value" {parameter="value" ....}]

$$query$$
      ...  place querystring here ....

$$display$$

       $$section-name$$
      {$$section-name$$
              ........}

[/inoplugs_multiselect]
		

b) Use stored Query defined with Administration Panel:

All parameters for the query and display have already been set in the optionpanel, therefore you only need to set the parameter "queryid" to "ID" or the "shortcode-slug" of the desired query. This option is not available in the free lite version.

[inoplugs_multiselect queryid="ID"]
[/inoplugs_multiselect]
		 

or in a single line:

[inoplugs_multiselect queryid="ID"/]
		 

The parameters for the shortcode are placed directly after the shortcodename "inoplugs_multiselect" seperated by spaces. The values for the parameters must be put in "" or ''. The following parameters are possible for the shortcode:

The querystring tells WP, which posts or pages should be selected. As this is a very powerfull tool, there are some syntax rules to be followed, so the internal parser can translate it for WP. You will find examples in an own chapter to help you understand the syntax and be able to create your custom queries in a short time.

a) Seperator Characters:

These are special characters interpreted by the parser to seperate information. They do not become part of the text to interpret but have only informational character. Any 'space', 'new line', 'tabulator' around them will also be ignored.

• & (used to combine multiple lines)
• = (used to seperate parameters from values)
• , (= comma, used to seperate values)
• ' (used to enclose strings - see strings)
• " (used to enclose strings - see strings)
• {{
• {
• }
• }}

If you want to use one of these characters in a string, see the next section.

b) Syntax for Strings:

Strings are a sequence of characters and numbers to be interpreted as text. You have 3 possibilities to define a string:

• Unqouted Strings: Any sequence of characters and numbers between two seperators. To include seperators in the string, you have to escape them with \ (e.g. to unclude & you have to write \&, for " you write \"). A new line does not end a string, depending on the section it will be removed or left in the string.
• "your text": Any sequence of characters and numbers inside "...." will be accepted, also seperators. To include " you have to escape it with \ (e.g. you write \").
• 'your text': Any sequence of characters and numbers inside '....' will be accepted, also seperators. To include ' you have to escape it with \ (e.g. you write \').

Examples:

this is an unquoted text
this isn’t new\, but \"hot\" \& spicy
"this is a quoted text & new"
"say \"hello\" now"
‘this is another quoted text & new’
‘it isn\’t new’
"Text1" , "Text2"
Text1, Text2, 'Text3' , "Text4"

c) Syntax for Numbers:

Numbers are a sequence of characters from 0 - 9, and can also be written similar to strings. For decimal numbers '.' is needed (e.g. 5.3). Other numberformats are not supported yet.

35
15.25
“35”
“15, 25”
“15”, “25”, 35
		

d) Basic Syntax for the Query:

The querystring syntax can consist of several lines. Linebreaks are ignored and can be put anywhere to make the code readable. Keywords must not be seperated.

keyword = value [, value, ....] [&
keyword = value [, value, ....] [&  ....  ]]
		

All possible keywords and the appropriate possible values are clearly described in the WP documentation of WP-Query object under the section "Parameters".

For syntax like 'category_name=staff' you write similarily to WP:

category_name=staff
author = 123, 135
author=-12,-34,-56
tag= bread, baking
		

For syntax described with array(...) you write the values similarily to the above syntax:

tag__and = 37, 47
post__in = 2, 5, 12, 14, 20
post_type = 'post', 'page', 'movie', 'book'
		

e) Syntax for Categories and Taxonomies:

To query categories and taxonomies you don't have to take care, whether a category belongs to a custom taxonomy or not. Simply select or deselect the categories as you like. You can also query all categories, which belong to a taxonomy.

There is a special syntax and keywords for querying categories, taxonomies and also for custom fields (described in the next section):

categoryselection = {{
    select = {
	    [cats | catsname | taxs] = value [&
	    operator = value]
          }
     [relation = value  &
     select = {
	    [cats | catsname | taxs] = value [&
	    operator = value]
          }
	 ][
      select = {
	     [cats | catsname | taxs] = value [&
	     operator = value]
           }
       ][....]
     ]
	              }}
		

f) Syntax for Querying Custom Fields:

To query custom fields you have to take the following syntax. A description of the parameters and values inside {....} you find in the WP documentation at WP-Query object under the section "Custom Field Parameters". All {{, { and & must be placed as described below.

meta_query  = {{
     select = { key = value &
                value =  value &
                compare = value [&
                type = value]
	          }
     [select = { key = value &
                 value =  value &
                 compare = value [&
                 type = value]
		       }
     [ ….   ]
	          }}
		

g) Pass through Syntax for Taxonomy - Query:

For experienced users it is possible to make a direct pass through taxonomy query. The keywords and values correspond to WP and is very similar to the array in array structure of WP.

tax_query = {{
     select = { taxonomy = value &
                field =  value &
                terms = value [&
                operator = value]
	          }
     [relation = value &
      select = { taxonomy = value &
                 field =  value &
                 terms = value [&
                 operator = value]
		     }
	 ][
      select = { taxonomy = value &
                 field =  value &
                 terms = value [&
                 operator = value]
		     }
      ][....    ]
	              }}
		

If both "categoryselection" and "tax_query" are present in a query, "categoryselection" will be ignored.

The desired output is selected with keywords. You can combine as many keywords you like and as often as you like. All resulting posts of the query have the same output. You cannot change the output within a query. If you need this, you have to put several shortcodes with queries on the page.

The free lite version only supports the following keywords: $$thetitle$$, $$theexcerpt$$, $$thedate$$.

Example:

[inoplugs_multiselect]

$$query$$
      ...  place your querystring here ....

$$display$$

$$thetitle$$
$$theexcerpt$$
$$thedate$$

[/inoplugs_multiselect]
		

The output has a default styling in multiselect.css located in the subfolder /css of the plugin. There are a lot of classes added to the HTML output, so you are able to make your own styling by changing the standard settings.

You are also able to adopt the styling depending on the query you make. If the parameter 'cssid' is set to a string, this string will be added to the classnames and this class will be added additionally. If it is not set, no extra class will be added.

The classnames all start with 'ipms-' to seperate them from any theme-classes used.

'ipms-bgskin-light' (= default) or 'ipms-bgskin-dark' are bound to the surrounding <div>-container only. 'ipms-bgskin-dark' can only be activated via the administration panel, where they are bound to each query independently.

The name of the displayed section is part of the classname preceded by 'div' for the surrounding <div>-container. The post-ID is also integrated in the classes added. If there are any links or other elements in the section you will also find classes to style them.

Do not alter any of the original css-files, because they are always part of the download in future releases and will therefore override your changes !!!

Instead use the file multiselect_custom.css to make your customizations. If this file is present, it will be loaded as the last of all inoplugs_multiselect stylesheets and therefore override the values of the others. For your convienience you find an empty file multiselect_custom_template.css, which you only need to rename.

The following snipplet of the output html code shows you the created classes. cssid was set to 'custcss'.

<div class="ipms-bgskin-light ipms-bgskin-light-custcss
                        ipms-postcomplete ipms-postcomplete-custcss
                        ipms-postcomplete-post-101 ipms-postcomplete-post-101-custcss">

	<div class="ipms-divtitle ipms-divtitle-custcss ipms-post-101 ipms-post-101-custcss">
		<h1 class="ipms-title ipms-title-custcss">A theme with fantastic options</h1>
	</div>

	<div class="ipms-divexcerpt ipms-divexcerpt-custcss
                         ipms-post-101 ipms-post-101-custcss">
		<p class="ipms-excerpt ipms-excerpt-custcss">

					......  the excerpttext   .....

		</p>
	</div>


</div>
		  

The stylesheet 'multiselect_options.css' in the folder /css is used by the administration panel. If you want to change any of the styles, use the stylesheet 'multiselect_options_custom.css', because this will never be updated by any further release and is added automatically at the end, if existing.

In the folder /inoplugs_framework/css you find the stylesheets 'admin_option.css' and 'exceptions.css'. Any changing to 'admin_option.css' should be done in 'multiselect_options_custom.css', for 'exceptions.css' should be done in 'multiselect_custom.css'.

On the administration page on the left side you find a Top level Menu 'Multiselect Options' with the submenues 'Show Queries' and 'Add New'. These Options are not available in the free lite version.

An optionpanel with accordeon technology allows you to manage options for the plugin and your queries. It provides you with a syntaxchecker and also shows you the generated SQL-statement to help you developing your query.

Here you see an overview of all stored queries ordered by 'UniqueID' with essential information like 'Shortcode-slug', 'Name of Query', 'CSS-ID' and 'Comment'. Currently you cannot change the order. By clicking on the name of the shortcode-slug or the upcoming link 'Edit' you can edit the query, to permanently delete it you have to click on 'Delete'.

This option panel allows you to create a new query. It is also activated, when you want to edit an existing query.

When you click on one of the bars in the panel, it expands, clicking again on it the underlying information is hidden again.

If you move your cursor over an inputfield, a popup window gives you information about the required input (works on most browsers).

This section is only faded in after loading the page as a quick status information and disappears automatically. It cannot be reproduced. Instead look into the section 'Errors and Internals'.

Copy the required output sections from 'Possible Values:' to 'Your Selection:' or visa versa. You can select multiple entrys by pressing 'Ctrl' key and clicking the required section. Clicking the buttons '>>', '>', '<', '<<' moves the selection.

The selection of the dropdown box 'Theme has a: light background | dark background' allows you to set a general styling for your output.

Messages produced by 'Check Syntax', 'Save Changes' and 'Delete Query' - buttons.

Summary of this documentation to help you online.

In this section you will find some examples that shall help you to form your own queries.

You site has a category-slug 'Hockey' (ID = 16) with subcategories and you want to show this category and their subcategories and the last (=newest) 7 posts on a page, ordered by posttitles descending. As of WP 3.1 WP is not able to have different order in a query, therefore only descending for title is possible. In a future release of this plugin there will be a fix to this limitation.

$$query$$

posts_per_page = 7 &
categoryselection = {{
    select = { cats = Hockey }
       }}
orderby = date, title &
order = desc

$$display$$
$$thetitle$$
$$theexcerpt$$
$$thedate$$
		  

or

$$query$$

categoryselection = {{
    select = { cats = 16 }
       }}
posts_per_page = 7 &
orderby = date, title &
order = desc

$$display$$
$$thetitle$$
$$theexcerpt$$
$$thedate$$
		  

or using the WP keyword cat

$$query$$
posts_per_page = 7 &
cat = 16 &
orderby = date, title &
order = desc

$$display$$
$$thetitle$$
$$theexcerpt$$
$$thedate$$
		  

Same query (without order and orderby), but now you want to exclude category ID = 17:

$$query$$
posts_per_page = 7 &
categoryselection = {{
    select = { cats = Hockey &
               operator = in}
     relation = and &
     select = { cats = 17  &
                operator = not in}
       }}

$$display$$
$$thetitle$$
$$theexcerpt$$
$$thedate$$
		  

or using the WP keyword cat

$$query$$
posts_per_page = 7 &
cat = 16, -17

$$display$$
$$thetitle$$
$$theexcerpt$$
$$thedate$$
		  

The above examples with categoryselection also work, if your theme has e.g. a custom taxonomy 'portfolio_entries' with the categories 'CSS' (ID = 4) and 'HTML' (ID = 5):

$$query$$
posts_per_page = 7 &
categoryselection = {{
    select = { cats = css, html }
       }}

$$display$$
$$thetitle$$
$$theexcerpt$$
$$thedate$$
		  

or

$$query$$
posts_per_page = 7 &
categoryselection = {{
    select = { cats = 4, 5 }
       }}

$$display$$
$$thetitle$$
$$theexcerpt$$
$$thedate$$
		  

To query all categories of 'portfolio_entries':

$$query$$
posts_per_page = 7 &
categoryselection = {{
    select = { taxs = 'portfolio_entries'}
       }}

$$display$$
$$thetitle$$
$$theexcerpt$$
$$thedate$$
		  

To query all categories of the standard built in category 'category':

$$query$$

posts_per_page = 7 &
categoryselection = {{
    select = { taxs = 'category'}
       }}

$$display$$
$$thetitle$$
$$theexcerpt$$
$$thedate$$
		  

To query all categories of 'portfolio_entries' but exclude categories 'CSS'(ID = 4) and 'HTML' (ID = 5):

$$query$$

posts_per_page = 7 &
categoryselection = {{
    select = { taxs= 'portfolio_entries'}
    relation = and  &
    select = { cats = css, 5  &
               operator = not in }
       }}

$$display$$
$$thetitle$$
$$theexcerpt$$
$$thedate$$
		  

To query the custom categories 'CSS'(ID = 4) and 'HTML' (ID = 5) and a built in category with category-slug 'Hockey' (ID = 16) with subcategories :

$$query$$

posts_per_page = 7 &
categoryselection = {{
    select = { cats = css, html, hockey}
       }}

$$display$$
$$thetitle$$
$$theexcerpt$$
$$thedate$$
		  

All the possible keywords and the appropriate possible values of WP to be used outside 'categoryselection' are clearly described in the WP documentation of WP-Query object under the section "Parameters".

You can try to define your own queries now. If you have any troubles, you can have a look at our homepage, where we will post more examples by the time or contact us in the forum and we will try to help you.

In this section you will find the chronology of the versions.