diff --git a/handbook/handbook.xml b/handbook/handbook.xml new file mode 100644 index 0000000..2cbaecb --- /dev/null +++ b/handbook/handbook.xml @@ -0,0 +1,257 @@ + + + + + + Obsidian Workspaces Handbook + + + Sébastien + Santoro + + dereckson@espace-win.org + + + + Preface + + About Obsidian Workspaces + Obsidian Workspaces is an modular application and PHP framework to creates intranet, workspaces and collaborative sites. + It uses concepts like documents collections, applications and workspaces to allow to create with the minimum of configuration and few development CRUD interfaces and dashboards. + + + Intended audience + The handbook Obsidian Workspaces intended audience is the system administrator, developer or user. + It's divided in several parts each targeted to one of these three activities. + + + + Workspaces administrator guide + + Collections + + Collections description + + A collection is a set of documents + [...] + + + A collection could be stored in several ways, and is independant of the storage strategy. + [...] + + + Terminology equivalents + The Obsidian Workspaces collection is the equivalent of a SharePoint list. Each collection document could be consided as matching a content type. + + + + Configuration + + Add a collection to a workspace application + + Workspace collections block sample + This configuration snippet declares two collection, library_books and library_periodics, both using the + BookDocument documen + type."collections": [ + { + "name": "library_books", + "documentType": "BookDocument" + }, + { + "name": "library_periodics", + "documentType": "BookDocument" + } +] + + + Workspace applications block sample + To tell an application to use collections: + + { + "name": "MyLibraryApplication", + [...] + "useCollections": { + "books": "library_books", + "periodics": "library_periodics" + } + } + + + + + + + Naming prefix + By default, your collection name is automatically prepended by the workspace + code, with a dash as separator. + For example, if you define a books + collection in the workspace library, the + collection name will be library-books. + If you wish to use a collection accross different workspaces, you need to define the global property, and set it as true. + + + Naming conventions + Depending of the storage engine, the collection name could be stored: + + as the value of a relational database collection_id text + field + + + as the name of a MongoDB collection + + + as the name of a filesystem directory + + + An efficient naming strategy is to only use A-Z a-z latin non accentuated + letters, 0-9 arab digits, dashes and underscore, and to start the collection + name by a letter. For example books, + Books, books-2037 are good collection names. + But you aren't restricted to adhere to this suggested scheme. Obsidian + supports arbitrary UTF-8 string for collection names, with some extra + limitations according the storage engine you pick. + If you wish your collection name to works without issue with every storage + engine, this implies some constraints on the characters you can use to name your collections: + + The MongoDB restrictions on collections names: + + + it can't contain a $ + + + it can't contain the null (\0) character + + + it must start by _ or a letter + + + it can't start with system + + + the namespace (database name, a dot, and collection + name) length is limited to 123 bytes (123 ASCII + characters, but UTF-8 characters could so fill more + quicker) ; databases name are limited to 63 characters + and you have to add the workspace code prefix, so try to + fit in 31 characters. + + + + + The filesystem restrictions on collections names: + + + on Windows, collection names are limited to 255 + characters, including the appended workspace + prefix + + + + + on Windows, for NTFS partitions, control characters + and / ? < > \ : * | ” are forbidden; FAT + furthermore forbids ^ ; names can't end by a space or a + by a dot + + + on UNIX, any character could be used, but avoid + / + + + on Mac OS X, you can't use the :, it's the legacy Mac + OS directory separator + + + it must start by _ or a letter + + + it can't start with system + + + + + + + + + + Developer guide + + Application walkthrough + + Introduction + This application were built on the top of the Keruald MVC starter kit, so you can read the following document to have an overview of what happens in the application: + Keruald start process — Application entry point walkthrough + [This is a placeholder for further notes, for example about the configuration files load, and the workspaces configuration file reading workflow] + + + + Extend the core + + Create an engine storage + [This is a placeholder for further notes to add an engine storage class. Meanwhile, look the existing code in includes/collection folder] + + + Authentication + + Create a remote identity provider + + + Use the remote identity provider + The authentication is scoped by workspace + The workspaces administrator guide describes how to configure an authentication provider. + + + + Create an user action + Obsidian Workspaces allows to automatically run actions when an user logs in, typically from an external source. + + + + + Code conventions + + Whitespaces + Indentation isn't done with tabulations, but with 4 whitespaces per level. + We follow the UNIX convention and use \n to return. + No whitespace should be present at the end of a line. + Each file should be ended by a new line. + + + PHP code + Brackets starts on the line. + Format your code the more clearer and easy to read way, following our bracked opened on the block declaration line style. + Don't end files by ?>, it avoids to introduce extra whitespaces in the page output. + + + L10n files + CamelCase is used for the keys, generally concatening the English sentence without articles. + + + + + Annexes + + + Software manuals and references + + MongoDB Manual, Limits + MongoDB Limits and Thresholds + MongoDB Manual + MongoDB + + + MSDN aa365247(VS.85) + Naming Files, Paths, and Namespaces + MSDN Library + Microsoft + 2013-05-12 + + + + +