]project-open[ My First Package


Published on

This tutorial guides you through the process of creating a new package in ]project-open[ and explains how to distribute the new package.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

]project-open[ My First Package

  1. 1. My First Package The ]project-open[ Data-Model , Frank Bergmann, 2010-10-05 Creating a “Hello World” package in ]project-open[.
  2. 2. Creating a New “foo-bar” Package <ul><li>We will use the „Package Manager“ to create a new package: </li></ul><ul><li>]po[ Home -> Admin -> OpenACS Package Manager </li></ul><ul><li>The Package Manager shows the list of currently installed packages. </li></ul><ul><li>-> Create a new package (at the end of the page) </li></ul><ul><li>Example Package: </li></ul><ul><ul><li>We will use „Foo“ as our „organization“ name. „Foo“ stands for „First Object Organization“ </li></ul></ul><ul><ul><li>We will use „bar“ as the package name. „Bar“ stands for „Business Application Resources“. </li></ul></ul>
  3. 3. Creating a New “foo-bar” Package <ul><li>Package Key „foo-bar“: Organization name – Package name for customer packages. OpenACS “kernel” packages are prefixed with “acs-*”. ]project-open[ packages are prefixed with “intranet-*”. </li></ul><ul><li>Package Name „First Object Organization – Business Application Resources“ </li></ul><ul><li>Package Plural Same as Package Name </li></ul><ul><li>Package Type Please always choose „Application“ if your package includes TCL/ADP pages </li></ul><ul><li>OpenACS Core? No (unchecked): </li></ul><ul><li>Singleton Yes (checked): All ]po[ are singleton. This means that you can only install one instance of the package in the system </li></ul><ul><li>Auto-mount URI „foo-bar“: Same as Package Key by default. This URI determines where the new package will be „mounted“ (i.e. http://localhost/foo-bar/) </li></ul><ul><li>Package URL „http://foo.com/repository/apm/packages/foo-bar“ This is the place where users could download new versions of the package in the future. Not relevant currently, except if you want the OpenACS community to include your package in their distribution </li></ul><ul><li>Initial Version „0.1d“: Please enter a version string. Normally, versions should look like „1.2.3“. A final „d“ indicates a developer version. </li></ul><ul><li>Version URL „http://foo.com/repository/apm/packages/foo-bar-0-1d.apm“ (automatically created by the Package Manager) </li></ul><ul><li>Summary „Provides important application resources for businesses“ A one paragraph description for users who have never before heard about your package </li></ul><ul><li>Description More extended description </li></ul><ul><li>Primary Owner “Peter Pan” </li></ul><ul><li>Primery Ownwer URL “mailto:ppan@milkyway.com” </li></ul><ul><li>Secondary Owner “” </li></ul><ul><li>Secondary Owner URL “” </li></ul><ul><li>Vendor “First Object Organization” </li></ul><ul><li>Vendor URL http://www.foo.com/ </li></ul><ul><li>Please note that you won’t be able to change Package Key and Auto-Mount URI after creating the package. </li></ul><ul><li>You can change all other values during development, so don’t worry too much about them now. </li></ul>
  4. 4. “ foo-bar” Post-Creation Actions <ul><li>You will need to “mount” the package after creation (OpenACS doesn’t mount the package during package creation…) </li></ul><ul><ul><li>Package Manager => foo-bar => “Uninstall this package from your System” => (no restart necessary) </li></ul></ul><ul><ul><li>Package Manager => Install Packages => Check “foo-bar” => Next => Restart Server </li></ul></ul><ul><li>Please check your /packages/ folder. OpenACS has created a default folder structure for the new package: </li></ul><ul><ul><li>/packages/foo-bar/ Main folder for the package </li></ul></ul><ul><ul><li>/packages/foo-bar/sql/ </li></ul></ul><ul><ul><li>/packages/foo-bar/sql/postgresql/ PostgreSQL specific creation and drop scripts </li></ul></ul><ul><ul><li>/packages/foo-bar/sql/oracle/ Oracle specific data-model, not used in ]po[ at the moment </li></ul></ul><ul><ul><li>/packages/foo-bar/tcl/ TCL Libraries for the package </li></ul></ul><ul><ul><li>/packages/foo-bar/tcl/test/ Not used in ]po[ usually </li></ul></ul><ul><ul><li>/packages/foo-bar/www/ Place your TCL/ADP pages here! </li></ul></ul><ul><ul><li>/packages/foo-bar /www/doc/ HTML package documentation </li></ul></ul><ul><li>Create a test page </li></ul><ul><ul><li>Please use your favorite editor and create a file /packages/foo-bar/www/index.adp with the contents: “<h1>Hello World</h1>” </li></ul></ul><ul><ul><li>Now enter the URL: http://localhost/foo-bar/index. You should see “Hello World”. </li></ul></ul><ul><ul><li>In case of issues please consult the error.log file in /log/error.log </li></ul></ul><ul><li>Congratulations, your first page of your first package is working! </li></ul>
  5. 5. Distributing Your foo-bar Package <ul><li>To distribute your package it is sufficient to “zip” or “tar” the /packages/foo-bar content: </li></ul><ul><ul><li>cd ~/packages/ </li></ul></ul><ul><ul><li>tar czf foo-bar.0-1d.tgz foo-bar (please observe the standard for naming packages .tgz files). </li></ul></ul><ul><li>Windows users: Please make sure your package files use Linux style line breaks. In editors like “TextPad” you can choose between Windows line breaks (CR-LF) and Linux (LF only). </li></ul>
  6. 6. Publishing Your foo-bar Package <ul><li>We (the ]po[ core team) can publish your </li></ul><ul><li>package on the www.project-open.org if you want: </li></ul><ul><li>Please contact [email_address] for a user account on www.project-open.org with edit permissions on the Wiki. </li></ul><ul><li>We will create two new Wiki pages for you: </li></ul><ul><ul><li>package_foo_bar: A page for your new package. </li></ul></ul><ul><ul><li>partner_foo: A page to present your organization </li></ul></ul><ul><li>Please include specific information on your package_foo_bar page about the purpose of the package, the target sector (ITSM, Translation, ALM, …), license, preconditions etc. </li></ul><ul><li>Please clearly state the development status/maturity of your package and if the package DOES NOT support one of the “packge services” listed on the next page. </li></ul>
  7. 7. Package “Services” Overview <ul><li>]project-open[ packages need to “live together” with other packages in a customer’s server. </li></ul><ul><li>There are certain expectations of ]po[ users on how a package should integrate with other packages. These “expectations” can be summarized as a number of “services” that a package should use in order to provide a look-and-feel like other packages: </li></ul><ul><ul><li>Pages – You may want to show the user information about business objects and/or allow the user to take actions. </li></ul></ul><ul><ul><li>Templates and the ]po[ design – Integrate your package seamlessly into ]po[ </li></ul></ul><ul><ul><li>Portlet Component – You may whish to show information from your package in other pages, such as the ProjectViewPage (/intranet/projects/view) etc. </li></ul></ul><ul><ul><li>Business Objects and Data-Model – You will probably need to create database tables in order to store information of your package. </li></ul></ul><ul><ul><li>Libraries – Libraries consist of procedures and functions to be used by pages or by other packages. </li></ul></ul><ul><ul><li>Menu Tab – You may want to create a new Tab in the menu bar so that users can get to your package. </li></ul></ul><ul><ul><li>Permissions – You may want to restrict access to your business objects </li></ul></ul><ul><ul><li>Localization – Allow users to translate your package into different languages </li></ul></ul><ul><ul><li>Categories – Categories represent the value of drop-down boxes. You may want to use ]po[ categories to define status, type and other information about business objects in your package, so that Application Administrators can configure your package using the standard ]po[ administration screens </li></ul></ul><ul><ul><li>Parameters – You may want to allow an Application Admin to modify behavior of your business logic. Generally, parameters allow you to eliminate hard-coding values in your package code. </li></ul></ul><ul><ul><li>New & Edit Pages – Allow the user to create and modify business objects. (=> Form Builder) </li></ul></ul><ul><ul><li>View Pages – Allow the user to see the contents of a business object (=> Portlet Layout) </li></ul></ul><ul><ul><li>List Pages – Allow the user to see lists of business objects (=> List Builder) </li></ul></ul><ul><ul><li>Reports – Allow the user to extract lengthy reports about your business objects </li></ul></ul><ul><ul><li>Full-Text Search Engine – You may want to let users search for contents in your package </li></ul></ul><ul><ul><li>Automatic developer documentation </li></ul></ul><ul><ul><li>Mail – Send and receive emails </li></ul></ul><ul><ul><li>Notifications – Allow your users to fine-tune the amount email notifications they are interested in </li></ul></ul><ul><ul><li>Calendar – Provide your users with a calendar view to their business objects </li></ul></ul><ul><ul><li>Dynamic Fields – Allow Application Admins to extend your business objects with dynamic fields </li></ul></ul><ul><ul><li>DynViews – Allow App Admins to modify the columns displayed by ListPages </li></ul></ul><ul><ul><li>Web-Services – Exchange information with external applications </li></ul></ul><ul><ul><li>Workflow – You may want to start workflows when creating new objects in your package </li></ul></ul><ul><ul><li>Finance – Create financial items that represent the economic impact of actions represented by business objects </li></ul></ul>
  8. 8. Frank Bergmann [email_address] www.project-open.com