As you may know, a region is actually a div. With the region type plug-in you can customize this div. And because it is a plug-in, you can reuse it in other pages. You also have the possibility to make the div look better by using JavaScript libraries. In this recipe, we will make a carousel with switching panels. The panels can contain images but they can also contain data from a table. We will make use of another jQuery extension, Stepcarousel.
You can download stepcarousel.js from http://www.dynamicdrive.com/dynamicindex4/stepcarousel.htm. However, in order to get this recipe to work in APEX, we needed to make a slight modification in it. So, stepcarousel.js, arrowl.gif, and arrow.gif are included in the download bundle of this book.
- First, we will create the plug-in. Go to shared components and click on the plug-ins link.
- Click the Create button.
- In the Name section, enter a name for the plug-in in the Name field. We will use Carousel.
- In the Internal name text field, enter a unique internal name. It is advised to use your domain reversed, for example, com.packtpub.carousel.
- In the type list box, select Region.
- In the Source section, enter the following code in the PL/SQL code text area:
function render_stepcarousel ( p_region in apex_plugin.t_region, p_plugin in apex_plugin.t_plugin, p_is_printer_friendly in boolean ) return apex_plugin.t_region_render_result is cursor c_crl is select id , panel_title , panel_text , panel_text_date from app_carousel order by id; -- l_code varchar2(32767); begin [render_stepcarousel.sql]
The function starts with a number of arguments. These arguments are mandatory but have a default value. In the declare section, there is a cursor with a query on the table APP_CAROUSEL. This table contains several data to appear in the panels in the carousel.
-- add the libraries and stylesheets -- apex_javascript.add_library ( p_name => 'stepcarousel', p_directory => p_plugin.file_prefix, p_version => null ); -- --Output the placeholder for the region which is used by the Javascript code [Render_stepcarousel.sql]
The actual code starts with the declaration of stepcarousel.js. There is a function, APEX_JAVASCRIPT.ADD_LIBRARY to load this library. This declaration is necessary but this file needs also to be uploaded in the next step. You don't have to use the extension .js here in the code.
--
sys.htp.p('<style type="text/css">'),
--
sys.htp.p('.stepcarousel{'),
sys.htp.p('position: relative;'),
sys.htp.p('border: 10px solid black;'),
sys.htp.p('overflow: scroll;'),
sys.htp.p('width: '||p_region.attribute_01||'px;'),
sys.htp.p('height: '||p_region.attribute_02||'px;'),
sys.htp.p('}'),
--
sys.htp.p('.stepcarousel .belt{'),
sys.htp.p('position: absolute;'),
sys.htp.p('left: 0;'),
sys.htp.p('top: 0;'),
sys.htp.p('}'),
sys.htp.p('.stepcarousel .panel{'),
sys.htp.p('float: left;'),
sys.htp.p('overflow: hidden;'),
sys.htp.p('margin: 10px;'),
sys.htp.p('width: 250px;'),
sys.htp.p('}'),
--
sys.htp.p('</style>'),
[render_stepcarousel.sql]
After the loading of the JavaScript library, some style elements are put on the screen. The style elements could have been put in a Cascaded Stylesheet (CSS) but since we want to be able to adjust the size of the carousel we use two parameters to set the height and width. And the height and the width are part of the style elements.
--
sys.htp.p('<div id="mygallery" class="stepcarousel" style="overflow:hidden"><div class="belt">'),
--
for r_crl in c_crl
loop
sys.htp.p('<div class="panel">'),
sys.htp.p('<b>'||to_char(r_crl.panel_text_date,'DD-MON-YYYY')||'</b>'),
sys.htp.p('<br>'),
sys.htp.p('<b>'||r_crl.panel_title||'</b>'),
sys.htp.p('<hr>'),
sys.htp.p(r_crl.panel_text);
sys.htp.p('</div>'),
end loop;
--
sys.htp.p('</div></div>'),
[render_stepcarousel.sql]
The next command in the script is the actual creation of a div. Important here is the name of the div and the class. The stepcarousel searches for these identifiers and replaces the div with the stepcarousel. The next step in the function is the fetch of the rows from the query in the cursor. For every line found, the formatted text is placed between the div tags. This is done so that stepcarousel recognizes that the text should be placed on the panels.
--Add the onload code to show the carousel
--
l_code := 'stepcarousel.setup({
galleryid: "mygallery"
,beltclass: "belt"
,panelclass: "panel"
,autostep: {enable:true, moveby:1, pause:3000}
,panelbehavior: {speed:500, wraparound:true, persist:true}
,defaultbuttons: {enable: true, moveby: 1, leftnav: ["'||p_plugin.file_prefix||'arrowl.gif", -5, 80], rightnav: ["'||p_plugin.file_prefix||'arrowr.gif", -20, 80]}
,statusvars: ["statusA", "statusB", "statusC"]
,contenttype: ["inline"]})';
--
apex_javascript.add_onload_code (p_code => l_code);
--
return null;
end render_stepcarousel;
[render_stepcarousel.sql]
The function ends with the call to apex_javascript.add_onload_code. Here starts the actual code for the stepcarousel and you can customize the carousel, like the size, rotation speed, and so on.
- Click the Create button.
- In the callbacks section, enter the name of the function in the return function name text field. In this case, it is render_stepcarousel.
- In the files section, upload the files stepcarousel.js, arrowl.gif and arrowr.gif.
Note
For this purpose, the file stepcarousel.js has a little modification in it. In the last section (setup:function), document.write is used to add some style to the div. Unfortunately, this will not work in APEX, as document.write somehow destroys the rest of the output. So, after the call, APEX has nothing left to show, resulting in an empty page. Document.write needed to be removed and the style elements need to be added in the code of the plug-in:
sys.htp.p('<div id="mygallery" class="stepcarousel" style="overflow:hidden"><div class="belt">'),
In this line of code you see style='overflow:hidden'. That is the line that actually had to be included in stepcarousel.js. This command hides the scrollbars.
- After you have uploaded the files, click the Apply changes button. The plug-in is ready and now we can use it in a page.
- Go to the page where you want this stepcarousel to be shown.
- In the regions section, click the Add icon.
- In the next step, select Plug-ins.
- Select Carousel.
- Click Next.
- Enter a title for this region, for example Newscarousel. Click Next.
- In the next step, enter the height and the width of the carousel. To show a carousel with three panels, enter 800 in the width text field. Enter 100 in the height text field. Click Next.
- Click the Create region button.
- The plugin is ready. Run the page to see the result.
The stepcarousel is actually a div. The region type plug-in uses the function sys.htp.p to put this div on the screen. In this example, a div is used but for the region, but also a HTML table can be used. An APEX region can contain any HTML output but for the positioning, mostly a HTML table or a div is used, especially when layout is important within the region.
The apex_javascript.add_onload_code starts the animation of the carousel. The carousel switches panels every three seconds. This can be adjusted (pause:3000).
For more information on this jQuery extension, go to http://www.dynamicdrive.com/dynamicindex4/stepcarousel.htm.