added check_plain() to form title and description fields
[project/context_field.git] / README.txt
1 I. Installation
2 --------------------------------------
3 Install and enable the following modules, preferably using Drush:
4 * Context (7.x-3.0-beta2 and up) http://drupal.org/project/context
5 * Context UI (included as a sub-module in Context)
6 * Context Field (7.x-1.0-beta1 and up) http://drupal.org/project/context_field
7
8 * Boxes (7.x-1.0-beta5 and up) http://drupal.org/project/boxes
9 * Views (7.x-3.0-rc1 and up) http://drupal.org/project/views
10 * Ctools (7.x-1.0-rc1 and up) http://drupal.org/project/ctools
11 * Entity Autocomplete (7.x-1.0-beta1 and up) http://drupal.org/project/entity_autocomplete
12
13 * Views Boxes (7.x-1.0-beta4 and up) http://drupal.org/project/views_boxes
14 * Views Arguments Extras (7.x-1.0-beta1 and up) http://drupal.org/project/views_arguments_extras
15
16
17 II. Using Context Field
18 --------------------------------------
19 In this tutorial, we're going to enhance the basic page content type with
20 Context Field so that each new page will have its own automatically
21 created context.
22
23 * Go to /admin/structure/types and click 'manage fields' on Basic page.
24
25 * Add a new field of the Context type, and set the options dropdown to 
26   Auto Create, then save.
27
28 * On the follow-up page, click 'Save field settings'.
29
30 * You'll then see a number of ways to configure how this specific field
31   behaves. The Default Context is the one that ships with the module, 
32   and we will set the use to 'Clone default context on Entity Creation', 
33   meaning we'll a new copy of that one for each page we create.
34   Alternatively, we can pick 'Always use Default Context' to essentially
35   reference one specific context for all page nodes. Once you've decided
36   on this, save your settings.
37
38 * Create and save a test page node.
39
40 * You'll notice the 'Configure layout' link when you view the node.
41   If not, make sure that your role has the 'Use Context Field Editor'
42   permission. Click on that link.
43
44 * You are now in context editing mode, with the editor widget to the
45   right of your screen. You can now use the dropdown to filter on the
46   category of block-type items that you can then drag and drop into
47   the region of your choice. If you've used Context UI before, this
48   should be familiar to you. For testing purposes, Select User in
49   the dropdown then drag and drop "Who's Online" into the Featured
50   region. The block will then render its contents.
51
52 * Any changes made to the currently selected context (viewable in
53   the Context Field editor) will need to get saved by clicking 'Done'
54   and then 'Save changes'. Should your current page have multiple
55   contexts, you can edit a specific one by clicking the corresponding
56   'Edit' button next to it in the editor.
57
58 * You can minimize the Context Editor by clicking its grey title bar,
59   and you can get out of the context editing mode by clicking the 'X'.
60
61
62 III. Using Views Boxes with Context Field
63 --------------------------------------
64 Now let's make this interesting and use the Context Editor with
65 some Views Boxes.
66
67 III.A. Basic use:
68 --------------------------------------
69 * Enter a couple of article nodes (just set the titles for now).
70
71 * Make sure you have Views UI enabled and then create a new view
72   (called list_articles) with a block display that returns the titles
73   of your published articles.
74
75 * Go back to your test page and reclick 'Configure Layout'.
76
77 * Select Boxes in the editor's dropdown, and then drag and drop
78   'Add custom view box' into a region.
79
80 * You'll be prompted to set the box's description (which is used
81   for admin UI purposes) and its title (which is actually rendered
82   and shown to end users). Set the title to <none> and the description
83   to 'Views Box - Articles' and then click Continue.
84
85 * The 'View' dropdown shown then allows you to pick the block display
86   you want this box instance to use. For now, we just have list_articles
87   which doesn't have any exposed or contextual filters, so we can go
88   ahead and save our settings.
89
90 * You'll now see your list of articles.
91
92 III.B. Exposed and contextual filters:
93 --------------------------------------
94 Views Boxes ships with some filters that are particularly useful for 
95 allowing extra levels of control over your view while still storing
96 the configuration data in the box itself. We're going to cover the ability
97 to curate this list_articles so that we can manually sort the article nodes
98 through the box. For this, we're going to install the Views Arguments Extras
99 module as it provides some filters that we'll need.
100
101 * Go edit the list_articles view.
102
103 * Add a contextual filter and select 'Content: Nid'. Before you save it,
104   scroll down and open up the 'More' options.
105
106 * The administrative title can be used for two purposes: displaying what it
107   is that we'll be selecting (Article nodes) to the admin when using the box,
108   and to limit the autocomplete fields we'll have to specific entities and
109   bundles. By default the autocomplete field will display all nodes, but if
110   we want to restrict it to articles, we'd enter: 
111   Article nodes [node] {bundles:article} here
112
113 * Check the 'Allow multiple values' option and save your changes.
114
115 * Add a sort criteria and select 'Arguments: Multi-item Argument Order'.
116   This insures that we're actually sorting using the nodes we'll be selecting
117   through the contextual filter in the box. Make sure that this sort criteria
118   comes before the existing 'Content: Post date' and it's set to
119   'sort descending'. Save your changes to the view and go back to your page
120   node with the list_articles view block.
121
122 * Edit the box by clicking the gear icon that appears when you hover over it
123   and then selecting 'Edit Box'. Notice that you don't necessarily need to be
124   in Context Editor mode to edit existing boxes.
125
126 * You'll notice that you now get 'Article Nodes' under settings for the box,
127   which allows you to pick article nodes using the autocomplete fields and to
128   order them as you'd like. Once you're done with this, save the changes and
129   you'll get your manually reordered list.
130
131 * You can reuse the same box instance or another page if you want to keep the
132   same ordered list, but you can also create a new custom view box that reuses
133   the same view display but with a different selection of nodes. This allows
134   for a pretty powerful way to make views configurable through the box interface
135   while still keeping the benefits of reusing the same displays (templates
136   for examples). Other filters can be exposed too and used through the box
137   interface, and having a view box filter on a specific taxonomy term can be
138   achieved in a similar manner.
139
140 Documentation written by tirdadc - http://drupal.org/user/383630