Main controlling instance of the MidCOM Framework
This class is the heart of the MidCOM Framework. It has the entry points which are used to fire up the framework and get everything running. This class represents a Facade pattern.
The following URL parameters are recognized by the _process function and are executed before any component processing is done. They all belong to the domain "midcom", e.g. they are executed like this: midcom-$name-$value.
string substyle
This will set a substyle to the current component, which is appended to the style selected by the component at the moment the component style is loaded. The methods substyle_(append|prepend)'s work on the basis of this value then.
Note, that this first assignment is done between can_handle and handle, so it will serve as a basis for all component-side style switching operations.
The substyle URL switch is most useful in conjunction with midcom_application::dynamic_load().
int serveattachment; GUID serveattachmentguid
This pair of methods will serve the attachment denoted by the given ID/GUID. It uses the default expiration time of serve_attachment (see there).
int servesnippet; GUID servesnippetguid
This pair will serve the code field of a snippet denoted by the given ID/GUID, see serve_snippet for further options. For security purposes, the snippets that may be served using this function MUST have the parameter midcom/allow_serve set to "true". If this is not the case, snippet serving will be aborted with an access denied error. See the serve_snippet method documentation for further details.
GUID permalink
This will resolve the given GUID into the MidCOM NAP tree, relocating to the URL corresponding to the node/leaf. The Permalink can be created by using the key MIDCOM_NAV_PERMALINK of any NAP data array. Upon resolving it, MidCOM will relocate to the automatically computed MIDCOM_NAV_FULLURL.
string exec
Allows you to execute certain php files directly, in full MidCOM context. The argument is the name of the component, which holds the script to be executed. Script files are searched in the subdirectory "exec" of the component. If you use "midcom" as component name, MidCOM core scripts, located in lib/midcom/exec will be accessible. The next argument on the command line must be the name of the script file. Accessing subdirectories is not possible, only a single argument will be taken.
The scripts executed need to do their own permission checks, they will work with the credentials of the current MidCOM instance unconditionally.
Example: http://$host/midcom-exec-midcom/upgrade_metadata.php
The remaining URL arguments are put into the globals $argc/$argv.
string cache
May take one of the following values: "invalidate" will clear the cache of the current site, "nocache" will bypass the cache for the current request by calling $this->cache->content->no_cache();
mixed log
Shows the contents of the current debuglog. You have to enable this interface by setting the config option log_tailurl_enable to true. Note, that this method is using the debug log path of the current MidCOM logger automatically, it is not possible to switch to another logfile dynamically due to security reasons. The parameter can be either "all" which will yield the complete log (beware of huge logfiles), or an integer, which is the number of lines counting from the file backwards you want to display (this uses the systems tail command via exec).
NOTE: This function is limited by PHP's memory limit, as the (f)passthru functions are really intelligent and try to load the complete file into memory instead streaming it to the client.
Located in /midcom.core/midcom/application.php (line 107)
JS/CSS merger service
Contains the output of get_midgard. You can directly access it here.
Set this variable to true during the handle phase of your component to
not show the site's style around the component output. This is mainly targeted at XML output like RSS feeds and similar things. The output handler of the site, excluding the style-init/-finish tags will be executed immediately after the handle phase, and midcom->finish() is called automatically afterwards, thus ending the request.
Changing this flag after the handle phase or for dynamically loaded components won't change anything.
Holds the component context information.
This is an array of arrays, the outer one indexed by context IDs, the inner one indexed by context keys. Only valid of the system has left the code-init phase.
Register JavaScript snippets to jQuery states.
This allows MidCOM components to register JavaScript code to the jQuery states. Possible ready states: document.ready
Register JavaScript Code for output directly in the page.
This allows MidCOM components to register JavaScript code during page processing. The site style code can then query this queued-up code at anytime it likes. The queue-up SHOULD be done during the code-init phase, while the print_head_elements output SHOULD be included in the HTML HEAD area and the HTTP onload attribute returned by print_jsonload SHOULD be included in the BODY-tag. Note, that these suggestions are not enforced, if you want a JScript clean site, just omit the print calls and you should be fine in almost all cases.
Note: These functions originate from the class midcom_admin_content and were moved to here to allow datamanager edit forms with DHTML widget support outside of AIS. The function stubs in midcom_admin_content remain in place for backwards-compatibility.
The sequence of the add_jsfile and add_jscript commands is kept stable.
Register JavaScript File for referring in the page.
This allows MidCOM components to register JavaScript code during page processing. The site style code can then query this queued-up code at anytime it likes. The queue-up SHOULD be done during the code-init phase, while the print_head_elements output SHOULD be included in the HTML HEAD area and the HTTP onload attribute returned by print_jsonload SHOULD be included in the BODY-tag. Note, that these suggestions are not enforced, if you want a JScript clean site, just omit the print calls and you should be fine in almost all cases.
Note: These functions originate from the class midcom_admin_content and were moved to here to allow datamanager edit forms with DHTML widget support outside of AIS. The function stubs in midcom_admin_content remain in place for backwards-compatibility.
The sequence of the add_jsfile and add_jscript commands is kept stable.
Register a JavaScript method for the body onload event
This allows MidCOM components to register JavaScript code during page processing. The site style code can then query this queued-up code at anytime it likes. The queue-up SHOULD be done during the code-init phase, while the print_head_elements output SHOULD be included in the HTML HEAD area and the HTTP onload attribute returned by print_jsonload SHOULD be included in the BODY-tag. Note, that these suggestions are not enforced, if you want a JScript clean site, just omit the print calls and you should be fine in almost all cases.
Note: These functions originate from the class midcom_admin_content and were moved to here to allow datamanager edit forms with DHTML widget support outside of AIS. The function stubs in midcom_admin_content remain in place for backwards-compatibility.
Register a linkelement to be placed in the pagehead.
This allows MidCom components to register extra css-links in the pagehead. Example to use this to include a css link:
Register a metatag to be added to the head element.
This allows MidCom components to register metatags to be placed in the head section of the page.
Register some object tags to be added to the head element.
This allows MidCom components to register object tags to be placed in the head section of the page.
Register a styleblock / style link to be added to the head element.
This allows MidCom components to register extra css sheets they wants to include. in the head section of the page.
Binds the current page view to a particular object. This will automatically connect such things like metadata and toolbars to the correct object.
Initialize the URL parser and process the request.
This function must be called before any output starts.
Display the output of the component
This function must be called in the content area of the Style template, usually <(content)>.
Dynamically execute a subrequest and insert its output in place of the function call.
Imporant Note As with the Midgard Parser, dynamic_load strips a trailing .html from the argument list before actually parsing it.
Under MIDCOM_REQUEST_CONTENT it tries to load the component referenced with the URL $url and executes it as if it was used as primary component. Additional configuration parameters can be appended through the parameter $config.
This is only possible if the system is in the Page-Style output phase. It cannot be used within code-init or during the output phase of another component.
Setting MIDCOM_REQUEST_CONTENTADM loads the content administration interface of the component. The semantics is the same as for any other MidCOM run with the following exceptions:
Danger, Will Robinson:
Be aware, that the call to another component will most certainly overwrite global variables that you are currently using. A common mistake is this:
The reason why this usually fails is, that the $view you have been using during the first call was overwritten by the other component during it, $view['url2'] is now empty. If you are now on the homepage, the homepage would start loading itself again and again.
Therefore, be sure to save the variables locally (remember, the style invocation is in function context):
Results of dynamic_loads are cached, by default with the system cache strategy but you can specify separate cache strategy for the DL in the config array like so
You can use only less specific strategy than the global strategy, ie basically you're limited to 'memberships' and 'public' as values if the global strategy is 'user' and to 'public' the global strategy is 'memberships', failure to adhere to this rule will result to weird cache behaviour.
Init jQuery
This method adds jQuery support to the page
Exit from the framework, execute after all output has been made.
Does all necessary clean-up work. Must be called after output is completed as the last call of any MidCOM Page. Best Practice: call it at the end of the ROOT style element.
WARNING: Anything done after calling this method will be lost.
Generate an error page.
This function is a small helper, that will display a simple HTML Page reporting the error described by $httpcode and $message. The $httpcode is also used to send an appropriate HTTP Response. Currently the layout of this error page is fixed, but it should be no problem to relay this to a style in a later stage of MidCOM Development.
For a list of the allowed HTTP codes see the MIDCOM_ERR... constants
Note: This function will call exit() after it is finished.
This is a temporary transition function used to get the currently known and required Request Metadata: The last modified timestamp and the permalink GUID.
Author's note: This function is a temporary solution which is used until the Request handling code of MidCOM has been rewritten. Hence the _26_ section in its name. I have decided to put them into their own function instead of letting you access the corresponding context keys directly. Thus, there is also corresponding setter-function, which set the information returned here. Just don't worry where it is stored and use the interface functions.
If the system is in the output phase (see above), the systemwide low-level NAP interface can be accessed through this function. A reference is returned.
This function maintains one NAP Class per concept. Usually this is enough, since you mostly will access it in context 0, the default. Only the AIS currently uses different context IDs. The problem is, that this is not 100% efficient: If you instantiate two different NAP Classes in different contexts both referring to the same root node, you will get two different instances.
If the system has not completed the can_handle phase, this method fails and returns false.
Note: Direct use of this function is discouraged, use the class midcom_helper_nav instead.
Returns the Client Status Array which gives you all available information about the client accessing us.
Currently incorporated is a recognition of client OS and client browser.
NOTE: Be careful if you rely on this information, the system does not check for invervening Proxies yet.
WARNING: If the caching engine is running, you must not rely on this information! You should set no_cache in these cases.
Return the reference to the component loader.
Access the MidCOM component context
Returns Component Context Information associated to the component with the context ID $contextid identified by $key. Omitting $contextid will yield the variable from the current context.
If the context ID is invalid, false is returned and $midcom_errstr will be set accordingly. Be sure to compare the data type with it, since a "0" will evaluate to false if compared with "==" instead of "===".
Returns the ID of the currently active context. This is FALSE if there is no context running.
Retrieve arbitrary, component-specific information in the component context
The set call defaults to the current context, the get call's semantics are as with get_context_data.
Note, that if you are working from a library like the datamanager is, you cannot override the component association done by the system. Instead you should add your libraries name (like midcom.helper.datamanager) as a prefix, separated by a dot. I know, that this is not really an elegant solution and that it actually breaks with the encapsulation I want, but I don't have a better solution yet.
A complete example can be found with set_custom_context_data.
Retrieves the name of the current host, fully qualified with protocol and port.
Return the prefix required to build relative links on the current site.
This includes the http[s] prefix, the hosts port (if necessary) and the base url of the main host. This is not necessarily the currently active MidCOM Page however, use the get_page_prefix() function for that.
e.g. something like http[s]://www.domain.com[:8080]/host_prefix/
A mgd_get_midgard replacement
Returns basically the object returned by mgd_get_midgard(), but the the variable "self" is fixed by appending the MidCOM site prefix.
Return the prefix required to build relative links on the current site.
This includes the http[s] prefix, the hosts port (if necessary) and the base url of the Midgard Page. Be aware, that this does *not* point to the base host of the site, which is an important distinction for example in AIS.
e.g. something like http[s]://www.domain.com[:8080]/host_prefix/page_prefix/
Return a reference to a given service.
Returns the MidCOM Object Service indicated by $name. If the service cannot be found, an HTTP 500 is triggered.
See the documentation of the various services for further details.
Get the current MidCOM processing state.
Sends a header out to the client.
This function is syntactically identical to the regular PHP header() function, but is integrated into the framework. Every Header you sent must go through this function or it might be lost later on; this is especially important with caching.
Main MidCOM initialization.
Note, that there is no constructor so that initialize can already populate global references.
Initialize the Application class. Sets all private variables to a predefined state. $node should be set to the midcom root-node GUID. $prefix can be a prefix, which is appended to get_midgard()->self (i.e. the Midgard Page URL). This may be needed when MidCOM is run by wrapper.
Load a code library
This will load the pure-code library denoted by the MidCOM Path $path. It will return true if the component truly was a pure-code library, false otherwise. If the component loader cannot load the component, generate_error will be called by it.
Common example:
Loads a code file from disk and require()'s it. This is no longer a valid MidCOM function and it will trigger an E_USER_NOTICE level PHP error.
Echo the _head elements added.
This function echos the elements added by the add_(style|meta|link|object)_head methods.
Place the method within the <head> section of your page.
This allows MidCOM components to register HEAD elements during page processing. The site style code can then query this queued-up code at anytime it likes. The queue-up SHOULD be done during the code-init phase, while the print_head_elements output SHOULD be included in the HTML HEAD area and the HTTP onload attribute returned by print_jsonload SHOULD be included in the BODY-tag. Note, that these suggestions are not enforced, if you want a JScript clean site, just omit the print calls and you should be fine in almost all cases.
Echo the jquery statuses
This function echos the scripts added by the add_jquery_state_script method.
This method is called from print_head_elements method.
Echo the registered javascript code.
This allows MidCOM components to register JavaScript code during page processing. The site style code can then query this queued-up code at anytime it likes. The queue-up SHOULD be done during the code-init phase, while the print_head_elements output SHOULD be included in the HTML HEAD area and the HTTP onload attribute returned by print_jsonload SHOULD be included in the BODY-tag. Note, that these suggestions are not enforced, if you want a JScript clean site, just omit the print calls and you should be fine in almost all cases.
Note: These functions originate from the class midcom_admin_content and were moved to here to allow datamanager edit forms with DHTML widget support outside of AIS. The function stubs in midcom_admin_content remain in place for backwards-compatibility.
The sequence of the add_jsfile and add_jscript commands is kept stable.
This is usually called during the BODY region of your style:
Relocate to another URL.
Helper function to facilitate HTTP relocation (Location: ...) headers. The helper actually can distinguish between site-local, absolute redirects and external redirects. If you add an absolute URL starting with a "/", it will automatically add an http[s]://$servername:$server_port in front of that URL; note that the server_port is optional and only added if non-standard ports are used. If the url does not start with http[s], it is taken as a URL relative to the current anchor prefix, which gets prepended automatically (no other characters as the anchor prefix get inserted).
Fully qualified urls (starting with http[s]) are used as-is.
Note, that this function automatically makes the page uncacheable, calls midcom_finish and exit, so it will never return. If the headers have already been sent, this will leave you with a partially completed page, so beware.
Deliver a blob to the client.
This is a replacement for mgd_serve_attachment that should work around most of its bugs: It is missing all important HTTP Headers concerning file size, modification date and expiration. It will not call exit() when it is finished, you still have to do that yourself. It will add the following HTTP Headers:
Deliver a snippet to the client.
This function is a copy of serve_attachment, but instead of serving attachments it can serve the code field of an arbitrary snippet. There is no checking on permissions done here, the callee has to ensure this. See the URL methods servesnippet(guid) for details.
Two parameters can be used to influence the behavior of this method: "midcom/content-type" will set the content-type header sent with the code field's content. If this is not set, application/octet-stream is used as a default. "midcom/expire" is a count of seconds used for content expiration, both for the HTTP headers and for the caching engine. If this is no valid integer or less then or equal to zero or not set, the value is set to "1".
The last modified header is created by using the revised timestamp of the snippet.
Remember to also set the parameter "midcom/allow_serve" to "true" to clear the snippet for serving.
This is a temporary transition function used to set the currently known and required Request Metadata: The last modified timestamp and the permalink GUID.
Author's note: This function is a temporary solution which is used until the Request handling code of MidCOM has been rewritten. Hence the _26_ section in its name. I have decided to put them into their own function instead of letting you access the corresponding context keys directly. Thus, there is also corresponding getter-function, which return you the set information here. Just don't worry where it is stored and use the interface functions.
You may set either of the arguments to NULL to enforce default usage (based on NAP).
Store arbitrary, component-specific information in the component context
This method allows you to get custom data to a given context. The system will automatically associate this data with the component from the currently active context. You cannot access the custom data of any other component this way, it is private to the context. You may attach information to other contexts, which will be associated with the current component, so you have a clean namespace independently from which component or context you are operating of. All calls honor references of passed data, so you can use this for central controlling objects.
Note, that if you are working from a library like the datamanager is, you cannot override the component association done by the system. Instead you should add your libraries name (like midcom.helper.datamanager) as a prefix, separated by a dot. I know, that this is not really an elegant solution and that it actually breaks with the encapsulation I want, but I don't have a better solution yet.
Be aware, that this function works by-reference instead of by-value.
A complete example could look like this:
A very important caveat of PHP references can be seen here: You must never give a reference to $this outside of a class within a constructor. class_one uses an init function therefore. See the PHP documentation for a few more details on all this. Component authors can usually safely set this up at the beginning of the can_handle() and/or handle() calls.
Also, be careful with the references you use here, things like this can easily get quite confusing.
Sets the page title for the current context.
This can be retrieved by accessing the component context key MIDCOM_CONTEXT_PAGETITLE.
Appends a substyle after the currently selected component style.
Appends a substyle after the currently selected component style, effectively enabling a depth of more then one style during substyle selection. This is only effective if done during the handle phase of the component and allows the component. The currently selected substyle therefore is now searched one level deeper below "subStyle".
The system must have completed the CAN_HANDLE Phase before this function will be available.
Prepends a substyle before the currently selected component style.
Prepends a substyle before the currently selected component style, effectively enabling a depth of more then one style during substyle selection. This is only effective if done during the handle phase of the component and allows the component. The currently selected substyle therefore is now searched one level deeper below "subStyle".
The system must have completed the CAN_HANDLE Phase before this function will be available.
Create and prepare a new component context.
This is a helper to execute any given Script in the current MidCOM context. All files have to be in $component_dir/exec directly, otherwise the script will not execute.
The script's name is taken from the current argv[0].
Any error calls generate_error.
The script file is executed in the cache's live mode to allow for long running scripts (just produce any output regularly, or Apache will kill you after ~ 2 mins.).
The remaining arguments will be placed into the globals $argc/argv.
Magic getter for service loading
Documentation generated on Fri, 10 Oct 2008 21:48:42 +0300 by phpDocumentor 1.4.2