To bootstrap your project, you should use the play-cms-demo as your starting point. Once it's up and running, continue with the steps below.
To setup the cms programatically (wire up your own provider classes), you implement the ch.insign.cms.CMSApiLifecycle interface or override the ch.insign.cms.CMSApiLifecycleImpl class to change runtime settings, and implement the ch.insign.cms.models.Bootstrapper interface or override the ch.insign.cms.models.DefaultBootstrapper class to change the initial database content.
Registering Blocks
play-cms allows to change set of enabled blocks without modifying code. To do so you need to update application.conf of your play-cms instance and modify following settings
cms.blocks.enabled
cms.blocks.disabled
Both these settings accepts array of fully qualified block class names. By default following blocks are enabled:
ch.insign.cms.models.PageBlock
ch.insign.cms.models.ContentBlock
ch.insign.cms.models.CollectionBlock
ch.insign.cms.blocks.linkblock.LinkBlock
ch.insign.cms.blocks.backendlinkblock.BackendLinkBlock
ch.insign.cms.blocks.groupingblock.GroupingBlock
ch.insign.cms.blocks.sliderblock.SliderCollectionBlock
ch.insign.cms.blocks.searchresultblock.SearchResultBlock
ch.insign.cms.blocks.jotformpageblock.JotFormPageBlock
ch.insign.cms.blocks.errorblock.ErrorPage
Adding additional entries to the list of enabled blocks looks like following:
// Enable ReviewBlock
cms.blocks.enabled += "ch.insign.cms.blocks.reviewblock.models.ReviewBlock"
Similarly, disabling of any block might be done like this:
// Disable JotForms
cms.blocks.disabled += "ch.insign.cms.blocks.jotformpageblock.JotFormPageBlock"
Sometimes there might be situations when block availability should be controlled at runtime. For such cases play-cms provides BlockManager
class. It allows to enable blocks by calling BlockManager#register()
method. Here is an example of usage:
public void registerNewyearWidgetBlock() {
LocalDate currentDate = LocalDate.now();
if (currentDate.isAfter(LocalDate.of(currentDate.getYear(), 12, 1))
&& currentDate.isBefore(LocalDate.of(currentDate.getYear(), 12, 31))) {
blockManager.register(NewYearWidgetBlock.class);
}
}
Create your own error pages
Error pages are treated as normal cms pages. Create and return them initially form code - the admins can then modify them using the cms.
Add example data
This helps greatly during development of your project: Create some demo pages and content using your own blocks and design, and matching the final project's desired content. During development, you can then easily reset the db (call yourdomain.ext/reset) and will find your example content again.
Add your own content filters
Content filters are a great tool to let the user add e.g. variables freely inside any content, e.g. [[currentUserCount]] which your filter resolves to the current value when displaying the page.
CMSApiLifecycle example
app/MyCMSApiLifecycle.java:
@Singleton
public class MyCMSApiLifecycle extends CMSApiLifecycleImpl {
private final MyAuthenticationListener myAuthenticationListener;
private final PlayAuthApi playAuthApi;
@Inject
public MyCMSApiLifecycle(
JPAApi jpaApi,
ActorSystem actorSystem,
PlayAuthApi playAuthApi,
MyAuthenticationListener myAuthenticationListener
) {
super(jpaApi, actorSystem);
this.myAuthenticationListener = myAuthenticationListener;
this.playAuthApi = playAuthApi;
}
@Override
public void onStart(CMSApi cmsApi) {
super.onStart(cmsApi);
// set your own authentication listener
playAuthApi.getEventDispatcher().addSubscriber(loggingAuthenticationListener);
// change other settings here...
}
@Override
protected void registerContentFilters(CMSApi cmsApi) {
// Add your own content filters.
super.registerContentFilters(cmsApi);
cmsApi.getFilterManager().register(
MyEmoticonContentFilter.class
);
}
}
Bootstrapper example
app/MyCMSBootstrapper.java:
@Singleton
public class MyCMSBootstrapper extends DefaultBootstrapper implements Bootstrapper {
private PartyManager pm;
private PartyRoleManager prm;
private JPAApi jpaApi;
@Inject
public MyCMSBootstrapper(
AccessControlManager accessControlManager,
CMSApi cmsApi,
PartyManager partyManager,
PartyRoleManager partyRoleManager,
JPAApi jpaApi
) {
super(accessControlManager, cmsApi, partyRoleManager, jpaApi);
this.pm = partyManager;
this.prm = partyRoleManager;
this.jpaApi = jpaApi;
}
/**
* Load essential data which is required for all configured sites to function properly.
*
* Used to perform an initial project bootstrap or to reload it to the initial state.
*/
@Override
public synchronized void loadEssentialData() {
super.loadEssentialData();
}
/**
* Load example data for all configured sites.
*/
@Override
public synchronized void loadExampleData() {
super.loadExampleData();
}
/* Override DefaultBootstrapper methods:
* The DefaultBootstrapper defines more fine grained methods
* which are called by DefaultBootstrapper.load*Data methods
* so it may be easier to override them if small changes required.
*/
/**
* Delete data created by loadEssentialData
*/
@Override
protected void deleteEssentialData() {
super.deleteEssentialData();
}
/**
* Delete data created by deleteExampleData
*/
@Override
protected void deleteExampleData() {
super.deleteExampleData();
}
/**
* Add navigation entries in the backend
*/
@Override
protected void createBackendNavigation() {
super.createBackendNavigation();
}
@Override
protected ErrorPage createErrorPageNotFound(Sites.Site site) {
return super.createErrorPageNotFound(site);
}
@Override
protected ErrorPage createErrorPageUnavailable(Sites.Site site) {
return super.createErrorPageUnavailable(site);
}
@Override
protected ErrorPage createErrorPageInternalServerError(Sites.Site site) {
return super.createErrorPageInternalServerError(site);
}
@Override
protected ErrorPage createErrorPageForbidden(Sites.Site site) {
return super.createErrorPageForbidden(site);
}
@Override
protected void createPartyRoles() {
super.createPartyRoles();
// add more user roles
}
@Override
protected void createParties() {
super.createParties();
// add more users
}
}
The CMSApiLifecycle
and Bootstrapper
implementations are configured as DI bindings in ch.insign.cms.inject.CmsApiModule
and ch.insign.cms.inject.BootstrapperModule
correspondingly, so they should also be overridden by implementing custom play.api.inject.Module
, enabling them in the application.conf and also disabling the overridden modules, e.g.:
conf/application.conf
# Override CmsApiModule
play.modules.disabled += "ch.insign.cms.inject.CmsApiModule"
play.modules.enabled += "my.CmsApiModule"
# Override BootstrapperModule
play.modules.disabled += "ch.insign.cms.inject.BootstrapperModule"
play.modules.enabled += "my.BootstrapperModule"
The cms uses configuration values defined in play-cms/conf/application.conf. You can override them in your global application.conf.
play-cms/conf/application.conf:
# play-cms default configuration
application.router=cms.Routes
# CMS config values.
# Always access these using Cms.getConfig().*
cms.deleteWithoutTrashBin = false
cms.enableResetRoute = false
From code, config values can be accessed using CMSApi#getConfig().*