Extension components API


Extension components API overview


For an overview on how to write extension components yourself, see this document.

The following API functions are available for creating your own components:



Element and Text Modifications



Utility Functions


Code and Styles



Drawing in Editor



Navigating and creating elements






print(...)


Prints a message to the console. Makes it possible to debug your scripts. You can see the console in RocketCake by clicking View -> Log window.

Parameters:




rcGetThisElement()


Returns a reference to the element represented by this component. The reference returned can be used as parameter in many other functions like rcSetElementProperty and similar.




rcGetElementType(elem)


Returns a string describing the type of the element, like "button" or "container"

Parameters:


Example: To search for the page where the current element is located in, do it like this:


var currentNode = rcGetThisElement();

var page = null;


while(currentNode)

{

       if (rcGetElementType(currentNode) == "page")

       {

               page = currentNode; // found!

               break;

       }

       currentNode = rcGetElementParent(currentNode);                

}




rcSetElementProperty(elem, propertyname, propertyvalue)


Sets the property of an element to a new value


Parameters:


All elements have properties in RocketCake. You can see the properties in the property window when the element is selected. When you set the language of RocketCake to "english", then you mostly see the exact name of the property displayed there as you can also use if as the "propertyname" parameter here. Common properties are for example "BackgroundMode", "BackgroundColor", "BorderMode", "Size", "PositionType", "Position", "UseHoverStyles", "HoverFillColor", etc.


When a property is a string, for example like "Size", then you can set it like this:


rcSetElementProperty(button, "Size", "60%, 30");


When a property is a color, for example like "BackgroundColor", then you can set a color value in there using the color class (see below), like this:


rcSetElementProperty(button, "BackgroundColor", new color(0.5, 0.5, 0.5));


Some properties have special values:





rcGetElementProperty(elem, propertyname)


Returns the property of an element.

Parameters:

See rcSetElementProperty() for a descripton of the properties.


Example:


var isOpen = rcGetElementProperty(rcGetThisElement(), "open");

If the element has a property named "open", then the value the user has set this property to is stored in isOpen.




rcGetDocumentNode()


Returns the document element reference. This is basically the root node. Can be used to search for a specific element.

Parameters:




rcCreateElement(parent, type)


Creates a new element.

Parameters:


Example:

In the onInit() function of extension components, you can create child elements. For example when you create a contact form, you want a few input elements and a send button. For this, you need to create a container child element as root element for these and then place the child elements in there. In this example, we create a container child element and a button with the text "Press Me" and a hyperlink:

// called at the start, so all default settings can be set here

myComponent.prototype.onInit = function()

{

       var me = rcGetThisElement();


       rcSetElementProperty(me, "Size", "220, 50");

       rcSetElementProperty(me, "BackgroundMode", 0); // 0 = none, 1 = color, 2 = image, 3 = gradient

       

       // create container child element

       

       var textContainerElem = rcCreateElement(me, "text");

       rcSetElementProperty(textContainerElem, "Size", "100%, 100%");

       rcSetElementProperty(textContainerElem, "Position", "0%, 0%");

       

       // create button

       

       var button = rcCreateElement(textContainerElem, "shape");

       rcSetElementProperty(button, "BackgroundMode", 1); // 0 = none, 1 = color, 2 = image, 3 = gradient

       rcSetElementProperty(button, "BackgroundColor", new color(0.5, 0.5, 0.5));

       rcSetElementProperty(button, "BorderMode", 0); // 0 = none

       rcSetElementProperty(button, "Size", "200, 28");

       rcSetElementProperty(button, "PositionType", 9);  // 0 = free, 9 = anchored in text

       rcSetElementProperty(button, "Position", "0%, 80");

       rcSetElementProperty(button, "UseHoverStyles", true);

       rcSetElementProperty(button, "HoverFillColor", new color(111 / 255.0, 111 / 255.0, 111 / 255.0));        

       rcSetElementProperty(button, "Margin", "10 10 10 10");

       rcSetElementText(button, "Press Me");        

       

       // add hyperlink

       rcSetHyperlink(button, "https://www.ambiera.com");

}




rcSetElementText(elem, txt)


Sets the whole text of an element.

Parameters:


Example:

Place this in the onInit function to create a text element with the text "Note: See our policy for details."

var textElem = rcCreateElement(rcGetThisElement(), "text");


rcSetElementProperty(textElem, "Size", "80%, 80%");

rcSetElementProperty(textElem, "Position", "10%, 10%");

rcSetElementText(textElem, "Note: See our policy for details.");





rcInsertElementIntoText(elem, elemToInsert, position)


Inserts an element at a specific position into the text of an element

Parameters:




rcSetTextHyperlink(elem, textPosFrom, textPosTo, url)


Sets the hyperlink of a part of a text. If you want to set the hyperlink for a whole element like an image, use rcSetHyperlink instead.

Parameters:


Example:

Place this in the onInit function to create a text element with the text "Note: See our policy for details." and the 'policy' text will then be a hyperlink to 'example.com'.

var textElem = rcCreateElement(rcGetThisElement(), "text");


rcSetElementProperty(textElem, "Size", "80%, 80%");

rcSetElementProperty(textElem, "Position", "10%, 10%");

rcSetElementText(textElem, "Note: See our policy for details.");


rcSetTextHyperlink(textElem, 15, 21, "https://www.example.com");





rcSetTextAlignment(elem, textPosFrom, textPosTo, alignment)


Sets the alignment of a part of a text

Parameters:


Example:

The child text element will have the text "Hello Here" and it will be centered.

test.prototype.onInit = function()

{

       var me = rcGetThisElement();

               

       rcSetElementProperty(me, "PositionType", 9);   // 0 = free, 9 = anchored in text

       rcSetElementProperty(me, "Size", "50%, 320");

       rcSetElementProperty(me, "MinWidth", 350);

       rcSetElementProperty(me, "BackgroundMode", 1); // 0 = none, 1 = color, 2 = image, 3 = gradient

       rcSetElementProperty(me, "BackgroundColor", new color(0.9, 0.9, 0.9));

       

       // create container child element

       

       var textContainerElem = rcCreateElement(me, "text");

       rcSetElementProperty(textContainerElem, "Size", "100%, 100%");

       rcSetElementProperty(textContainerElem, "Position", "0%, 0%");

       

       rcSetElementText(textContainerElem, "\nHello There\n\n\n\n");

       

       rcSetTextAlignment(textContainerElem, 0, 14, "center");

}




rcSetTextFontSize(elem, textPosFrom, textPosTo, size)


Sets the font size of a part of a text


Parameters:




rcSetFloatWhenAnchoredInText(elem, float)


Sets the float of an element when it is anchored in the text. Same as when you right-click onto an element in the editor and select "Text Float -> float"


Parameters:




rcSetAllowFontEditing(elem)


To be called in the onInit function, this enables font properties to be set for this whole element when it is selected in the editor. Properties of the font can be accessed then via properties, see the example below.


Parameters:


Example:


An example onInit() method which calls rcSetAllowFontEditing(), so that fonts for that element can be selected:

test.prototype.onInit = function()

{

       var me = rcGetThisElement();


       rcSetElementProperty(me, "Size", "50%, 22");

       rcSetElementProperty(me, "BackgroundMode", 0); // 0 = none, 1 = color, 2 = image, 3 = gradient

       

       rcSetAllowFontEditing(me); // enables the font selection bar when this element is selected,

                                  // and provides the selectd font in the properties "FontName",

                                          // "FontSize", "FontItalic", "FontColor" etc

}



Later, for example in the .onWriteHTML, these can be accessed via rcGetElementProperty() and written out as CSS styles like this:

       // get font style

       

       var fontName = rcGetElementProperty(me, "FontName");

       if (fontName == "") fontName = "Arial, Helvetica, sans-serif"; // default font

       var fontSize = rcGetElementProperty(me, "FontSize");

       var fontBold = rcGetElementProperty(me, "FontBold");

       var fontItalic = rcGetElementProperty(me, "FontItalic");

       var fontUnderline = rcGetElementProperty(me, "FontUnderline");                

       var fontColor = rcGetElementProperty(me, "FontColor").getHTMLColor();


       var fontStyle = "";

       fontStyle += "font-size:" + fontSize + "pt; ";

       fontStyle += "font-family:" + fontName + "; ";

       fontStyle += "color:" + fontColor + "; ";

       if (fontItalic) fontStyle += "font-style:italic; ";

       if (fontUnderline) fontStyle += "text-decoration:underline; ";

       if (fontBold) fontStyle += "font-weight:bold; ";

       

       

       // write CSS style for font style

       

       rcWriteCode(" style=\"");

       rcWriteCode(fontStyle);

       rcWriteCode("\" ");


In case you want to draw something with this font in the editor, in the .onPaintInEditor function, you can do it like this:

       // get font style

       

       var me = rcGetThisElement();                


       var fontName = rcGetElementProperty(me, "FontName");

       var fontSize = rcGetElementProperty(me, "FontSize");

       var fontBold = rcGetElementProperty(me, "FontBold");

       var fontItalic = rcGetElementProperty(me, "FontItalic");

       var fontUnderline = rcGetElementProperty(me, "FontUnderline");                

       var fontColor = rcGetElementProperty(me, "FontColor");


       // finally draw


       var text = "Hello World";

       var rect = rcGetLayoutRect(me);

                       

       rcDrawText(rect.x1, rect.y1, text, fontName, fontSize, fontColor, fontBold, fontItalic, fontUnderline);





rcWriteCode(text, noHTMLEncode)


Writes out HTML or CSS code to the target file.


Parameters:


Example:


In the onWriteHTML function, you can write "Hello World" like this:

       rcWriteCode("<div>Hello World!</div");






rcHTMLEncode(text)


Creates a HTML encoded string from an input string. For example for the text "<this & that>", it writes out "&lt;this &amp; that&gt;"


Parameters:

Returns:






rcGetHTMLElementId(elem)


In RocketCake, every element has it's own HTML Id. It can also be modified by the user. You can return the Id as string using this function.

Parameters:


Returns:


Example:

In the onWriteHTML function, you can write the div tag for your component like this, with the correct HTML id:


       // write HTML opening tag

       

       rcWriteCode("<div id=\"");

       rcWriteCode(rcGetHTMLElementId(rcGetThisElement()));

       rcWriteCode("\" >");


       // closing tag

       rcWriteCode("</div>");        






rcGetCSSStyleForPosition(elem)


Returns the user selected CSS styles for the position of the element.


Parameters:


Returns:


Example:

       // write div with CSS style for user selected position and background

       

       rcWriteCode("<div style=\"");

       rcWriteCode(rcGetCSSStyleForPosition(me));

       rcWriteCode(rcGetCSSStyleForBackground(me));

       rcWriteCode("\"> </div> ");






rcGetCSSStyleForBackground(elem)


Returns the user selected CSS styles for the background of the element.


Parameters:


Returns:


Example:


       // write div with CSS style for user selected position and background

       

       rcWriteCode("<div style=\"");

       rcWriteCode(rcGetCSSStyleForPosition(me));

       rcWriteCode(rcGetCSSStyleForBackground(me));

       rcWriteCode("\"> </div> ");





rcWriteHTMLOfChildElements(elem)


In the .OnWriteHTML function, this will cause child elements to write out their HTML code and css. This is useful when your element has child elements such as web form elements in a web form.


Parameters:


Example:


// called when HTML Code needs to be generated

test.prototype.onWriteHTML = function(isPreviewMode)

{

       var me = rcGetThisElement();

       

       // write HTML opening tag

       

       rcWriteCode("<div id=\"");

       rcWriteCode(rcGetHTMLElementId(me));

       rcWriteCode("\" >");

               

       // let child elements like the text and the button write out their html

       

       rcWriteHTMLOfChildElements(me);

       

       

       // closing tag

       rcWriteCode("</div>");        


}





rcWriteGlobalCSSOfChildElements(elem)


In the .OnWriteHTML function, this will cause child elements to write out their HTML code and css. This is useful when your element has child elements such as web form elements in a web form.


Parameters:


Example:


// called when HTML Code needs to be generated

test.prototype.onWriteHTML = function(isPreviewMode)

{

       var me = rcGetThisElement();

       

       // write HTML opening tag

       

       rcWriteCode("<div id=\"");

       rcWriteCode(rcGetHTMLElementId(me));

       rcWriteCode("\" >");

               

       // let child elements like the text and the button write out their html

       

       rcWriteHTMLOfChildElements(me);

       

       

       // closing tag

       rcWriteCode("</div>");        


}





rcAddFileWithTextContent(filename, text)


In the .OnWriteHTML function, this will cause a text file to be written out with the text content supplied. The function will return the web root relative filename used to create the file if successful.


Parameters:


Example:


// called when HTML Code needs to be generated

test.prototype.onWriteHTML = function(isPreviewMode)

{

       rcAddFileWithTextContent("hello.txt", "hello world!");        


}





rcSetHyperlink(elem, url)


Sets the hyperlink of an element. Unlike rcSetTextHyperlink, which sets the hyperlink in a part of the text.


Parameters:





rcSetTextEditType(elem, type)


Sets the type of an text edit web form element. 


Parameters:





rcGetElementFromId(id)


Returns a reference to the element represented by the specified id.


Parameters:




rcGetElementChildCount(elem)


Returns the amount of children this element has.


Parameters:




rcGetElementChild(elem, idx)


Returns the nth child of this element


Parameters:




rcGetElementParent(elem)


Returns the parent element of this element.


Parameters:




rcGetLayoutRect(elem)


Returns the visible rectangle coordinates of this element. Can be used to draw the rectangle of this element.


Parameters:

Returns:


Example:


test.prototype.onPaintInEditor = function()

{

       var me = rcGetThisElement();                

       var rect = rcGetLayoutRect(me);

       

       rcDrawElementBorder(me, rect);        

}





rcDrawElementBackgroundBoxShadow(elem, rect)


Draws the element's background box shadow, if the element was set in the editor to have a box shadow.  Should only be called in a onPaintInEditor() function.


Parameters:


Example:


test.prototype.onPaintInEditor = function()

{

       var me = rcGetThisElement();                

       var rect = rcGetLayoutRect(me);

       

       rcDrawElementBackgroundBoxShadow(me, rect);

       rcDrawElementBackground(me, rect);

       rcDrawElementBorder(me, rect);        

}





rcDrawElementBackground(elem, rect)


Draws the element's background as set in the editor by the user.  Should only be called in a onPaintInEditor() function.


Parameters:


Example:


test.prototype.onPaintInEditor = function()

{

       var me = rcGetThisElement();                

       var rect = rcGetLayoutRect(me);

       

       rcDrawElementBackgroundBoxShadow(me, rect);

       rcDrawElementBackground(me, rect);

       rcDrawElementBorder(me, rect);        

}





rcDrawElementBorder(elem, rect)


Draws the element's border as set in the editor by the user.  Should only be called in a onPaintInEditor() function.


Parameters:


Example:


test.prototype.onPaintInEditor = function()

{

       var me = rcGetThisElement();                

       var rect = rcGetLayoutRect(me);

       

       rcDrawElementBackgroundBoxShadow(me, rect);

       rcDrawElementBackground(me, rect);

       rcDrawElementBorder(me, rect);        

}





rcMeasureText(text, fontfamily, fontsize, fontbold, fontitalic, fontunderline)


returns the size of a text when drawn with the specified font settings. Should only be called in a onPaintInEditor() function.


Parameters:


Example:


test.prototype.onPaintInEditor = function()

{

       var me = rcGetThisElement();                

       var rect = rcGetLayoutRect(me);

               

       var fontName = rcGetElementProperty(me, "FontName");

       var fontSize = rcGetElementProperty(me, "FontSize");

       var fontBold = rcGetElementProperty(me, "FontBold");

       var fontItalic = rcGetElementProperty(me, "FontItalic");

       var fontUnderline = rcGetElementProperty(me, "FontUnderline");                

       var fontColor = rcGetElementProperty(me, "FontColor");

       

       // calculate position to draw it centered in the middle of the rectangle

       

       var text = "Hello World";

       

       // measure text size in order to draw it centered in element

       

       var size = rcMeasureText(text, fontName, fontSize, fontBold, fontItalic, fontUnderline);

       var posx = rect.x1 + ((rect.x2 - rect.x1) - size.x1) / 2;

       var posy = rect.y1;

       

       // finally draw

       

       rcDrawText(posx, posy, text, fontName, fontSize, fontColor, fontBold, fontItalic, fontUnderline);

}





rcDrawText(x,y, text, fontfamily, fontsize, fontColor, fontbold, fontitalic, fontunderline)


draws a text. Should only be called in a onPaintInEditor() function.


Parameters:


Example:


test.prototype.onPaintInEditor = function()

{

       var me = rcGetThisElement();                

       var rect = rcGetLayoutRect(me);

                       

       rcDrawText(rect.x1, rect.x2, "Hello World", "Arial", 12, new color(1.0, 0, 0), false);

}






rcDrawRectangle(color, x1, y1, x2, y2)


draws a rectangle. Should only be called in a onPaintInEditor() function.


Parameters:


Example:


test.prototype.onPaintInEditor = function()

{

       var me = rcGetThisElement();        

       var rect = rcGetLayoutRect(me);


       rcDrawRectangle(new color(1.0, 0, 0), rect.x1, rect.y1, rect.x2, rect.y2);

}







rcDrawLine(color, x1, y1, x2, y2)


draws a line. Should only be called in a onPaintInEditor() function.


Parameters:


Example:


test.prototype.onPaintInEditor = function()

{

       var me = rcGetThisElement();        

       var rect = rcGetLayoutRect(me);


       rcDrawLine(new color(1.0, 0, 0), rect.x1, rect.y1, rect.x2, rect.y2);

}









color class


The RocketCake API has a built-in color class, for getting and setting properties, mostly via rcSetElementProperty() and rcGetElementProperty().


You can create a new color by specifying float RGB values from 0.0 to 1.0:


var clr = new color(0.5, 0.5, 0.5);


It has a method getHTMLColor() It to return a HTML color string like "#ff00ab"


clr.getHTMLColor();


And a toString() function to create a string like "(1.0, 0.6, 0.5)" from its float values.


You can access the r, g, and b values using the properties .r, .g, and .b:


print(clr.r);





rect class


The RocketCake API has a built-in rect class, for getting and setting properties, mostly via rcSetElementProperty() and rcGetElementProperty().

You can create a new rect by specifying float position values:


var rct = new rect(10, 10, 200, 200);


You can access the position values using the properties .x1, y1, x2, and .y2:


print(rct.x1);




Copyright © by Ambiera e.U.