Components Output

From HTML5 Builder
Jump to: navigation, search

In the end, components are just PHP classes that write code (HTML, CSS, JavaScript…) for a webpage. So it is important that you know the right way to output that code.

Inline Code

To get your component to print code to the webpage when the script it belongs to is rendered, override Component’s dumpContents() method in your component and print the code to the output.

function dumpContents() {
  echo "This string will be printed to the final webpage by this component.";
}

Separated Code

You should avoid printing your style and scripting code inlined. Instead, you can get your code printed in a separated file, included in your webpages automatically. This leads to a cleaner code, and makes your component more flexible.

Separated CSS

Override Component’s dumpCSS() method in your component to print CSS code.

function dumpCSS() {
  echo "font-weight: bold;\n";
  parent::dumpCSS(); // You must call the parent function at the end.
}

The code you print with this method will be appended to a CSS selector identifying the main HTML element of your component (the one where you configured the id attribute with the value of the Name property of your component), using the id of its top-level container followed by that of the component itself. That is:

#ContainerName #ComponentName {
  /* Here would go the CSS code you printed. */
}

For certain components, you might need additional flexibility. In those, override also Component’s dumpAdditionalCSS() to achieve whatever you need. Unlike with dumpCSS(), what you print in this method will not be placed inside a CSS selector, so you can manually specify the selector or selectors you want.

Tip: You will usually want to use CSS selectors based on your component’s main selector, which is returned by the readCSSDescriptor() method.

For example, you could override it this way:

function dumpAdditionalCSS() {
  parent::dumpAdditionalCSS(); // You must call the parent function at the beginning.

  echo $this->readCSSDescriptor()." blockquote {\n";
  echo "  font-family: monospace;\n";
  echo "}\n\n";

  echo $this->readCSSDescriptor()."_table li {\n";
  echo "  margin: ".$this->_itemmargin.";\n";
  echo "}\n\n";
}

The resulting CSS code would be:

#ContainerName #ComponentName blockquote {
  font-family: monospace;
}
#ContainerName #ComponentName_table li {
  margin: /* The value of the margin property would go here. */;
}

Your CSS code will be added to a separated CSS file, generated by the script when the css GET parameter is defined, and automatically included in your web page.

Separated JavaScript

Override Component’s dumpJavascript() method in your component to print JavaScript code.

function dumpJavascript() {
  parent::dumpJavascript(); // You must call the parent function at the beginning.
  echo "function sayHello() { alert('Hello!); }\n\n";
}

Your JavaScript code will be added to a separated JavaScript file, generated by the script when the js GET parameter is defined, and automatically included in your web page.

External Code

Your component can also get external files for style or scripting included inside the webpage by overriding Component’s dumpHeaderCode() method:

function dumpHeaderCode() {
  parent::dumpHeaderCode(); // You must call the parent function at the beginning.
 
  // Inlcude a CSS file.
  echo "<link href=\"".RPCL_HTTP_PATH."/path/to/the/file.css\" rel=\"stylesheet\" type=\"text/css\"/>\n";
 
  // Include a JavaScript file.
  echo "<script type=\"text/javascript\" src=\"".RPCL_HTTP_PATH."/path/to/the/file.js\"></script>\n";
}

Reusable Code

Some of your components will print code that could be reused by any of its instances, or even by several different components. For example, you could include a JavaScript library using the RPCL method dumpHeaderCode().

The problem is, that code that can be reused by several components will be printed once for each component instance. That is, if you have a webpage with two instance of a component that includes a JavaScript library in the header, the code to include the library will be printed twice.

To avoid that code duplication, the convention in the RPCL is to use a define during the printing of the code, so it can only be printed once:

if(!defined("INCLUDED_CODE_IDENTIFIER"))
{
  echo "This will be printed to the webpage just once, no matter how many times you include the component.";
  define("INCLUDED_CODE_IDENTIFIER", 1);
}

For example, to print the code that includes a JavaScript library:

if(!defined("LIBRARY_NAME"))
{
  echo "<script type=\"text/javascript\" src=\"".RPCL_HTTP_PATH."/path/to/the/library.js\"></script>\n";
  define("LIBRARY_NAME", 1);
}
Personal tools